DocsICP FilingConsole
官方文档
首页

Voice Design API reference

更新时间：
复制 MD 格式
产品详情
我的收藏

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.

Important

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 https://dashscope.aliyuncs.com to https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com

  • Singapore: from https://dashscope-intl.aliyuncs.com to https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

{WorkspaceId} is your workspace ID, which can be found on the Workspace Details page in the Model Studio console. The existing domain remains fully functional.

Request headers

Parameter

Type

Required

Description

Authorization

string

Yes

Authorization token in the format Bearer <your_api_key>. Replace <your_api_key> with your actual API key.

Content-Type

string

Yes

Media type of the request body. Set to application/json.

Create a voice

Request body

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

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"
    }
}'

model string (Required)

The voice design model. Valid values:

  • voice-enrollment: CosyVoice voice design.

  • qwen-voice-design: Qwen voice design.

input object (Required)

The input parameter object.

Properties

action string (Required)

The operation type.

  • CosyVoice (voice-enrollment): Set to create_voice.

  • Qwen (qwen-voice-design): Set to create.

target_model string (Required)

The text-to-speech (TTS) model that drives the voice. This value must match the model used when you call the TTS API. A mismatch causes synthesis to fail.

voice_prompt string (Required)

A voice description of the desired voice characteristics. Only Chinese and English are supported.

  • CosyVoice (voice-enrollment): Maximum 500 characters.

  • Qwen (qwen-voice-design): Maximum 2,048 characters.

preview_text string (Required)

The text for the preview audio.

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

Important

Only applicable to CosyVoice (when model is voice-enrollment).

The voice name prefix. Only digits and letters are allowed, with a maximum of 10 characters. The generated voice name follows the format: {target_model}-vd-{prefix}-{unique_id}

preferred_name string (Conditionally required)

Important

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

The voice name prefix. Only digits, letters, and underscores are allowed, with a maximum of 16 characters.

language_hints array[string] (Optional)

Important

Only applicable to CosyVoice (when model is voice-enrollment).

The language hints for the generated voice. This determines the voice's language characteristics and pronunciation patterns. Set this to the language that matches your use case. The specified language 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)

Important

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

The language hints for the generated voice. This determines the voice's language characteristics and pronunciation patterns. Set this to the language that matches your use case. The specified language 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.

parameters object (Optional)

Configuration for voice design.

Properties

sample_rate int (Optional)

Sample rate of the preview audio, in Hz.

  • CosyVoice: 16000, 24000, or 48000.

  • Qwen: 8000, 16000, 24000, or 48000.

Default: 24000.

response_format string (Optional)

Format of the preview audio.

  • CosyVoice: pcm, wav, or mp3.

  • Qwen: pcm, wav, mp3, or opus.

Default: wav.

Response body

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"
}
Important

CosyVoice returns the voice_id field, while Qwen returns the voice field.

request_id string

The unique identifier of this request.

output object

The data returned by the model.

Properties

voice_id / voice string

The voice ID. CosyVoice returns voice_id, and Qwen returns voice. Use this value directly as the voice parameter in the TTS API.

preview_audio object

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_model string

The TTS model that drives the voice.

usage object

Usage information for this request.

Properties

count integer

The number of voices created. Always 1.

List voices

Request body

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

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
    }
}'

model string (Required)

The voice design model. Valid values:

  • voice-enrollment: CosyVoice voice design.

  • qwen-voice-design: Qwen voice design.

input object (Required)

The input parameter object.

Properties

action string (Required)

The operation type. CosyVoice: list_voice. Qwen: list.

prefix string (Optional)

Important

Only applicable to CosyVoice.

Filter voices by name prefix.

page_index integer (Optional)

The page index.

page_size integer (Optional)

The number of entries per page.

Response body

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"
}
Important

CosyVoice returns a voice_list array where each item contains a voice_id field. Qwen also returns a voice_list array, but each item contains a voice field instead. The Qwen output also includes the page_index, page_size, and total_count pagination fields.

request_id string

The unique identifier of this request.

output object

The data returned by the model.

Properties

page_index integer

Important

Returned by Qwen only.

The current page index.

page_size integer

Important

Returned by Qwen only.

The number of entries per page.

total_count integer

Important

Returned by Qwen only.

The total number of voices.

voice_list array[object]

The list of voices returned by the query.

Properties

voice_id / voice string

The voice ID. CosyVoice uses voice_id, and Qwen uses voice.

gmt_create string

The creation time.

gmt_modified string

The last modification time.

status string

Important

Returned by CosyVoice only.

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

target_model string

Important

Returned by Qwen only.

The TTS model that drives the voice.

language string

The voice language.

voice_prompt string

The voice description text.

preview_text string

The preview audio text.

usage object

Usage information for this request.

Properties

count integer

CosyVoice: always 1. Qwen: always 0.

Query voice details

Request body

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

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"
    }
}'

model string (Required)

The voice design model. Valid values:

  • voice-enrollment: CosyVoice voice design.

  • qwen-voice-design: Qwen voice design.

input object (Required)

The input parameter object.

Properties

action string (Required)

The operation type. CosyVoice: query_voice. Qwen voice design: query.

voice_id string (Conditionally required)

Important

Only applicable to CosyVoice.

The voice ID to query.

voice string (Conditionally required)

Important

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

The voice name to query.

Response body

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"
}
Important

CosyVoice returns voice_id, voice_prompt, and other fields. Qwen returns the voice and language fields.

request_id string

The unique identifier of this request.

output object

The data returned by the model.

Properties

voice_id / voice string

The voice ID. CosyVoice returns voice_id, and Qwen returns voice.

gmt_create string

The creation time.

gmt_modified string

The last modification time.

status string

Important

Returned by CosyVoice only.

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

target_model string

The TTS model that drives the voice.

language string

Important

Returned by Qwen voice design only.

The voice language.

voice_prompt string

Important

Returned by CosyVoice voice design only.

The voice description text.

preview_text string

Important

Returned by CosyVoice voice design only.

The preview audio text.

usage object

Usage information for this request.

Properties

count integer

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

Delete a voice

Request body

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

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"
    }
}'

model string (Required)

The voice design model. Valid values:

  • voice-enrollment: CosyVoice voice design.

  • qwen-voice-design: Qwen voice design.

input object (Required)

The input parameter object.

Properties

action string (Required)

The operation type. CosyVoice: delete_voice. Qwen: delete.

voice_id string (Conditionally required)

Important

Only applicable to CosyVoice.

The voice ID to delete.

voice string (Conditionally required)

Important

Only applicable to Qwen.

The voice name to delete.

Response body

CosyVoice

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

Qwen

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

CosyVoice returns an empty output object, while Qwen returns the voice field.

request_id string

The unique identifier of this request.

output object

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

Properties

voice string

Important

Returned by Qwen only.

The name of the deleted voice.

usage object

Usage information for this request.

Properties

count integer

CosyVoice: always 1. Qwen: always 0.

Voice status reference

After a voice is created, it goes through a review process. The following table describes each status. This status system applies only to CosyVoice (when model is voice-enrollment). Qwen query and list responses don't 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.
Previous：Python SDK referenceNext：Music generation