Alibaba Cloud Model Studio:Voice cloning

Qwen-Audio-TTS voice cloning

Step 1: Create a voice

Call the voice cloning API to upload audio and create a voice. The url parameter specifies the accessible URL of the audio file, and the prefix parameter serves as the voice name prefix.

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

Step 2: Synthesize speech with the cloned voice

Use the voice_id value returned in the previous step in the following request.

# 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

Step 1: Create a voice

Use the DashScope SDK or HTTP API to call the voice cloning API, upload audio, and create a voice. The target_model parameter specifies the real-time dialogue model name, and the prefix parameter serves as the voice name prefix.

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

Step 2: Use the cloned voice in a real-time dialogue session

Pass the voice_id returned in the previous step to the voice parameter in the session.update event. For details, see Voice configuration.

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

CosyVoice voice cloning

Step 1: Create a voice

Call the voice cloning API to upload audio and create a voice. The url parameter specifies the accessible URL of the audio file, and the prefix parameter serves as the voice name prefix.

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

Step 2: Synthesize speech with the cloned voice

Use the voice_id value returned in the previous step in the following request.

# 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

The following examples use a local audio file voice.mp3. Replace it with your actual file path when running the code.

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

Recording equipment

You can use a smartphone, digital voice recorder, or professional recording device. We recommend a device that supports high sample rate recording (≥ 24 kHz) to meet the audio requirements.

Recording environment

Location

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

Noise control

• 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 control

• 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

Using a typical bedroom as an example, after completing noise and reverberation control:

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.

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.

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

No. A voice is bound to a specific speech synthesis model through the target_model parameter at creation time and cannot be used across models. If you need to use the same audio's voice with multiple models, create a separate voice for each model.

Q: How long is a cloned voice valid?

Voices created by Qwen-Audio-TTS, Qwen-Audio-Realtime, Qwen-TTS, and CosyVoice are valid indefinitely by default. If a voice has not been used for any speech synthesis request in the past year, the system automatically deletes it. For details, see Voice quota and automatic cleanup. We recommend saving the voice ID. You can use the query API to check whether a voice is still available.

Q: Does poor audio quality affect cloning results?

Yes. The quality of the input audio directly affects the cloning result. Background noise, reverberation, and multiple voices all reduce the similarity and naturalness of the cloned voice. We recommend preparing your sample following the Audio requirements and Recording tips.