Voice cloning

​

Overview

• Qwen-Audio-TTS / CosyVoice: Create voices through the DashScope SDK or HTTP API. Supports real-time speech synthesis. Available in the Beijing and Singapore regions.
• Qwen-Audio-Realtime: Qwen-Audio-Realtime is a real-time voice dialogue model (not a speech synthesis model). Voice cloning is used to customize the TTS voice of the dialogue model's responses. Create voices through the DashScope SDK or HTTP API. Available in the China (Beijing) region only.
• Qwen-TTS: Create voices through the HTTP API. Supports real-time and non-real-time speech synthesis. Available in the Beijing and Singapore regions.

​

Prerequisites

1. Configure an API key and set it as an environment variable.
2. If you call the API through the DashScope SDK, install the latest SDK.
3. Prepare an audio file: The audio must meet the Audio requirements.

​

Quick start

1. Prepare audio: Prepare an audio file that meets the Audio requirements.
2. Create a voice: Call the voice cloning API to upload audio and create a voice. Use the target_model parameter to specify the speech synthesis model to bind.
3. Synthesize speech with the cloned voice: Call the speech synthesis API with the voice ID returned in the previous step.

​

Qwen-Audio-TTS 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",
        "url": "https://your-audio-url.wav"
    }
}'

# coding=utf-8

import dashscope
from dashscope.audio.tts_v2 import *
import os

# The API Keys for Singapore and Beijing regions are different. Get your API Key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# If the environment variable is not configured, replace the following line with your Model Studio API Key: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# The following is the configuration for the Singapore region. Replace "{WorkspaceId}" with your actual workspace ID when calling. The configuration varies by region.
dashscope.base_websocket_api_url='wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference'

# Voice cloning and speech synthesis must use the same model
model = "qwen-audio-3.0-tts-flash"
# Replace the voice parameter with the custom voice generated by voice cloning
voice = "voice_id"

# Instantiate SpeechSynthesizer, passing the model, voice, and other request parameters in the constructor
synthesizer = SpeechSynthesizer(model=model, voice=voice)
# Send text for synthesis and get binary audio
audio = synthesizer.call("What's the weather like today?")
# The first text submission requires establishing a WebSocket connection, so the first-packet latency includes the connection setup time
print('[Metric] requestId: {}, first-packet latency: {} ms'.format(
    synthesizer.get_last_request_id(),
    synthesizer.get_first_package_delay()))

# Save audio to a local file
with open('output.mp3', 'wb') as f:
    f.write(audio)

​

Qwen-Audio-Realtime voice cloning

import os
import requests

# If not set as an environment variable, replace with your API Key: api_key = "sk-xxx"
api_key = os.environ.get('DASHSCOPE_API_KEY')

# Qwen-Audio-Realtime is available in the Beijing region only.
# Replace {WorkspaceId} with your actual Workspace ID (use a Beijing region API key).
url = 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization'

response = requests.post(
    url,
    headers={
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    },
    json={
        'model': 'voice-enrollment',
        'input': {
            'action': 'create_voice',
            'target_model': 'qwen-audio-3.0-realtime-plus',
            'prefix': 'myvoice',
            'url': 'https://your-audio-url.wav'
        }
    }
)
result = response.json()
print('voice_id:', result['output']['voice_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-realtime-plus",
        "prefix": "myvoice",
        "url": "https://your-audio-url.wav"
    }
}'

{"type":"session.update","session":{"voice":"qwen-audio-3.0-realtime-plus-myvoice-xxxxxx"}}

​

CosyVoice 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": "cosyvoice-v3.5-plus",
        "prefix": "myvoice",
        "url": "https://your-audio-url.wav"
    }
}'

# coding=utf-8

import dashscope
from dashscope.audio.tts_v2 import *
import os

# The API Keys for Singapore and Beijing regions are different. Get your API Key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# If the environment variable is not configured, replace the following line with your Model Studio API Key: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# The following is the configuration for the Singapore region. Replace "{WorkspaceId}" with your actual workspace ID when calling. The configuration varies by region.
dashscope.base_websocket_api_url='wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference'

# Voice cloning and speech synthesis must use the same model
model = "cosyvoice-v3.5-plus"
# Replace the voice parameter with the custom voice generated by voice cloning
voice = "voice_id"

# Instantiate SpeechSynthesizer, passing the model, voice, and other request parameters in the constructor
synthesizer = SpeechSynthesizer(model=model, voice=voice)
# Send text for synthesis and get binary audio
audio = synthesizer.call("What's the weather like today?")
# The first text submission requires establishing a WebSocket connection, so the first-packet latency includes the connection setup time
print('[Metric] requestId: {}, first-packet latency: {} ms'.format(
    synthesizer.get_last_request_id(),
    synthesizer.get_first_package_delay()))

# Save audio to a local file
with open('output.mp3', 'wb') as f:
    f.write(audio)

​

Qwen-TTS voice cloning

import os
import requests
import base64
import pathlib
import dashscope

# ======= Constants =======
DEFAULT_TARGET_MODEL = "qwen3-tts-vc-2026-01-22"  # Voice cloning and speech synthesis must use the same model
DEFAULT_PREFERRED_NAME = "guanyu"
DEFAULT_AUDIO_MIME_TYPE = "audio/mpeg"
VOICE_FILE_PATH = "voice.mp3"  # Relative path to the local audio file used for voice cloning

def create_voice(file_path: str,
                 target_model: str = DEFAULT_TARGET_MODEL,
                 preferred_name: str = DEFAULT_PREFERRED_NAME,
                 audio_mime_type: str = DEFAULT_AUDIO_MIME_TYPE) -> str:
    """
    Create a voice and return the voice parameter
    """
    # The API Keys for Singapore and Beijing regions are different. Get your API Key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    # If the environment variable is not configured, replace the following line with your Model Studio API Key: api_key = "sk-xxx"
    api_key = os.getenv("DASHSCOPE_API_KEY")

    file_path_obj = pathlib.Path(file_path)
    if not file_path_obj.exists():
        raise FileNotFoundError(f"Audio file not found: {file_path}")

    base64_str = base64.b64encode(file_path_obj.read_bytes()).decode()
    data_uri = f"data:{audio_mime_type};base64,{base64_str}"

    # The following is the configuration for the Singapore region.
    url = "https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization"
    payload = {
        "model": "qwen-voice-enrollment", # Do not modify this value
        "input": {
            "action": "create",
            "target_model": target_model,
            "preferred_name": preferred_name,
            "audio": {"data": data_uri}
        }
    }
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }

    resp = requests.post(url, json=payload, headers=headers)
    if resp.status_code != 200:
        raise RuntimeError(f"Failed to create voice: {resp.status_code}, {resp.text}")

    try:
        return resp.json()["output"]["voice"]
    except (KeyError, ValueError) as e:
        raise RuntimeError(f"Failed to parse voice response: {e}")

if __name__ == '__main__':
    # The following is the configuration for the Singapore region.
    dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

    text = "What's the weather like today?"
    response = dashscope.MultiModalConversation.call(
        model=DEFAULT_TARGET_MODEL,
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        text=text,
        voice=create_voice(VOICE_FILE_PATH), # Replace the voice parameter with the custom voice generated by voice cloning
        stream=False
    )
    print(response)

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-2026-01-22",
        "preferred_name": "guanyu",
        "audio": {
            "data": "https://xxx.wav"
        }
    }
}'

curl -X POST 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
    "model": "qwen3-tts-vc-2026-01-22",
    "input": {
        "text": "What's the weather like today?",
        "voice": "YOUR_VOICE_ID"
    }
}'

​

Audio requirements

​

Recording tips

​

Recording equipment

​

Recording environment

• Record in a small, enclosed space of 10 square meters or less.
• Prioritize rooms with sound-absorbing materials such as acoustic foam, carpets, or curtains.
• Avoid open halls, conference rooms, classrooms, and other high-reverberation spaces.

• External noise: Close doors and windows to avoid traffic, construction, and other disturbances.
• Internal noise: Turn off air conditioners, fans, fluorescent lamp ballasts, and other equipment. You can record the ambient sound on your phone and play it back at high volume to identify potential noise sources.

• Reverberation causes sound to become blurry and reduces clarity.
• Reduce reflections from smooth surfaces: close curtains, open wardrobe doors, and drape clothing or blankets over tables and cabinets.
• Use irregular objects (such as bookshelves and upholstered furniture) to create diffuse reflections.

​

Recording script

• There are no specific content restrictions. We recommend matching the content to your target use case.
• Avoid short phrases (such as "hello" or "yes"). Use complete sentences.
• Maintain semantic coherence and avoid frequent pauses while reading (at least 3 continuous seconds without interruption is recommended).
• Maintain a consistent speaking speed throughout. Avoid speaking too fast at the beginning or end, which can cause stuttering during synthesis.
• Include appropriate emotional expression (such as warmth, friendliness, or seriousness). Avoid mechanical reading.
• Do not include sensitive content (such as political, pornographic, or violent material). This will cause cloning to fail.

​

Best practices

1. Familiarize yourself with the script beforehand, set a character tone, and deliver naturally.
2. Maintain approximately 10 cm distance from the recording device to avoid plosive distortion or weak signal.

​

Manage custom voices

• List voices: Retrieve a list of all custom voices under the current account.
• Get voice details (Qwen-Audio-TTS / Qwen-Audio-Realtime / CosyVoice only): View detailed information about a specific voice, such as creation time and bound speech synthesis model.
• Delete a voice: Delete custom voices that are no longer needed to free up quota.

​

Quota and billing

​

Voice quota and automatic cleanup

• Voice limit: Each Alibaba Cloud Model Studio account can create up to 1,000 custom voices for Qwen-Audio-TTS / Qwen-Audio-Realtime / CosyVoice and up to 1,000 for Qwen-TTS (the two quotas are calculated independently). After reaching the limit, new creation requests will fail and return an error. The system does not automatically delete the earliest created voices. To create new voices, delete unneeded voices to free up quota, or wait for unused voices to be automatically cleaned up (see the automatic cleanup rules below).
• Behavior after reaching the limit: After reaching the 1,000-voice limit, subsequent calls to the voice creation API will return a failure error. The system does not automatically evict the earliest created voices to make room. You must manually delete unneeded voices to free up quota before you can continue creating voices.
• Automatic cleanup rule: If a voice has not been used for any speech synthesis request in the past year, the system automatically deletes it.

​

Billing rules

• Qwen-Audio-TTS / Qwen-Audio-Realtime / CosyVoice: Voice creation is free.
• Qwen-TTS: Billed at $0.01/voice. Failed creations are not billed. Free quota (available in the Singapore region only):
  • Within 90 days of activating Alibaba Cloud Model Studio, you can create up to 1,000 voices for free.
  • Failed creations do not count against the free quota.
  • Deleting a voice does not restore the free quota.
  • After the free quota is used up or the 90-day period expires, voice creation is billed at $0.01/voice.

​

Supported models and regions

​

API reference

​

FAQ

​

Q: Can I use a created voice with different speech synthesis models?

​

Q: How long is a cloned voice valid?

​

Q: Does poor audio quality affect cloning results?