Voice cloning HTTP API reference_Alibaba Cloud Model Studio(Model Studio) - Alibaba Cloud Model Studio

Use the HTTP API to create, list, query, update, and delete cloned voices.

Service endpoint

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

Singapore

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization

Replace {WorkspaceId} with your actual workspace ID.

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) and Singapore 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
Singapore: from dashscope-intl.aliyuncs.com to {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

Request headers

Parameter Type Required Description

Parameter	Type	Required	Description
Authorization	string	Yes	Authentication token in the format `Bearer <your_api_key>`. Replace `<your_api_key>` with your actual 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`.

Authorization

string

Yes

Authentication token in the format Bearer <your_api_key>. Replace <your_api_key> with your actual 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

modelstring(required)

Set to voice-enrollment.

inputobject(required)

The input parameters.

Properties

action string(required)

Set to create_voice.

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.

audio string(required)

Reference audio for voice cloning. Accepts a publicly accessible URL or a Base64 Data URI, such as data:audio/wav;base64,....

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

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

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.

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

Click to view supported languages by model

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

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.

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.

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

This example uses the Singapore region endpoint. For the Beijing region, use: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization.

Replace {WorkspaceId} with your actual workspace ID.

Voice cloning

curl -X POST https://{WorkspaceId}.ap-southeast-1.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": "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")

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.

usageobject

Usage information for this request.

Properties

count integer

The number of voices created. Always 1.

Voice cloning

{
    "output": {
        "voice_id": "qwen-audio-3.0-tts-flash-myvoice-xxxxxx"
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

Query voice list

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

Request body

modelstring(required)

Set to voice-enrollment.

inputobject(required)

The input parameters.

Properties

action string(required)

Set to list_voice.

prefix string(optional)

Filters voices by name prefix.

page_index integer(optional)

The page index.

page_size integer(optional)

The number of entries per page.

This example uses the Singapore region endpoint. For the Beijing region, use: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization.

Replace {WorkspaceId} with your actual workspace ID.

Query voice list

curl -X POST https://{WorkspaceId}.ap-southeast-1.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 queried voices.

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

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

usageobject

Usage information for this request.

Properties

count integer

Always 1.

Query voice list

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

Query voice details

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

Request body

modelstring(required)

Set to voice-enrollment.

inputobject(required)

The input parameters.

Properties

action string(required)

Set to query_voice.

voice_id string(required)

The voice ID to query.

This example uses the Singapore region endpoint. For the Beijing region, use: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization.

Replace {WorkspaceId} with your actual workspace ID.

Query voice details

curl -X POST https://{WorkspaceId}.ap-southeast-1.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

resource_linkstring

The URL of the audio file.

gmt_createstring

The creation time.

gmt_modifiedstring

The last modification time.

statusstring

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

target_modelstring

The TTS model that drives the cloned voice.

usageobject

Usage information for this request.

Properties

count integer

Always 1.

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

Update a voice

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

Request body

modelstring(required)

Set to voice-enrollment.

inputobject(required)

The input parameters.

Properties

action string(required)

Set to update_voice.

voice_id string(required)

The voice ID to update.

audio string(required)

New reference audio. Accepts a publicly accessible URL or a Base64 Data URI, such as data:audio/wav;base64,....

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

This example uses the Singapore region endpoint. For the Beijing region, use: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization.

curl -X POST https://{WorkspaceId}.ap-southeast-1.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": "update_voice",
        "voice_id": "yourVoiceId",
        "audio": "https://new-audio-url.wav"
    }
}'

Response body

request_idstring

The unique identifier of this request.

outputobject

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.

usageobject

Usage information for this request.

Properties

count integer

Always 1.

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

Delete a voice

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

Request body

modelstring(required)

Set to voice-enrollment.

inputobject(required)

The input parameters.

Properties

action string(required)

Set to delete_voice.

voice_id string(required)

The voice ID to delete.

This example uses the Singapore region endpoint. For the Beijing region, use: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization.

Replace {WorkspaceId} with your actual workspace ID.

Delete a voice

curl -X POST https://{WorkspaceId}.ap-southeast-1.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.

Delete a voice

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

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.