Skip to main content
Omni-modal

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 API parameters, requests, and responses, see the Voice cloning API reference.
This guide covers voice cloning for Qwen-Omni and Qwen-Omni-Realtime. For text-to-speech models, see Speech synthesis.

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.
ItemRequirement
Supported formatsWAV (16-bit), MP3, M4A
Duration10 to 20 seconds recommended. Maximum: 60 seconds.
File size< 10 MB
Sample rate>= 24 kHz
ChannelsMono
ContentThe 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.
LanguagesChinese (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 a voice API and upload an audio clip. The system analyzes the audio and creates a custom cloned voice. You must specifytarget_modelin this step to declare which omni model will drive the voice. Skip this step if you already have a voice. Check existing voices with the List voices API.
  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
# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
dashscope.base_http_api_url = "https://ap-southeast-1.maas.qwencloudapi.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.
    """
    # 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}"

    url = "https://ap-southeast-1.maas.qwencloudapi.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")
    url = "wss://ap-southeast-1.maas.qwencloudapi.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.
No dedicated count endpoint exists. 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: billed at $0.01/voice. Failed creations are not billed.
    Free quota (Beijing and Singapore regions only). To claim, query, or use it, see Free quota for new users.
    • 1,000 free voice creations within 90 days of activating QwenCloud.
    • 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.