Voice cloning HTTP API reference

Use the HTTP API to create, list, query, update, and delete cloned voices. User guide: Voice cloning.

Service endpoint

International

If you select the International deployment scope, model inference compute resources are dynamically scheduled worldwide, excluding the Chinese mainland. Static data is stored in your selected region. Supported region: Singapore.

POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization

Chinese mainland

If you select the Chinese mainland deployment scope, model inference compute resources are restricted to the Chinese mainland. Static data is stored in your selected region. Supported region: China (Beijing).

POST https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization

Request headers

Parameter	Type	Required	Description
Authorization	string	Yes	Authentication token in the format `Bearer` . Replace with your actual API key.
Content-Type	string	Yes	Media type of the request body. Set to `application/json` for CosyVoice/Qwen-TTS, or `application/json; charset=utf-8` for MiniMax.

Create a voice

Request body

This example uses the Singapore region endpoint. For the Beijing region, use: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization.

## CosyVoice voice cloning

curl

curl -X POST https://dashscope-intl.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-plus",
 "prefix": "myvoice",
 "url": "https://your-audio-url.wav",
 "language_hints": \["en"\]
 }
}'

## Qwen voice cloning

curl

curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization \\
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{
 "model": "qwen-voice-enrollment",
 "input": {
 "action": "create",
 "target_model": "qwen3-tts-vc-realtime-2026-01-15",
 "preferred_name": "myvoice",
 "audio": {"data": "data:audio/mpeg;base64,{base64_encoded_audio}"}
 }
}'

   **model **`*string*`* ***(required)**

The voice cloning model. Valid values:

voice-enrollment: CosyVoice voice cloning.
qwen-voice-enrollment: Qwen voice cloning.

**input **object* *(required) The input parameters. Properties

action *string** *(required) The action type.

CosyVoice (voice-enrollment): Set to create_voice.
Qwen (qwen-voice-enrollment): Set to create.

target_model *string** *(required) The text-to-speech (TTS) model that drives the cloned voice. It must match the model you specify when calling the TTS API; otherwise, synthesis fails.

url *string** *(conditionally required)

**Important ** Applies only to CosyVoice voice cloning (when model is voice-enrollment).

The URL of the audio file for voice cloning. The URL must be publicly accessible.

audio *object** *(conditionally required)

**Important ** Applies only to Qwen voice cloning (when model is qwen-voice-enrollment).

The audio data. Two submission methods are supported:

Data URL (Base64-encoded): Format is {"data": "data:{mime_type};base64,{base64_encoded_data}"}. Supported MIME types: audio/wav, audio/mpeg, and audio/mp4.
Audio URL: Format is {"data": "https://your-audio-url.wav"}. The URL must be publicly accessible without authentication.

text *string** *(optional)

**Important ** Applies only to Qwen voice cloning (when model is qwen-voice-enrollment).

The transcript of the audio, used to improve cloning quality.

prefix *string** *(conditionally required)

**Important ** Applies only to CosyVoice (when model is voice-enrollment).

A prefix for the voice name. Only alphanumeric characters are allowed, with a maximum length of 10 characters. The resulting voice name follows this format: {target_model}-{prefix}-{unique_id}.

preferred_name *string** *(conditionally required)

**Important ** Applies only to Qwen voice cloning (when model is qwen-voice-enrollment).

A prefix for the voice name. Only alphanumeric characters and underscores are allowed, with a maximum length of 16 characters.

language_hints *array\[string\]** *(optional)

**Important ** Applies only to CosyVoice voice cloning (when model is voice-enrollment). Supported only by cosyvoice-v3.5-plus, v3.5-flash, v3-plus, and v3-flash.

Helps the model identify the language of the sample audio to extract voice features more accurately and improve cloning quality. If the specified language doesn't match the actual audio language (for example, setting en when the audio is in Chinese), the system ignores this value and detects the language automatically. This parameter is an array, but the current version processes only the first element. Valid values vary by model:

cosyvoice-v3-plus: <li>zh: Chinese
en: English
fr: French
de: German
ja: Japanese
ko: Korean
ru: Russian </li>
cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash: <li>zh: Chinese
en: English
fr: French
de: German
ja: Japanese
ko: Korean
ru: Russian
pt: Portuguese
th: Thai
id: Indonesian
vi: Vietnamese </li> Default: ["zh"].

language *string** *(optional)

**Important ** Applies only to Qwen voice cloning (when model is qwen-voice-enrollment).

The language of the audio provided in audio.data. If you use this parameter, make sure the specified language matches the actual language of the audio used for cloning. Valid values:

zh: Chinese
en: English
de: German
it: Italian
pt: Portuguese
es: Spanish
ja: Japanese
ko: Korean
fr: French
ru: Russian Default: zh.

max_prompt_audio_length *float** *(optional)

**Important ** Applies only to CosyVoice voice cloning (when model is voice-enrollment). Supported only by cosyvoice-v3.5-plus, v3.5-flash, and v3-flash.

The maximum duration (in seconds) of the reference audio after preprocessing. Valid values: [3.0, 30.0]. Longer durations produce better results. Default: 10.0.

enable_preprocess *boolean** *(optional)

**Important ** Applies only to CosyVoice voice cloning (when model is voice-enrollment). Supported only by cosyvoice-v3.5-plus, v3.5-flash, and v3-flash.

Whether to enable audio preprocessing (noise reduction, audio enhancement, and volume normalization). Enable this for recordings with background noise. Disable it for recordings in quiet environments to preserve the original voice characteristics. Default: false.

Response body

## CosyVoice voice cloning

json

{
 "output": {
 "voice_id": "cosyvoice-v3.5-plus-myvoice-xxxxxx"
 },
 "usage": {
 "count": 1
 },
 "request_id": "xxxx-xxxx-xxxx"
}

## Qwen voice cloning

json

{
 "output": {
 "voice": "yourVoice",
 "target_model": "qwen3-tts-vc-realtime-2026-01-15"
 },
 "usage": {
 "count": 1
 },
 "request_id": "xxxx-xxxx-xxxx"
}

**Important ** CosyVoice returns the voice_id field, while Qwen returns the voice field. Qwen voice cloning may also return the fallback_mode and fallback_reason 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, while Qwen returns voice. Use this value directly in the voice parameter of the TTS API.

**target_model ***string*

**Important ** Returned only by Qwen.

The TTS model that drives the cloned voice.

**fallback_mode ***boolean*

**Important ** Applies only to Qwen voice cloning (when model is qwen-voice-enrollment).

Whether the voice was created in fallback mode. A value of true indicates that the audio quality was poor or didn't match the provided text, and the cloning quality may be reduced.

**fallback_reason ***string*

**Important ** Returned only when fallback_mode is true.

The reason for the fallback. Possible values include no_merged_segments (unable to merge audio segments) and no_valid_asr_segments (severe mismatch between audio and text).

**usage ***object* Usage information for this request. Properties

count *integer* The number of voices created. Always 1.

Query voice list

Request body

This example uses the Singapore region endpoint. For the Beijing region, use: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization.

## CosyVoice

curl

curl -X POST https://dashscope-intl.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 cloning

curl

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

   **model **`*string*`* ***(required)**

The voice cloning model. Valid values:

voice-enrollment: CosyVoice voice cloning.
qwen-voice-enrollment: Qwen voice cloning.

**input **object* *(required) The input parameters. Properties

action *string** *(required) The action type. CosyVoice: list_voice. Qwen: list.

prefix *string** *(optional)

**Important ** Applies only to CosyVoice.

Filters voices by name prefix.

page_index *integer** *(optional) The page index.

page_size *integer** *(optional) The number of entries per page.

Response body

## CosyVoice

json

{
 "output": {
 "voice_list": \[
 {
 "voice_id": "cosyvoice-v3.5-plus-myvoice-xxxxxx",
 "gmt_create": "2024-12-11 13:38:02",
 "gmt_modified": "2024-12-11 13:38:02",
 "status": "OK"
 }
 \]
 },
 "usage": {
 "count": 1
 },
 "request_id": "xxxx-xxxx-xxxx"
}

## Qwen

json

{
 "output": {
 "page_index": 0,
 "page_size": 10,
 "total_count": 2,
 "voice_list": \[
 {
 "voice": "yourVoice1",
 "gmt_create": "2025-08-11 17:59:32",
 "gmt_modified": "2025-08-11 17:59:32",
 "language": "en",
 "target_model": "qwen3-tts-vc-realtime-2026-01-15"
 }
 \]
 },
 "usage": {
 "count": 0
 },
 "request_id": "xxxx-xxxx-xxxx"
}

**Important ** CosyVoice returns a voice_list array where each entry contains the voice_id field. Qwen also returns a voice_list array, but each entry contains the voice field instead. The Qwen output additionally 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 only by Qwen.

The current page index.

**page_size ***integer*

**Important ** Returned only by Qwen.

The number of entries per page.

**total_count ***integer*

**Important ** Returned only by Qwen.

The total number of voices.

**voice_list ***array\[object\]* The list of queried voices. Both CosyVoice and Qwen use the voice_list field name. Properties

**voice_id / voice ***string* The voice ID. CosyVoice uses voice_id, while Qwen uses voice.

**gmt_create ***string* The creation time.

**gmt_modified ***string* The last modification time.

**status ***string*

**Important ** Returned only by CosyVoice.

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

**target_model ***string*

**Important ** Returned only by Qwen.

The TTS model that drives the cloned voice.

**usage ***object* Usage information for this request. Properties

count *integer* Always 1 for CosyVoice. Always 0 for Qwen.

Query voice details

Important

Applies only to CosyVoice (when model is voice-enrollment). Qwen models don't support the query voice details operation.

Request body

This example uses the Singapore region endpoint. For the Beijing region, use: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization.

## CosyVoice

curl

curl -X POST https://dashscope-intl.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"
 }
}'

   **model **`*string*`* ***(required)**

Set to voice-enrollment (CosyVoice).

**input **object* *(required) The input parameters. Properties

action *string** *(required) Set to query_voice.

voice_id *string** *(required) The voice ID to query.

Response body

json

{
 "output": {
 "gmt_create": "2024-12-11 13:38:02",
 "resource_link": "https://yourAudioFileUrl",
 "target_model": "cosyvoice-v3.5-plus",
 "gmt_modified": "2024-12-11 13:38:02",
 "status": "OK"
 },
 "usage": {
 "count": 1
 },
 "request_id": "xxxx-xxxx-xxxx"
}

**request_id ***string* The unique identifier of this request.

**output ***object* The data returned by the model. Properties

**resource_link ***string* The URL of the audio file.

**gmt_create ***string* The creation time.

**gmt_modified ***string* The last modification time.

**status ***string* The voice status. For valid values, see "Voice status descriptions".

**target_model ***string* The TTS model that drives the cloned voice.

**usage ***object* Usage information for this request. Properties

count *integer* Always 1.

Update a voice

Important

Applies only to CosyVoice voice cloning (when model is voice-enrollment). Qwen models don't support the update operation.

Request body

This example uses the Singapore region endpoint. For the Beijing region, use: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization.

curl

curl -X POST https://dashscope-intl.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": "update_voice",
 "voice_id": "yourVoiceId",
 "url": "https://new-audio-url.wav"
 }
 }'

   **model **`*string*`* ***(required)**

Set to voice-enrollment.

**input **object* *(required) The input parameters. Properties

action *string** *(required) Set to update_voice.

voice_id *string** *(required) The voice ID to update.

url *string** *(required) The URL of the new audio file. The URL must be publicly accessible.

Response body

json

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

**request_id ***string* The unique identifier of this request.

**output ***object* The data returned by the model. The update operation returns an empty object.

**usage ***object* Usage information for this request. Properties

count *integer* Always 1.

Delete a voice

Request body

This example uses the Singapore region endpoint. For the Beijing region, use: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization.

## CosyVoice

curl

curl -X POST https://dashscope-intl.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 cloning

curl

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

   **model **`*string*`* ***(required)**

The voice cloning model. Valid values:

voice-enrollment: CosyVoice voice cloning.
qwen-voice-enrollment: Qwen voice cloning.

**input **object* *(required) The input parameters. Properties

action *string** *(required) The action type. CosyVoice: delete_voice. Qwen: delete.

voice_id *string** *(conditionally required)

**Important ** Applies only to CosyVoice.

The voice ID to delete.

voice *string** *(conditionally required)

**Important ** Applies only to Qwen.

The voice name to delete.

Response body

## CosyVoice

json

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

## Qwen

json

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

**Important ** CosyVoice returns an empty output object, while Qwen returns the voice field with the deleted voice name.

**request_id ***string* The unique identifier of this request.

**output ***object* The data returned by the model. CosyVoice returns an empty object, while Qwen returns the name of the deleted voice. Properties

**voice ***string*

**Important ** Returned only by Qwen.

The name of the deleted voice.

**usage ***object* Usage information for this request. Properties

count *integer* Always 1.

Voice status descriptions

After a voice is created, it goes through a review process. The statuses below apply 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 to use.
UNDEPLOYED	Review rejected. The voice can't be used.

Voice cloning HTTP API reference ​

Service endpoint ​

International ​

Chinese mainland ​

Request headers ​

Create a voice ​

Request body ​

## CosyVoice voice cloning ​

## Qwen voice cloning ​

Response body ​

## CosyVoice voice cloning ​

## Qwen voice cloning ​

Query voice list ​

Request body ​

## CosyVoice ​

## Qwen voice cloning ​

Response body ​

## CosyVoice ​

## Qwen ​

Query voice details ​

Request body ​

## CosyVoice ​

Response body ​

Update a voice ​

Request body ​

Response body ​

Delete a voice ​

Request body ​

## CosyVoice ​

## Qwen voice cloning ​

Response body ​

## CosyVoice ​

## Qwen ​

Voice status descriptions ​

Voice cloning HTTP API reference

Service endpoint

International

Chinese mainland

Request headers

Create a voice

Request body

## CosyVoice voice cloning

## Qwen voice cloning

Response body

## CosyVoice voice cloning

## Qwen voice cloning

Query voice list

Request body

## CosyVoice

## Qwen voice cloning

Response body

## CosyVoice

## Qwen

Query voice details

Request body

## CosyVoice

Response body

Update a voice

Request body

Response body

Delete a voice

Request body

## CosyVoice

## Qwen voice cloning

Response body

## CosyVoice

## Qwen

Voice status descriptions