Voice Design API reference

User guide: Voice Design.

Endpoint

Voice design is available only in China North 2 (Beijing). Use an API key from this region. See Regions. POST https://cn-beijing.maas.qwencloudapi.com/api/v1/services/audio/tts/customization

Request headers

Parameter	Type	Required	Description
Authorization	string	Yes	Set to `Bearer $DASHSCOPE_API_KEY`. Replace `$DASHSCOPE_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

# China North 2 (Beijing). This model is available only in this region.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
curl -X POST https://cn-beijing.maas.qwencloudapi.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"
    }
}'

Parameter	Type	Description
model	string	(Required) The voice design model. Valid values: `voice-enrollment`: Qwen-Audio-TTS/CosyVoice voice design.
input	object	(Required) The input parameter object.
input.action	string	(Required) The operation type. Qwen-Audio-TTS/CosyVoice (`voice-enrollment`): Set to `create_voice`.
input.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.
input.voice_prompt	string	(Required) Description of desired voice characteristics. Chinese and English only. Qwen-Audio-TTS/CosyVoice (`voice-enrollment`): Maximum 500 characters.
input.preview_text	string	(Required) The text for the preview audio. Qwen-Audio-TTS/CosyVoice (`voice-enrollment`): Maximum 200 characters. Chinese and English are supported.
input.prefix	string	(Required) Tip: 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}`
input.language_hints	array[string]	(Optional) Tip: 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"].
parameters	object	(Optional) Configuration for voice design.
parameters.sample_rate	int	(Optional) Sample rate of the preview audio, in Hz. Qwen-Audio-TTS/CosyVoice: 16000, 24000, or 48000. Default: 24000.
parameters.response_format	string	(Optional) Format of the preview audio. Qwen-Audio-TTS/CosyVoice: pcm, wav, or mp3. Default: wav.

Response body

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

Parameter	Type	Description
request_id	string	The unique identifier of this request.
output	object	The data returned by the model.
output.voice_id	string	The voice ID. Use it in the `voice` parameter of the TTS API.
output.preview_audio	object	The preview audio data.
output.preview_audio.data	string	The preview audio data, Base64-encoded.
output.preview_audio.sample_rate	int	The sample rate of the preview audio, in Hz.
output.preview_audio.response_format	string	The format of the preview audio.
output.target_model	string	The TTS model that drives the voice.
usage	object	Usage information for this request.
usage.count	integer	The number of voices created. Always 1.

List voices

Request body

# China North 2 (Beijing). This model is available only in this region.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
curl -X POST https://cn-beijing.maas.qwencloudapi.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
    }
}'

Parameter	Type	Description
input.action	string	(Required) Set to `list_voice`.
input.prefix	string	(Optional) Tip: Only applicable to Qwen-Audio-TTS/CosyVoice. Filter voices by name prefix.
input.page_index	integer	(Optional) The page index.
input.page_size	integer	(Optional) The number of entries per page.

Response body

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

Parameter	Type	Description
output.voice_list	array[object]	The list of voices returned by the query.
output.voice_list.voice_id	string	The voice ID. Use it in the `voice` parameter of the TTS API.
output.voice_list.gmt_create	string	The creation time.
output.voice_list.gmt_modified	string	The last modification time.
output.voice_list.status	string	Tip: Returned by Qwen-Audio-TTS/CosyVoice only. The voice status. For valid values, see "Voice status reference".
output.voice_list.voice_prompt	string	The voice description text.
output.voice_list.preview_text	string	The preview audio text.
usage.count	integer	Always 1.

Query voice details

Request body

# China North 2 (Beijing). This model is available only in this region.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
curl -X POST https://cn-beijing.maas.qwencloudapi.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"
    }
}'

Parameter	Type	Description
input.action	string	(Required) Set to `query_voice`.
input.voice_id	string	(Required) Tip: Only applicable to Qwen-Audio-TTS/CosyVoice. The voice ID to query.

Response body

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

Parameter	Type	Description
output.voice_id	string	The voice ID. Use it in the `voice` parameter of the TTS API.
output.gmt_create	string	The creation time.
output.gmt_modified	string	The last modification time.
output.status	string	Tip: Returned by Qwen-Audio-TTS/CosyVoice only. The voice status. For valid values, see "Voice status reference".
output.target_model	string	The TTS model that drives the voice.
output.voice_prompt	string	Tip: Returned by Qwen-Audio-TTS/CosyVoice voice design only. The voice description text.
output.preview_text	string	Tip: Returned by Qwen-Audio-TTS/CosyVoice voice design only. The preview audio text.

Delete a voice

Request body

# China North 2 (Beijing). This model is available only in this region.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
curl -X POST https://cn-beijing.maas.qwencloudapi.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"
    }
}'

Parameter	Type	Description
input.action	string	(Required) Set to `delete_voice`.
input.voice_id	string	(Required) Tip: Only applicable to Qwen-Audio-TTS/CosyVoice. The voice ID to delete.

Response body

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

Parameter	Type	Description
output	object	The data returned by the model. This is an empty object.

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.

​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

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