Skip to main content

Voice cloning

Upload a recording to create a voice, then use it in Qwen-Omni or Qwen-Omni-Realtime conversations. This guide covers supported languages, audio requirements, cloning steps, billing, and voice management.

For request parameters, responses, and errors, see the Voice cloning API reference.
This document covers the voice cloning APIs for Qwen-Omni and Qwen-Omni-Realtime. For speech synthesis models, see the Voice cloning user guide.
Workspace-specific domains are available in the China (Beijing) and Singapore regions. They improve inference performance and stability. We recommend migrating to these domains:
  • China (Beijing): from https://dashscope.aliyuncs.com to https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore: from https://dashscope-intl.aliyuncs.com to https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Find your {WorkspaceId} on the Workspace Details page in the Alibaba Cloud Model Studio console. The old domain still works.

Audio requirements

Recording quality affects cloning results. System voices and voice cloning support different dialects. The table below lists the languages and dialects for voice cloning. For system voices, see the voice list.

Item

Requirement

Supported formats

WAV (16-bit), MP3, M4A

Duration

10 to 20 seconds recommended. Maximum: 60 seconds.

File size

< 10 MB

Sample rate

>= 24 kHz

Channels

Mono

Content

The audio must contain at least 3 seconds of continuous, clear speech with no background sounds. The remaining portion may include brief pauses (<=2 seconds). Avoid background music, noise, or other voices throughout the entire audio. Use normal spoken audio as input. Don't upload songs or singing audio.

Languages

Chinese (zh), English (en), German (de), Italian (it), Portuguese (pt), Spanish (es), Japanese (ja), Korean (ko), French (fr), Russian (ru), Thai (th), Indonesian (id), Arabic (ar), Czech (cs), Danish (da), Dutch (nl), Finnish (fi), Hebrew (he), Hindi (hi), Icelandic (is), Malay (ms), Norwegian (no), Persian (fa), Polish (pl), Swedish (sv), Tagalog (tl), Turkish (tr), Urdu (ur), Vietnamese (vi)

Chinese dialects: Dongbei, Shannxi, Sichuan, Henan, Changsha, Tianjin, Hangzhou, Liaoning, Shenyang, Anshan

Quick start

image

1. Workflow

Create a voice, then use it in a model call:
  1. Create a voice Call the Create voice API and upload an audio clip. The system analyzes the audio and creates a custom cloned voice. You must specify target_model in this step to declare which omni model will use the voice. If you already have a voice, you can skip this step and continue to the next step. Call the List voices API to view existing voices.
  2. Use the voice in a conversation Call the Omni API (realtime or non-realtime) with the created voice. The Omni model must match target_model.

2. Model configuration and prerequisites

Select the models, then complete the prerequisites.

Model configuration

Voice cloning requires two models:
  • Voice cloning model: qwen-voice-enrollment
  • Omni model that drives the voice:
    • qwen3.8-omni-flash-realtime
    • qwen3.5-omni-plus-realtime
    • qwen3.5-omni-flash-realtime
    • qwen3.5-omni-plus
    • qwen3.5-omni-flash

Prerequisites

  1. Get an API key: Obtain an API key. For security, configure the API key as an environment variable.
  2. Install the SDK: Install the latest DashScope SDK.
  3. Prepare the audio for cloning: The audio must meet the Audio requirements.

3. End-to-end example

This example clones a voice and uses it in a conversation. Key principle: The target_model specified during cloning must match the model in the subsequent Omni API call. Otherwise, synthesis fails. Replace the example file voice.mp3 with your own audio.
  • Realtime
  • Non-realtime
Applies to Qwen-Omni-Realtime models. See Qwen-Omni-Realtime.
Python
# Requirements: dashscope >= 1.26.5, pyaudio
import os
import requests
import base64
import pathlib
import time
import pyaudio
from dashscope.audio.qwen_omni import MultiModality, OmniRealtimeCallback, OmniRealtimeConversation
import dashscope
# China (Beijing) region. Replace {WorkspaceId} with your Bailian workspace ID. URLs vary by region.
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

# ======= Configuration =======
DEFAULT_TARGET_MODEL = "qwen3.8-omni-flash-realtime"  # Must be the same model for cloning and conversation
DEFAULT_PREFERRED_NAME = "guanyu"
DEFAULT_AUDIO_MIME_TYPE = "audio/mpeg"
VOICE_FILE_PATH = "voice.mp3"  # Path to the local audio file 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 custom voice and return the voice parameter.
    """
    # API keys differ between the Singapore and Beijing regions. Get an API key: https://www.alibabacloud.com/help/model-studio/get-api-key
    # If you haven't set an environment variable, replace the following line with: 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 Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
    url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization"
    payload = {
        "model": "qwen-voice-enrollment",
        "parameters": {"voice_clone_mode": "normal"},
        "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}")

class SimpleCallback(OmniRealtimeCallback):
    def __init__(self, pya):
        self.pya = pya
        self.out = None
    def on_open(self):
        self.out = self.pya.open(
            format=pyaudio.paInt16,
            channels=1,
            rate=24000,
            output=True
        )
    def on_event(self, response):
        if response['type'] == 'response.audio.delta':
            self.out.write(base64.b64decode(response['delta']))
        elif response['type'] == 'conversation.item.input_audio_transcription.completed':
            print(f"[User] {response['transcript']}")
        elif response['type'] == 'response.audio_transcript.done':
            print(f"[LLM] {response['transcript']}")

if __name__ == '__main__':
    # If you haven't set an environment variable, replace the following line with: dashscope.api_key = "sk-xxx"
    dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")
    # The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
    url = "wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime"

    # Step 1: Clone a voice
    voice = create_voice(VOICE_FILE_PATH)
    print(f"Voice cloning complete. Voice: {voice}")

    # Step 2: Start a real-time conversation with the cloned voice
    pya = pyaudio.PyAudio()
    callback = SimpleCallback(pya)
    conv = OmniRealtimeConversation(model=DEFAULT_TARGET_MODEL, callback=callback, url=url)
    conv.connect()
    conv.update_session(
        output_modalities=[MultiModality.AUDIO, MultiModality.TEXT],
        voice=voice  # Use the cloned voice
    )
    mic = pya.open(format=pyaudio.paInt16, channels=1, rate=16000, input=True)
    print("Conversation started. Speak into your microphone (Ctrl+C to exit)...")
    try:
        while True:
            audio_data = mic.read(3200, exception_on_overflow=False)
            conv.append_audio(base64.b64encode(audio_data).decode())
            time.sleep(0.01)
    except KeyboardInterrupt:
        conv.close()
        mic.close()
        callback.out.close()
        pya.terminate()
        print("\nConversation ended")

Voice quota and auto-cleanup

Total limit: 1,000 voices per account.
This API does not provide a voice count endpoint. Call the List voices API to count your voices.
Auto-cleanup: Voices unused for one year are automatically deleted.

Billing

Voice cloning and model invocation are billed separately:
  • Voice cloning: Create voice costs $0.01 per voice. Failed creation requests are not charged.
    Free quota (China site Beijing region and International site Singapore region only):
    • 1,000 free voice creations within 90 days of activating Model Studio.
    • Failed creations don't consume the free quota.
    • Deleting a voice doesn't 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.
  • Conversations with a cloned voice are billed by model token usage. See Model inference pricing.
You are responsible for the ownership and legal use of the voice you provide. Read the Service Agreement.

Recording guide

Recording equipment

Use a noise-cancelling microphone, or record with a phone at close range in a quiet environment.

Recording environment

Location

  • Record in a small enclosed space of 10 square meters or less.
  • Choose a room with sound-absorbing materials such as acoustic foam, carpets, or curtains.
  • Avoid large open halls, conference rooms, or classrooms where reverberation is high.

Noise control

  • Outdoor noise: Close doors and windows to block traffic, construction, and other external sounds.
  • Indoor noise: Turn off air conditioners, fans, and fluorescent light ballasts.
  • Record ambient sound with your phone and play it back at high volume to identify hidden noise sources.

Reverberation control

  • Reverberation causes audio to sound muffled and reduces clarity.
  • Reduce reflections from smooth surfaces: close curtains, open wardrobe doors, and cover desks and shelves with clothing or blankets.
  • Use irregular objects such as bookshelves and upholstered furniture to create diffuse reflections.

Script preparation

  • Match the script to the target use case. For example, use customer service dialog style for a customer service scenario.
  • Make sure the script doesn't contain sensitive or illegal content (such as political, pornographic, or violent material), as this causes cloning to fail.
  • Avoid short phrases (such as "hello" or "yes"). Use complete sentences.
  • Maintain semantic coherence and avoid frequent pauses when reading. At least 3 consecutive seconds without interruption is recommended.
  • You can use the target emotion, such as friendly or serious. Keep the tone natural and avoid exaggerated delivery.
Using a typical bedroom as an example:
  1. Close doors and windows to block external noise.
  2. Turn off air conditioners, fans, and other appliances.
  3. Close curtains to reduce glass reflections.
  4. Cover the desk surface with clothing or a blanket to reduce desktop reflections.
  5. Practice the script, choose the character's tone, and speak naturally.
  6. Maintain about 10 cm distance from the recording device to avoid plosive distortion or weak signal.