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(Qwen-Audio-TTS/CosyVoice)

  • China (Beijing)
  • Singapore
POST https://{WorkspaceId}.cn-beijing.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.

Service endpoint (MiniMax)

HTTP request URL: POST https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation base_url for SDK calls: https://dashscope.aliyuncs.com/api/v1
Third-party models (MiniMax) currently only support access through the dashscope.aliyuncs.com domain and do not support dedicated endpoints.

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(Qwen-Audio-TTS/CosyVoice)

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.1-tts-flash, 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.1-tts-flash, 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.1-tts-flash, 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 Beijing region endpoint. For the Singapore region, use: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization.Replace {WorkspaceId} with your actual workspace ID.
curl -X POST https://{WorkspaceId}.cn-beijing.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"
}

Create a voice (MiniMax)

A voice cloning request generates a demo audio clip. The demo audio is billed at the synchronous TTS rate of the selected model.

Request body

modelstring(required)The speech model used to generate the demo audio.Supported models:
  • MiniMax/speech-2.8-hd
  • MiniMax/speech-02-hd
  • MiniMax/speech-2.8-turbo
  • MiniMax/speech-02-turbo
inputobject(required)

Properties

actionstring(required)The operation to perform. Set to voice_clone for voice cloning.audio_urlstring(required)The URL of the audio file to clone. The audio must meet the following requirements:
  • Format: mp3, m4a, or wav
  • Duration: at least 10 seconds and no more than 5 minutes
  • File size: no more than 20 MB
clone_promptobject(optional)A sample audio clip for voice cloning. Providing this parameter improves voice similarity and stability during synthesis.
prompt_audiostring(optional)The URL of the sample audio file. The audio must meet the following requirements:
  • Format: mp3, m4a, or wav
  • Duration: less than 8 seconds
  • File size: no more than 20 MB
prompt_textstring(optional)The transcript of the sample audio. The text must match the audio content exactly and end with a punctuation mark.
textstring(required)The text to synthesize as demo audio for the cloned voice. Maximum: 1,000 characters.
The demo audio is billed at the standard TTS rate per character. For pricing details, see MiniMax model pricing.
  • Interjection tags: When using speech-2.8-hd or speech-2.8-turbo, you can insert interjection tags in the text. Supported interjections: (laughs) (laughter), (chuckle) (chuckle), (coughs) (cough), (clear-throat) (throat clearing), (groans) (groan), (breath) (normal breath), (pant) (panting), (inhale) (inhale), (exhale) (exhale), (gasps) (gasp), (sniffs) (sniff), (sighs) (sigh), (snorts) (snort), (burps) (burp), (lip-smacking) (lip smacking), (humming) (humming), (hissing) (hissing), (emm) (hesitation), (whistles) (whistle), (sneezes) (sneeze), (crying) (crying), (applause) (applause)
voice_id string(required)The ID of the cloned voice (for example, "MiniMax001"). The ID must follow these naming rules:
  • Length: 8 to 256 characters
  • Must start with a letter
  • Allowed characters: letters, digits, hyphens (-), and underscores (_)
  • Must not end with a hyphen (-) or underscore (_)
  • Must be unique across all existing voice IDs. Duplicate IDs return an error.
The voice ID must be globally unique across all voices in your account. Include a timestamp or other unique identifier in the ID to avoid conflicts.
language_boostenum<string>(optional) Default: nullWhether to enhance recognition accuracy for a specific language or dialect. Set to auto to let the model detect the language automatically.
Chinese, Chinese,Yue, English, Arabic, Russian, Spanish, French, Portuguese, German, Turkish, Dutch, Ukrainian, Vietnamese, Indonesian, Japanese, Italian, Korean, Thai, Polish, Romanian, Greek, Czech, Finnish, Hindi, Bulgarian, Danish, Hebrew, Malay, Persian, Slovak, Swedish, Croatian, Filipino, Hungarian, Norwegian, Slovenian, Catalan, Nynorsk, Tamil, Afrikaans,auto
need_noise_reductionboolean (optional) Default: falseWhether to enable noise reduction for the audio used for cloning.need_volume_normalizationboolean (optional) Default: falseWhether to enable volume normalization.aigc_watermarkboolean (optional) Default: falseWhether to add an AI watermark to the synthesized demo audio.
# Third-party models (MiniMax) currently only support dashscope.aliyuncs.com
curl -X POST 'https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "input": {
      "action": "voice_clone",
      "voice_id": "bailian-test-voice-22",
      "audio_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/cosyvoice/cosyvoice-zeroshot-sample.wav",
      "text": "How is the weather today?"
    },
    "model": "MiniMax/speech-2.8-turbo"
  }'

Response body

request_idstringThe unique identifier of this request.outputobject

Properties

input_sensitivebooleanWhether the input audio triggered content moderation.input_sensitive_typeintegerThe type of content moderation violation detected in the input audio:
  • 0: Normal (no violation)
  • 1: Severe violation
  • 2: Pornographic content
  • 3: Advertising
  • 4: Prohibited content
  • 5: Abusive language
  • 6: Violent or terrorist content
  • 7: Other
demo_audiostringURL of the demo audio.base_respobject
status_codeintegerStatus code:
  • 0: Success
  • 1000: Unknown error
  • 1001: Timeout
  • 1002: Rate limit exceeded
  • 1004: Authentication failed
  • 1013: Internal server error
  • 2013: Invalid input format
  • 2038: Insufficient permissions for voice cloning. Check your account authentication status.
status_msgstringA description of the status.
usageobjectCharacter usage for this request.

Properties

characters integerThe number of characters in the input text.
{
    "output": {
        "base_resp": {
            "status_code": 0,
            "status_msg": "success"
        },
        "demo_audio": "https://minimax-algeng-chat-tts.oss-cn-wulanchabu.aliyuncs.com/audio%2Feffect%2F05fdf023562aea84632d2a8c01c2366f_1773059375796_1311.mp3?Expires=1773232175&OSSAccessKeyId=YOUR_ACCESS_KEY_ID&Signature=YOUR_SIGNATURE",
        "input_sensitive": false,
        "input_sensitive_type": 0
    },
    "usage": {
        "characters": 18
    },
    "request_id": "b1160386-ebf1-913f-9275-ef176c5e1c91"
}

Query voice list

MiniMax doesn't support querying the voice list through this operation. To query the available voice IDs (including system voices and cloned voices) of MiniMax series models (such as MiniMax/speech-2.8-turbo), see Voice Management.

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 Beijing region endpoint. For the Singapore region, use: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization.Replace {WorkspaceId} with your actual workspace ID.
curl -X POST https://{WorkspaceId}.cn-beijing.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). MiniMax models don't support the query voice details operation.

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 Beijing region endpoint. For the Singapore region, use: https://{WorkspaceId}.ap-southeast-1.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}.cn-beijing.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). MiniMax models don't support the update operation.

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 Beijing region endpoint. For the Singapore region, use: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization.
curl -X POST https://{WorkspaceId}.cn-beijing.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

MiniMax doesn't support querying the voice list through this operation. To query the available voice IDs (including system voices and cloned voices) of MiniMax series models (such as MiniMax/speech-2.8-turbo), see Voice Management.

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 Beijing region endpoint. For the Singapore region, use: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization.Replace {WorkspaceId} with your actual workspace ID.
curl -X POST https://{WorkspaceId}.cn-beijing.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
3D Model Generation
Audio
Real-time Multimodal
Realtime API
Text Embedding
Translation models
Decision Model
More Models
Toolkit/Framework
TokenPlan
Model Production
File Management
Billing
Model Management
More