Voice Design API reference - Alibaba Cloud Model Studio

User guide: Voice Design.

Endpoint

Singapore
China (Beijing)

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customizationReplace {WorkspaceId} with your actual workspace ID.

Alibaba Cloud Model Studio has released workspace-specific domains for the China (Beijing) and Singapore regions. The new dedicated domains deliver superior performance and higher stability for inference requests. We recommend migrating to the new domains:

China (Beijing): from dashscope.aliyuncs.com to {WorkspaceId}.cn-beijing.maas.aliyuncs.com
Singapore: from dashscope-intl.aliyuncs.com to {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

Replace {WorkspaceId} with your actual Workspace ID. The existing domains remain fully functional.

Request headers

Parameter	Type	Required	Description
Authorization	string	Yes	Set to `Bearer <your_api_key>`. Replace `<your_api_key>` with your API key.
Content-Type	string	Yes	Media type of the request body. Set to `application/json`.

Create a voice

Request body

modelstring(Required)The voice design model. Valid values:

voice-enrollment: Qwen-Audio-TTS/CosyVoice voice design.
qwen-voice-design: Qwen voice design.

inputobject(Required)The input parameter object.

Properties

action string(Required)The operation type.

Qwen-Audio-TTS/CosyVoice (voice-enrollment): Set to create_voice.
Qwen (qwen-voice-design): Set to create.

target_model string(Required)The text-to-speech (TTS) model for the voice. Must match the model in TTS API calls, or synthesis fails.qwen-audio-3.0-tts-plus and qwen-audio-3.0-tts-flash do not support Voice Design.voice_prompt string(Required)Description of desired voice characteristics. Chinese and English only.

Qwen-Audio-TTS/CosyVoice (voice-enrollment): Maximum 500 characters.
Qwen (qwen-voice-design): Maximum 2,048 characters.

preview_text string(Required)The text for the preview audio.

Qwen-Audio-TTS/CosyVoice (voice-enrollment): Maximum 200 characters. Chinese and English are supported.
Qwen (qwen-voice-design): Maximum 1,024 characters. Chinese, English, German, Italian, Portuguese, Spanish, Japanese, Korean, French, and Russian are supported.

prefix string(Conditionally required)

Only applicable to Qwen-Audio-TTS/CosyVoice (when model is voice-enrollment).

Voice name prefix. Alphanumeric only, max 10 characters. Generated name format: {target_model}-vd-{prefix}-{unique_id}preferred_name string(Conditionally required)

Only applicable to Qwen (when model is qwen-voice-design).

Voice name prefix. Alphanumeric and underscores, max 16 characters.language_hints array[string](Optional)

Only applicable to Qwen-Audio-TTS/CosyVoice (when model is voice-enrollment).

Language hint for voice generation. Must match the language of preview_text.Currently, only the first element is used.Valid values:

zh: Chinese
en: English

Default: ["zh"].language string(Optional)

Only applicable to Qwen (when model is qwen-voice-design).

Language hint for voice generation. Must match the language of preview_text.Valid values:

zh: Chinese
en: English
de: German
it: Italian
pt: Portuguese
es: Spanish
ja: Japanese
ko: Korean
fr: French
ru: Russian

Default: zh.

parametersobject(Optional)Configuration for voice design.

Properties

sample_rate int(Optional)Sample rate of the preview audio, in Hz.

Qwen-Audio-TTS/CosyVoice: 16000, 24000, or 48000.
Qwen: 8000, 16000, 24000, or 48000.

Default: 24000.response_format string(Optional)Format of the preview audio.

Qwen-Audio-TTS/CosyVoice: pcm, wav, or mp3.
Qwen: pcm, wav, mp3, or opus.

Default: wav.

Qwen-Audio-TTS/CosyVoice Voice Design is available only in the Beijing region. Qwen Voice Design supports the Singapore region. The Qwen-Audio-TTS/CosyVoice examples below use the China (Beijing) region URL. The Qwen examples below use the Singapore region URL (replace {WorkspaceId} with your actual workspace ID).

curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "voice-enrollment",
    "input": {
        "action": "create_voice",
        "target_model": "cosyvoice-v3.5-plus",
        "voice_prompt": "A composed middle-aged male announcer with a deep, rich and magnetic voice, a steady speaking speed and clear articulation, is suitable for news broadcasting or documentary commentary.",
        "preview_text": "Dear listeners, hello everyone. Welcome to the evening news.",
        "prefix": "announcer",
        "language_hints": ["en"]
    },
    "parameters": {
        "sample_rate": 24000,
        "response_format": "wav"
    }
}'

Response body

request_idstringThe unique identifier of this request.outputobjectThe data returned by the model.

Properties

voice_id / voicestringQwen-Audio-TTS/CosyVoice returns voice_id; Qwen returns voice. Pass this value as the voice parameter in TTS API calls.preview_audioobjectThe preview audio data.

Properties

data stringThe preview audio data, Base64-encoded.sample_rate intThe sample rate of the preview audio, in Hz.response_format stringThe format of the preview audio.

target_modelstringThe TTS model that drives the voice.

usageobjectUsage information for this request.

Properties

count integerThe number of voices created. Always 1.

{
    "output": {
        "preview_audio": {
            "data": "{base64_encoded_audio}",
            "sample_rate": 24000,
            "response_format": "wav"
        },
        "target_model": "cosyvoice-v3.5-plus",
        "voice_id": "cosyvoice-v3.5-plus-vd-announcer-xxxxxx"
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

Qwen-Audio-TTS/CosyVoice returns the voice_id field, while Qwen returns the voice field.

List voices

Request body

modelstring(Required)The voice design model. Valid values:

voice-enrollment: Qwen-Audio-TTS/CosyVoice voice design.
qwen-voice-design: Qwen voice design.

inputobject(Required)The input parameter object.

Properties

action string(Required)The operation type. Qwen-Audio-TTS/CosyVoice: list_voice. Qwen: list.prefix string(Optional)

Only applicable to Qwen-Audio-TTS/CosyVoice.

Filter voices by name prefix.page_index integer(Optional)The page index.page_size integer(Optional)The number of entries per page.

curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "voice-enrollment",
    "input": {
        "action": "list_voice",
        "prefix": "myvoice",
        "page_size": 10,
        "page_index": 0
    }
}'

Response body

request_idstringThe unique identifier of this request.outputobjectThe data returned by the model.

Properties

page_indexinteger

Returned by Qwen only.

The current page index.page_sizeinteger

Returned by Qwen only.

The number of entries per page.total_countinteger

Returned by Qwen only.

The total number of voices.voice_listarray[object]The list of voices returned by the query.

Properties

voice_id / voicestringThe voice ID. Qwen-Audio-TTS/CosyVoice uses voice_id, and Qwen uses voice.gmt_createstringThe creation time.gmt_modifiedstringThe last modification time.statusstring

Returned by Qwen-Audio-TTS/CosyVoice only.

The voice status. For valid values, see "Voice status reference".target_modelstring

Returned by Qwen only.

The TTS model that drives the voice.languagestringThe voice language.voice_promptstringThe voice description text.preview_textstringThe preview audio text.

usageobjectUsage information for this request.

Properties

count integerQwen-Audio-TTS/CosyVoice: always 1. Qwen: always 0.

{
    "output": {
        "voice_list": [
            {
                "voice_id": "cosyvoice-v3.5-plus-vd-announcer-xxxxxx",
                "gmt_create": "2025-12-10 14:54:09",
                "gmt_modified": "2025-12-10 17:47:48",
                "status": "OK",
                "voice_prompt": "A composed middle-aged male announcer with a deep, rich and magnetic voice, a steady speaking speed and clear articulation, is suitable for news broadcasting or documentary commentary.",
                "preview_text": "Dear listeners, hello everyone. Welcome to the evening news."
            }
        ]
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

Qwen-Audio-TTS/CosyVoice returns a voice_list array with voice_id per item. Qwen returns voice_list with voice instead, plus page_index, page_size, and total_count for pagination.

Query voice details

Request body

modelstring(Required)The voice design model. Valid values:

voice-enrollment: Qwen-Audio-TTS/CosyVoice voice design.
qwen-voice-design: Qwen voice design.

inputobject(Required)The input parameter object.

Properties

action string(Required)The operation type. Qwen-Audio-TTS/CosyVoice: query_voice. Qwen voice design: query.voice_id string(Conditionally required)

Only applicable to Qwen-Audio-TTS/CosyVoice.

The voice ID to query.voice string(Conditionally required)

Only applicable to Qwen voice design (when model is qwen-voice-design).

The voice name to query.

curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "voice-enrollment",
    "input": {
        "action": "query_voice",
        "voice_id": "yourVoiceId"
    }
}'

Response body

request_idstringThe unique identifier of this request.outputobjectThe data returned by the model.

Properties

voice_id / voicestringThe voice ID. Qwen-Audio-TTS/CosyVoice returns voice_id, and Qwen returns voice.gmt_createstringThe creation time.gmt_modifiedstringThe last modification time.statusstring

Returned by Qwen-Audio-TTS/CosyVoice only.

The voice status. For valid values, see "Voice status reference".target_modelstringThe TTS model that drives the voice.languagestring

Returned by Qwen voice design only.

The voice language.voice_promptstring

Returned by Qwen-Audio-TTS/CosyVoice voice design only.

The voice description text.preview_textstring

Returned by Qwen-Audio-TTS/CosyVoice voice design only.

The preview audio text.

usageobjectUsage information for this request.

Properties

count integerQwen: always 0. Not returned by Qwen-Audio-TTS/CosyVoice (the usage object is empty).

{
    "output": {
        "voice_id": "cosyvoice-v3.5-plus-vd-announcer-xxxxxx",
        "gmt_create": "2025-12-10 14:54:09",
        "gmt_modified": "2025-12-10 17:47:48",
        "preview_text": "Dear listeners, hello everyone. Welcome to the evening news.",
        "target_model": "cosyvoice-v3.5-plus",
        "status": "OK",
        "voice_prompt": "A composed middle-aged male announcer with a deep, rich and magnetic voice, a steady speaking speed and clear articulation, is suitable for news broadcasting or documentary commentary."
    },
    "usage": {},
    "request_id": "xxxx-xxxx-xxxx"
}

Qwen-Audio-TTS/CosyVoice returns voice_id, voice_prompt, and other fields. Qwen returns the voice and language fields.

Delete a voice

Request body

modelstring(Required)The voice design model. Valid values:

voice-enrollment: Qwen-Audio-TTS/CosyVoice voice design.
qwen-voice-design: Qwen voice design.

inputobject(Required)The input parameter object.

Properties

action string(Required)The operation type. Qwen-Audio-TTS/CosyVoice: delete_voice. Qwen: delete.voice_id string(Conditionally required)

Only applicable to Qwen-Audio-TTS/CosyVoice.

The voice ID to delete.voice string(Conditionally required)

Only applicable to Qwen.

The voice name to delete.

curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "voice-enrollment",
    "input": {
        "action": "delete_voice",
        "voice_id": "yourVoiceId"
    }
}'

Response body

request_idstringThe unique identifier of this request.outputobjectThe data returned by the model. Qwen-Audio-TTS/CosyVoice returns an empty object. Qwen returns the name of the deleted voice.

Properties

voicestring

Returned by Qwen only.

The name of the deleted voice.

usageobjectUsage information for this request.

Properties

count integerQwen-Audio-TTS/CosyVoice: always 1. Qwen: always 0.

{
    "output": {},
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

Qwen-Audio-TTS/CosyVoice returns an empty output object, while Qwen returns the voice field.

Voice status reference

Created voices go through a review process. These statuses apply to Qwen-Audio-TTS/CosyVoice only (model voice-enrollment). Qwen responses do not include a status field.

Status	Description
DEPLOYING	Under review or processing.
OK	Review passed. The voice is ready for use.
UNDEPLOYED	Review rejected. The voice can't be used.

​Endpoint

​Request headers

​Create a voice

Request body

Response body

​List voices

Request body

Response body

​Query voice details

Request body

Response body

​Delete a voice

Request body

Response body

​Voice status reference

Endpoint

Request headers

Create a voice

List voices

Query voice details

Delete a voice

Voice status reference