Skip to main content

Voice Design API reference

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/customizationReplace {WorkspaceId} with your actual workspace ID.
Alibaba Cloud Model Studio has released workspace-specific domains for the China (Beijing) 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
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.
inputobject(Required)The input parameter object.

Properties

action string(Required)The operation type.
  • Qwen-Audio-TTS/CosyVoice (voice-enrollment): Set to create_voice.
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.
preview_text string(Required)The text for the preview audio.
  • Qwen-Audio-TTS/CosyVoice (voice-enrollment): Maximum 200 characters. Chinese and English are supported.
prefix string(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}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"].
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.
Default: 24000.response_format string(Optional)Format of the preview audio.
  • Qwen-Audio-TTS/CosyVoice: pcm, wav, or mp3.
Default: wav.
The following examples use the China (Beijing) region configuration. Replace {WorkspaceId} with your actual workspace ID.Replace {WorkspaceId} with your actual workspace ID.
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"
    }
}'

Response body

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

Properties

voice_idstringThe voice ID. Use it in the voice parameter of the TTS API.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"
}

List voices

Request body

modelstring(Required)The voice design model. Valid values:
  • voice-enrollment: Qwen-Audio-TTS/CosyVoice voice design.
inputobject(Required)The input parameter object.

Properties

action string(Required)Set to list_voice.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.
The following examples use the China (Beijing) region configuration. Replace {WorkspaceId} with your actual workspace ID.
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
    }
}'

Response body

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

Properties

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

Properties

voice_idstringThe voice ID. Use it in the voice parameter of the TTS API.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".voice_promptstringThe voice description text.preview_textstringThe preview audio text.
usageobjectUsage information for this request.

Properties

count integerAlways 1.
{
    "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"
}

Query voice details

Request body

modelstring(Required)The voice design model. Valid values:
  • voice-enrollment: Qwen-Audio-TTS/CosyVoice voice design.
inputobject(Required)The input parameter object.

Properties

action string(Required)Set to query_voice.voice_id string(Required)
Only applicable to Qwen-Audio-TTS/CosyVoice.
The voice ID to query.
The following examples use the China (Beijing) region configuration. Replace {WorkspaceId} with your actual workspace ID.
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"
    }
}'

Response body

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

Properties

voice_idstringThe voice ID. Use it in the voice parameter of the TTS API.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.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 integerAlways 1.
{
    "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": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

Delete a voice

Request body

modelstring(Required)The voice design model. Valid values:
  • voice-enrollment: Qwen-Audio-TTS/CosyVoice voice design.
inputobject(Required)The input parameter object.

Properties

action string(Required)Set to delete_voice.voice_id string(Required)
Only applicable to Qwen-Audio-TTS/CosyVoice.
The voice ID to delete.
The following examples use the China (Beijing) region configuration. Replace {WorkspaceId} with your actual workspace ID.
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"
    }
}'

Response body

request_idstringThe unique identifier of this request.outputobjectThe data returned by the model. This is an empty object.usageobjectUsage information for this request.

Properties

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

Voice status reference

Created voices go through a review process. The following statuses apply to Qwen-Audio-TTS/CosyVoice when model is voice-enrollment.

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.

API Usage
Text Generation
Image Generation
Video Generation
World models
3D Model Generation
Audio
    • Voice Design
  • Audio generation
Real-time Multimodal
Realtime API
Text Embedding
Translation models
Decision Model
More Models
Toolkit/Framework
TokenPlan
Model Production
File Management
Billing
Model Management
More