All Products
Search

This Product

    :Voice Design API Reference

    Document Center

    :Voice Design API Reference

    Last Updated:Nov 06, 2026

    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.

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

    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.

    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)

    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}

    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"].

    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.

    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_idstring

    The unique identifier of this request.

    outputobject

    The data returned by the model.

    Properties

    voice_idstring

    The voice ID. Use it in the voice parameter of the TTS API.

    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.

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

    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.

    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_idstring

    The unique identifier of this request.

    outputobject

    The data returned by the model.

    Properties

    voice_listarray[object]

    The list of voices returned by the query.

    Properties

    voice_idstring

    The voice ID. Use it in the voice parameter of the TTS API.

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

    voice_promptstring

    The voice description text.

    preview_textstring

    The preview audio text.

    usageobject

    Usage information for this request.

    Properties

    count integer

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

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

    The unique identifier of this request.

    outputobject

    The data returned by the model.

    Properties

    voice_idstring

    The voice ID. Use it in the voice parameter of the TTS API.

    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.

    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

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

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

    The unique identifier of this request.

    outputobject

    The data returned by the model. This is an empty object.

    usageobject

    Usage information for this request.

    Properties

    count integer

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