Skip to main content

Voice cloning HTTP API reference

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

User guide: Voice cloning.

Service endpoint

  • Singapore
  • China (Beijing)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customizationReplace {WorkspaceId} with your actual workspace ID.
Alibaba 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
Replace {WorkspaceId} with your actual Workspace ID. The existing domains remain fully functional.

Request headers

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 to application/json for Qwen-Audio-TTS/CosyVoice, or application/json; charset=utf-8 for MiniMax.

Create a voice

Request body

modelstring(required)The voice cloning model. Valid values:
  • voice-enrollment: Qwen-Audio-TTS/CosyVoice voice cloning.
inputobject(required)The input parameters.

Properties

action string(required)The action type.
  • Qwen-Audio-TTS/CosyVoice (voice-enrollment): Set to create_voice.
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(required)
Applies only to Qwen-Audio-TTS/CosyVoice voice cloning (when model is voice-enrollment).
The URL of the audio file for voice cloning. The URL must be publicly accessible.prefix string(required)
Applies only to Qwen-Audio-TTS/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}.language_hints array[string](optional)
Applies only to Qwen-Audio-TTS/CosyVoice voice cloning (when model is voice-enrollment). Supported only by qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, 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:
  • qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-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)
Applies only to Qwen-Audio-TTS/CosyVoice voice cloning (when model is voice-enrollment). Supported only by qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, 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].Default: 10.0.enable_preprocess boolean(optional)
Applies only to Qwen-Audio-TTS/CosyVoice voice cloning (when model is voice-enrollment). Supported only by qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, 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.enable_volume_normalization string(optional)
Applies only to Qwen-Audio-TTS/CosyVoice voice cloning when model is set to voice-enrollment.
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.
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",
        "url": "https://your-audio-url.wav",
        "language_hints": ["en"],
        "enable_volume_normalization": "false"
    }
}'

Response body

request_idstringThe unique identifier of this request.outputobjectThe data returned by the model.

Properties

voice_idstringThe voice ID. Use it in the voice parameter of the TTS API.
usageobjectUsage information for this request.

Properties

count integerThe number of voices created. Always 1.
{
    "output": {
        "voice_id": "qwen-audio-3.0-tts-flash-myvoice-xxxxxx"
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

Query voice list

Request body

modelstring(required)The voice cloning model. Valid values:
  • voice-enrollment: Qwen-Audio-TTS/CosyVoice voice cloning.
inputobject(required)The input parameters.

Properties

action string(required)Set to list_voice.prefix string(optional)
Applies only to Qwen-Audio-TTS/CosyVoice.
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.
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_idstringThe unique identifier of this request.outputobjectThe data returned by the model.

Properties

voice_listarray[object]The list of queried voices.

Properties

voice_idstringThe voice ID. Use it in the voice parameter of the TTS API.gmt_createstringThe creation time.gmt_modifiedstringThe last modification time.statusstring
Returned only by Qwen-Audio-TTS/CosyVoice.
The voice status. For valid values, see "Voice status descriptions".
usageobjectUsage information for this request.

Properties

count integerAlways 1.
{
    "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 only to Qwen-Audio-TTS/CosyVoice (when model is voice-enrollment)

Request body

modelstring(required)Set to voice-enrollment (Qwen-Audio-TTS/CosyVoice).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.
  • Qwen-Audio-TTS/CosyVoice
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_idstringThe unique identifier of this request.outputobjectThe data returned by the model.

Properties

resource_linkstringThe URL of the audio file.gmt_createstringThe creation time.gmt_modifiedstringThe last modification time.statusstringThe voice status. For valid values, see "Voice status descriptions".target_modelstringThe TTS model that drives the cloned voice.
usageobjectUsage information for this request.

Properties

count integerAlways 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 only to Qwen-Audio-TTS/CosyVoice voice cloning (when model is voice-enrollment)

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.url string(required)The URL of the new audio file. The URL must be publicly accessible.
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",
        "url": "https://new-audio-url.wav"
    }
}'

Response body

request_idstringThe unique identifier of this request.outputobjectThe 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.usageobjectUsage information for this request.

Properties

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

Delete a voice

Request body

modelstring(required)The voice cloning model. Valid values:
  • voice-enrollment: Qwen-Audio-TTS/CosyVoice voice cloning.
inputobject(required)The input parameters.

Properties

action string(required)Set to delete_voice.voice_id string(required)
Applies only to Qwen-Audio-TTS/CosyVoice.
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.
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_idstringThe unique identifier of this request.outputobjectThe data returned by the model. This is an empty object.usageobjectUsage information for this request.

Properties

count integerAlways 1.
{
    "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/CosyVoice when model is voice-enrollment.

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.

API Usage
Text Generation
Image Generation
Video Generation
World models
Audio
Real-time Multimodal
Realtime API
Text Embedding
Decision Model
More Models
Toolkit/Framework
TokenPlan
Model Production
File Management
Billing
Model Management
More