Voice Design HTTP API reference-Alibaba Cloud Model Studio(Model Studio)-阿里云帮助中心

Use the Voice Design HTTP API to create, list, query, and delete custom voices.

User guide: Voice Design.

Endpoint

China (Beijing)

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization

Replace {WorkspaceId} with your actual workspace ID.

Singapore

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization

Replace {WorkspaceId} with your actual workspace ID.

ImportantAlibaba 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.

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)

ImportantOnly 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)

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

Voice name prefix. Alphanumeric and underscores, max 16 characters.

language_hints array[string](Optional)

ImportantOnly 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)

ImportantOnly 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 both the Beijing and Singapore regions. The following examples use the Beijing region URL. To use Qwen Voice Design in the Singapore region, replace the URL with: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization (replace WorkspaceId with your actual workspace ID).

Replace {WorkspaceId} with your actual workspace ID.

Qwen-Audio-TTS/CosyVoice voice design

curl -X POST https://{WorkspaceId}.cn-beijing.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"
    }
}'

Qwen voice design

curl -X POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-voice-design",
    "input": {
        "action": "create",
        "target_model": "qwen3-tts-vd-realtime-2026-01-15",
        "preferred_name": "announcer",
        "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.",
        "language": "en"
    },
    "parameters": {
        "sample_rate": 24000,
        "response_format": "wav"
    }
}'

Response body

request_idstring

The unique identifier of this request.

outputobject

The data returned by the model.

Properties

voice_id / voicestring

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

preview_audioobject

The preview audio data.

Properties

data string

The preview audio data, Base64-encoded.

sample_rate int

The sample rate of the preview audio, in Hz.

response_format string

The format of the preview audio.

target_modelstring

The TTS model that drives the voice.

usageobject

Usage information for this request.

Properties

count integer

The number of voices created. Always 1.

Qwen-Audio-TTS/CosyVoice voice design

{
    "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 voice design

{
    "output": {
        "preview_audio": {
            "data": "{base64_encoded_audio}",
            "sample_rate": 24000,
            "response_format": "wav"
        },
        "target_model": "qwen3-tts-vd-realtime-2026-01-15",
        "voice": "yourVoice"
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

ImportantQwen-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)

ImportantOnly 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.

Qwen-Audio-TTS/CosyVoice

curl -X POST https://{WorkspaceId}.cn-beijing.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
    }
}'

Qwen voice design

curl -X POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-voice-design",
    "input": {
        "action": "list",
        "page_size": 10,
        "page_index": 0
    }
}'

Response body

request_idstring

The unique identifier of this request.

outputobject

The data returned by the model.

Properties

page_indexinteger

ImportantReturned by Qwen only.

The current page index.

page_sizeinteger

ImportantReturned by Qwen only.

The number of entries per page.

total_countinteger

ImportantReturned by Qwen only.

The total number of voices.

voice_listarray[object]

The list of voices returned by the query.

Properties

voice_id / voicestring

The voice ID. Qwen-Audio-TTS/CosyVoice uses voice_id, and Qwen uses voice.

gmt_createstring

The creation time.

gmt_modifiedstring

The last modification time.

statusstring

ImportantReturned by Qwen-Audio-TTS/CosyVoice only.

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

target_modelstring

ImportantReturned by Qwen only.

The TTS model that drives the voice.

languagestring

The voice language.

voice_promptstring

The voice description text.

preview_textstring

The preview audio text.

usageobject

Usage information for this request.

Properties

count integer

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

Qwen-Audio-TTS/CosyVoice

{
    "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

{
    "output": {
        "page_index": 0,
        "page_size": 10,
        "total_count": 1,
        "voice_list": [
            {
                "voice": "yourVoice",
                "gmt_create": "2025-08-11 17:59:32",
                "gmt_modified": "2025-08-11 17:59:32",
                "language": "zh",
                "target_model": "qwen3-tts-vd-realtime-2026-01-15",
                "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": 0
    },
    "request_id": "xxxx-xxxx-xxxx"
}

ImportantQwen-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)

ImportantOnly applicable to Qwen-Audio-TTS/CosyVoice.

The voice ID to query.

voice string(Conditionally required)

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

The voice name to query.

Qwen-Audio-TTS/CosyVoice

curl -X POST https://{WorkspaceId}.cn-beijing.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"
    }
}'

Qwen voice design

curl -X POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-voice-design",
    "input": {
        "action": "query",
        "voice": "yourVoice"
    }
}'

Response body

request_idstring

The unique identifier of this request.

outputobject

The data returned by the model.

Properties

voice_id / voicestring

The voice ID. Qwen-Audio-TTS/CosyVoice returns voice_id, and Qwen returns voice.

gmt_createstring

The creation time.

gmt_modifiedstring

The last modification time.

statusstring

ImportantReturned by Qwen-Audio-TTS/CosyVoice only.

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

target_modelstring

The TTS model that drives the voice.

languagestring

ImportantReturned by Qwen voice design only.

The voice language.

voice_promptstring

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

The voice description text.

preview_textstring

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

The preview audio text.

usageobject

Usage information for this request.

Properties

count integer

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

Qwen-Audio-TTS/CosyVoice voice design

{
    "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 voice design

{
    "output": {
        "voice": "yourVoice",
        "gmt_create": "2025-08-11 17:59:32",
        "gmt_modified": "2025-08-11 17:59:32",
        "language": "zh",
        "target_model": "qwen3-tts-vd-realtime-2026-01-15"
    },
    "usage": {
        "count": 0
    },
    "request_id": "xxxx-xxxx-xxxx"
}

ImportantQwen-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)

ImportantOnly applicable to Qwen-Audio-TTS/CosyVoice.

The voice ID to delete.

voice string(Conditionally required)

ImportantOnly applicable to Qwen.

The voice name to delete.

Qwen-Audio-TTS/CosyVoice

curl -X POST https://{WorkspaceId}.cn-beijing.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"
    }
}'

Qwen voice design

curl -X POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-voice-design",
    "input": {
        "action": "delete",
        "voice": "yourVoice"
    }
}'

Response body

request_idstring

The unique identifier of this request.

outputobject

The data returned by the model. Qwen-Audio-TTS/CosyVoice returns an empty object. Qwen returns the name of the deleted voice.

Properties

voicestring

ImportantReturned by Qwen only.

The name of the deleted voice.

usageobject

Usage information for this request.

Properties

count integer

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

Qwen-Audio-TTS/CosyVoice

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

Qwen

{
    "output": {
        "voice": "yourVoice"
    },
    "usage": {
        "count": 0
    },
    "request_id": "xxxx-xxxx-xxxx"
}

ImportantQwen-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.