Voice cloning HTTP API reference

Service endpoint

Qwen-Audio-TTS/Qwen-Audio-Realtime/CosyVoice

POST https://ap-southeast-1.maas.qwencloudapi.com/api/v1/services/audio/tts/customization This is the Singapore endpoint. For another region, replace ap-southeast-1 in the URL. API keys are region-specific. See Regions.

Request headers

Parameter	Type	Required	Description
Authorization	string	Yes	Authentication token in the format `Bearer $DASHSCOPE_API_KEY`.
Content-Type	string	Yes	Media type of the request body. Set it based on the model series: Qwen-Audio-TTS/Qwen-Audio-Realtime/CosyVoice: `application/json`.

Create a voice

Qwen-Audio-TTS/Qwen-Audio-Realtime/CosyVoice

Request body

# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
curl -X POST https://ap-southeast-1.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": "qwen-audio-3.0-tts-flash",
        "prefix": "myvoice",
        "audio": "https://your-audio-url.wav",
        "language_hints": ["en"],
        "enable_volume_normalization": "false"
    }
}'

For a local WAV file, use the following code to generate a Base64 Data URI and pass the value of audio to input.audio in the create or update request. Replace sample.wav with your local audio path.

import base64
from pathlib import Path

audio = "data:audio/wav;base64," + base64.b64encode(
  Path("sample.wav").read_bytes()
).decode("ascii")

Parameter	Type	Description
model	string	(required) Set to `voice-enrollment`.
input	object	(required) The input parameters.
input.action	string	(required) Set to `create_voice`.
input.target_model	string	(required) The target model that uses the voice. It must match the model used in subsequent requests with this voice; otherwise, the requests fail.
input.audio	string	(required) Reference audio for voice cloning. Accepts a publicly accessible URL or a Base64 Data URI, such as `data:audio/wav;base64,...`. Note: The legacy `url` parameter is still supported. You can omit `audio` when using `url`. The `url` parameter will be phased out; use `audio` for new requests.
input.prefix	string	(required) 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}`.
input.language_hints	array[string]	(optional) 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 and must contain exactly one element. Note: Applies to qwen-audio-3.1-tts-plus, qwen-audio-3.1-tts-flash, qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, qwen-audio-3.1-realtime-plus, qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash, cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-plus, cosyvoice-v3-flash (cosyvoice-v3.5-plus and cosyvoice-v3.5-flash are available only in China North 2 (Beijing)). qwen-audio-3.1-tts-plus, qwen-audio-3.1-tts-flash, qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, qwen-audio-3.1-realtime-plus, qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash: zh: Chinese en: English fr: French de: German ja: Japanese ko: Korean ru: Russian pt: Portuguese th: Thai id: Indonesian vi: Vietnamese it: Italian es: Spanish ms: Malaysian fil: Filipino ar: Arabic cosyvoice-v3-plus: zh: Chinese en: English fr: French de: German ja: Japanese ko: Korean ru: Russian cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash: zh: Chinese en: English fr: French de: German ja: Japanese ko: Korean ru: Russian pt: Portuguese th: Thai id: Indonesian vi: Vietnamese Default: ["zh"].
input.max_prompt_audio_length	float	(optional) The maximum duration (in seconds) of the reference audio after preprocessing. Valid values: [3.0, 30.0]. Default: 10.0. Note: Applies to qwen-audio-3.1-tts-plus, qwen-audio-3.1-tts-flash, qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, qwen-audio-3.1-realtime-plus, qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash, cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash (cosyvoice-v3.5-plus and cosyvoice-v3.5-flash are available only in China North 2 (Beijing)).
input.enable_preprocess	boolean	(optional) 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. Note: Applies to qwen-audio-3.1-tts-plus, qwen-audio-3.1-tts-flash, qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, qwen-audio-3.1-realtime-plus, qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash, cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash (cosyvoice-v3.5-plus and cosyvoice-v3.5-flash are available only in China North 2 (Beijing)).
input.enable_volume_normalization	string	(optional) Whether to normalize the volume of the sample audio used for voice cloning. Valid values: `"true"`: Enable volume normalization. `"false"`: Disable volume normalization. When enabled, audio synthesized with the created voice may have a different volume than audio synthesized with a voice created with this parameter disabled. Default: `"false"`.

Response body

{
    "output": {
        "voice_id": "qwen-audio-3.0-tts-flash-myvoice-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.
usage	object	Usage information for this request.
usage.count	integer	The number of voices created. Always 1.

Query voice list

Applies to Qwen-Audio-TTS, Qwen-Audio-Realtime, and CosyVoice.

Request body

# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
curl -X POST https://ap-southeast-1.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) Filters 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": "qwen-audio-3.0-tts-flash-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"
}

Parameter	Type	Description
output.voice_list	array[object]	The list of queried voices.
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	The voice status. For valid values, see "Voice status descriptions".
usage.count	integer	Always 1.

Query voice details

Applies to Qwen-Audio-TTS, Qwen-Audio-Realtime, and CosyVoice.

Request body

Query voice details

# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
curl -X POST https://ap-southeast-1.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) The voice ID to query.

Response body

{
    "output": {
        "gmt_create": "2024-12-11 13:38:02",
        "resource_link": "https://yourAudioFileUrl",
        "target_model": "qwen-audio-3.0-tts-flash",
        "gmt_modified": "2024-12-11 13:38:02",
        "status": "OK"
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

Parameter	Type	Description
output.resource_link	string	The URL of the audio file.
output.gmt_create	string	The creation time.
output.gmt_modified	string	The last modification time.
output.status	string	The voice status. For valid values, see "Voice status descriptions".
output.target_model	string	The TTS model that drives the cloned voice.

Update a voice

Applies to Qwen-Audio-TTS, Qwen-Audio-Realtime, and CosyVoice.

Request body

# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
curl -X POST https://ap-southeast-1.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": "update_voice",
        "voice_id": "yourVoiceId",
        "audio": "https://new-audio-url.wav"
    }
}'

Parameter	Type	Description
input.action	string	(required) Set to `update_voice`.
input.voice_id	string	(required) The voice ID to update.
input.audio	string	(required) New reference audio. Accepts a publicly accessible URL or a Base64 Data URI, such as `data:audio/wav;base64,...`. Note: The legacy `url` parameter is still supported. You can omit `audio` when using `url`. The `url` parameter will be phased out; use `audio` for new requests.

Response body

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

Parameter	Type	Description
output	object	The data returned by the model. The update operation returns no business data. The response may include a `preview_audio` field, which is an empty object that you can ignore.

Delete a voice

Applies to Qwen-Audio-TTS, Qwen-Audio-Realtime, and CosyVoice.

Request body

# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
curl -X POST https://ap-southeast-1.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) 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 descriptions

Created voices go through a review process. The following statuses apply to Qwen-Audio-TTS, Qwen-Audio-Realtime, and CosyVoice.

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.

​Service endpoint

​Qwen-Audio-TTS/Qwen-Audio-Realtime/CosyVoice

​Request headers

​Create a voice

​Qwen-Audio-TTS/Qwen-Audio-Realtime/CosyVoice

​Request body

​Response body

​Query voice list

​Request body

​Response body

​Query voice details

​Request body

​Response body

​Update a voice

​Request body

​Response body

​Delete a voice

​Request body

​Response body

​Voice status descriptions

Service endpoint

Qwen-Audio-TTS/Qwen-Audio-Realtime/CosyVoice

Request headers

Create a voice

Qwen-Audio-TTS/Qwen-Audio-Realtime/CosyVoice

Request body

Response body

Query voice list

Request body

Response body

Query voice details

Request body

Response body

Update a voice

Request body

Response body

Delete a voice

Request body

Response body

Voice status descriptions