Qwen3-TTS Steps Up: Voice Cloning and Voice Design!

Qwen3-TTS family has launched two new models: the voice design model Qwen3-TTS-VD-Flash (accessible via the Qwen API) and the voice cloning model Qwen3-TTS-VC-Flash (accessible via the Qwen API).

Key Features:

• Voice Design：Qwen3-TTS-VD-Flash supports complex natural language instructions, enabling fine-grained control over timbre, prosody, emotion, persona, and more, achieving full control from “what to say” to “how to say it.” It allows users to freely define the desired voice, completely freeing them from only being able to clone existing voices or choose from a limited set of preset voices. On InstructTTS-Eval, it significantly outperforms GPT-4o-mini-tts and Mimo-audio-7b-instruct overall, and surpasses Gemini-2.5-pro-preview-tts in role-playing tests.

• Voice Cloning：Qwen3-TTS-VC-Flash supports 3-second voice cloning, and can generate speech in 10 major languages—Chinese, English, German, Italian, Portuguese, Spanish, Japanese, Korean, French, and Russian—based on the cloned voice. On the MiniMax TTS Multilingual Test Set, its average word error rate (WER) is consistently better than MiniMax, ElevenLabs, and GPT-4o-Audio-Preview.

• High Expressiveness：Qwen3-TTS-VD-Flash and Qwen3-TTS-VC-Flash offer highly expressive, humanlike voices that can stably and reliably produce speech closely aligned with the input text, automatically adjusting tone and rhythm according to semantic content for natural and vivid delivery.

• Robust Text Handling：Qwen3-TTS-VD-Flash and Qwen3-TTS-VC-Flash have strong text parsing capabilities, automatically handling complex text structures and accurately extracting key information, showing strong robustness when dealing with diverse and non-standard text formats.

Your browser does not support the video tag.

Qwen3-TTS-VD-Flash#

Qwen3-TTS supports creating customized voice profiles directly from natural language descriptions. Users can freely describe acoustic attributes, persona settings, background information, and more, making it easy to create the exact kind of voice they want.

Metrics#

Controllable generation: On the InstructTTS-Eval benchmark, Qwen3-TTS significantly outperforms GPT-4o-mini-tts and Mimo-audio-7b-instruct overall, and surpasses Gemini-2.5-pro-preview-tts on role‑playing tests.

Samples#

Users can also persistently store and repeatedly invoke the voices created by Qwen3-TTS, enabling the generation of vivid and natural multi-turn, multi-role long-form dialogues.

How to use#

Using Qwen3-TTS-VD-Flash via the Qwen API is very simple. Below is a short code snippet to try it out:

import requests
import base64
import os

def create_voice_and_play():
    # API keys differ between Singapore and Beijing regions. Get your API key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    # If you haven't set an environment variable, replace the line below with: api_key = "sk-xxx"
    api_key = os.getenv("DASHSCOPE_API_KEY")
    
    if not api_key:
        print("Error: DASHSCOPE_API_KEY environment variable not found. Please set your API key.")
        return None, None, None
    
    # Prepare request data
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    
    data = {
        "model": "qwen-voice-design",
        "input": {
            "action": "create",
            "target_model": "qwen3-tts-vd-realtime-2025-12-16",
            "voice_prompt": "A composed middle-aged male announcer with a deep, rich and magnetic voice, a steady speaking speed and clear articulation, is suitable for news broadcasting or documentary commentary.",
            "preview_text": "Dear listeners, hello everyone. Welcome to the evening news.",
            "preferred_name": "announcer",
            "language": "en"
        },
        "parameters": {
            "sample_rate": 24000,
            "response_format": "wav"
        }
    }
    
    # URL for Singapore region. For Beijing region, use: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization
    url = "https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization"
    
    try:
        # Send request
        response = requests.post(
            url,
            headers=headers,
            json=data,
            timeout=60  # Add timeout setting
        )
        
        if response.status_code == 200:
            result = response.json()
            
            # Get voice name
            voice_name = result["output"]["voice"]
            print(f"Voice name: {voice_name}")
            
            # Get preview audio data
            base64_audio = result["output"]["preview_audio"]["data"]
            
            # Decode Base64 audio data
            audio_bytes = base64.b64decode(base64_audio)
            
            # Save audio file locally
            filename = f"{voice_name}_preview.wav"
            
            # Write audio data to local file
            with open(filename, 'wb') as f:
                f.write(audio_bytes)
            
            print(f"Audio saved to local file: {filename}")
            print(f"File path: {os.path.abspath(filename)}")
            
            return voice_name, audio_bytes, filename
        else:
            print(f"Request failed. Status code: {response.status_code}")
            print(f"Response: {response.text}")
            return None, None, None
            
    except requests.exceptions.RequestException as e:
        print(f"Network request error: {e}")
        return None, None, None
    except KeyError as e:
        print(f"Response format error: missing required field: {e}")
        print(f"Response: {response.text if 'response' in locals() else 'No response'}")
        return None, None, None
    except Exception as e:
        print(f"Unexpected error: {e}")
        return None, None, None

if __name__ == "__main__":
    print("Creating voice...")
    voice_name, audio_data, saved_filename = create_voice_and_play()
    
    if voice_name:
        print(f"\nSuccessfully created voice '{voice_name}'")
        print(f"Audio file saved: '{saved_filename}'")
        print(f"File size: {os.path.getsize(saved_filename)} bytes")
    else:
        print("\nVoice creation failed")

Qwen3-TTS-VC-Flash#

Qwen3-TTS supports natural, 3‑second–level voice cloning, and can generate multilingual audio based on the cloned voice. It is also highly robust when handling complex text and in-the-wild audio.

Metrics#

Multilingual voice cloning: On the MiniMax TTS Multilingual Test Set, Qwen3‑TTS shows more stable content than MiniMax, ElevenLabs, and GPT‑4o‑Audio‑Preview for Chinese, English, French, Italian, and other languages, achieving the best average word error rate (WER).

Samples#

Want to hear how animals would sound if they could talk? Qwen3-TTS can show you cross-species cloning:

How to use#

Using Qwen3-TTS-VC-Flash via the Qwen API is very simple. Below is a short code snippet to try it out:

# The DashScope SDK version must be 1.23.9 or later, and the Python version must be 3.10 or later.
# coding=utf-8
# Installation instructions for pyaudio:
# APPLE Mac OS X
#   brew install portaudio
#   pip install pyaudio
# Debian/Ubuntu
#   sudo apt-get install python-pyaudio python3-pyaudio
#   or
#   pip install pyaudio
# CentOS
#   sudo yum install -y portaudio portaudio-devel && pip install pyaudio
# Microsoft Windows
#   python -m pip install pyaudio

import pyaudio
import os
import requests
import base64
import pathlib
import threading
import time
import dashscope  # The DashScope Python SDK version must be 1.23.9 or later.
from dashscope.audio.qwen_tts_realtime import QwenTtsRealtime, QwenTtsRealtimeCallback, AudioFormat

# ======= Constant configuration =======
DEFAULT_TARGET_MODEL = "qwen3-tts-vc-realtime-2025-11-27"  # The same model must be used for voice cloning and speech synthesis.
DEFAULT_PREFERRED_NAME = "guanyu"
DEFAULT_AUDIO_MIME_TYPE = "audio/mpeg"
VOICE_FILE_PATH = "voice.mp3"  # The relative path of the local audio file for voice cloning.

TEXT_TO_SYNTHESIZE = [
    'Right? I really like this kind of supermarket,',
    'especially during the New Year.',
    'Going to the supermarket',
    'just makes me feel',
    'super, super happy!',
    'I want to buy so many things!'
]

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 the Singapore and Beijing regions are different. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key.
    # If you have not configured the environment variable, 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"The audio file does not exist: {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 URL for the Singapore region. If you use a model in the Beijing region, replace the URL with: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization
    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 the voice: {resp.status_code}, {resp.text}")

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

def init_dashscope_api_key():
    """
    Initialize the API key for the DashScope SDK.
    """
    # The API keys for the Singapore and Beijing regions are different. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key.
    # If you have not configured the environment variable, replace the following line with your Model Studio API key: dashscope.api_key = "sk-xxx"
    dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")

# ======= Callback class =======
class MyCallback(QwenTtsRealtimeCallback):
    """
    Custom TTS streaming callback.
    """
    def __init__(self):
        self.complete_event = threading.Event()
        self._player = pyaudio.PyAudio()
        self._stream = self._player.open(
            format=pyaudio.paInt16, channels=1, rate=24000, output=True
        )

    def on_open(self) -> None:
        print('[TTS] Connection established')

    def on_close(self, close_status_code, close_msg) -> None:
        self._stream.stop_stream()
        self._stream.close()
        self._player.terminate()
        print(f'[TTS] Connection closed code={close_status_code}, msg={close_msg}')

    def on_event(self, response: dict) -> None:
        try:
            event_type = response.get('type', '')
            if event_type == 'session.created':
                print(f'[TTS] Session started: {response["session"]["id"]}')
            elif event_type == 'response.audio.delta':
                audio_data = base64.b64decode(response['delta'])
                self._stream.write(audio_data)
            elif event_type == 'response.done':
                print(f'[TTS] Response complete, Response ID: {qwen_tts_realtime.get_last_response_id()}')
            elif event_type == 'session.finished':
                print('[TTS] Session finished')
                self.complete_event.set()
        except Exception as e:
            print(f'[Error] Exception occurred while processing callback event: {e}')

    def wait_for_finished(self):
        self.complete_event.wait()

# ======= Main execution logic =======
if __name__ == '__main__':
    init_dashscope_api_key()
    print('[System] Initializing Qwen TTS Realtime ...')

    callback = MyCallback()
    qwen_tts_realtime = QwenTtsRealtime(
        model=DEFAULT_TARGET_MODEL,
        callback=callback,
        # The following is the URL for the Singapore region. If you use a model in the Beijing region, replace the URL with: wss://dashscope.aliyuncs.com/api-ws/v1/realtime
        url='wss://dashscope-intl.aliyuncs.com/api-ws/v1/realtime'
    )
    qwen_tts_realtime.connect()
    
    qwen_tts_realtime.update_session(
        voice=create_voice(VOICE_FILE_PATH), # Replace the voice parameter with the custom voice generated by cloning.
        response_format=AudioFormat.PCM_24000HZ_MONO_16BIT,
        mode='server_commit'
    )

    for text_chunk in TEXT_TO_SYNTHESIZE:
        print(f'[Send text]: {text_chunk}')
        qwen_tts_realtime.append_text(text_chunk)
        time.sleep(0.1)

    qwen_tts_realtime.finish()
    callback.wait_for_finished()

    print(f'[Metric] session_id={qwen_tts_realtime.get_session_id()}, '
          f'first_audio_delay={qwen_tts_realtime.get_first_audio_delay()}s')

Citation#

If you find our model useful in your research, please consider citing us 📝 :)

@misc{qwen3_tts_202512,
  author       = {Qwen Team, Alibaba},
  title        = {Qwen3-TTS Steps Up: Voice Cloning and Voice Design!},
  year         = {2025},
  url          = {https://qwen.ai/blog?id=qwen3-tts-vc-voicedesign},
  urldate      = {2025-12-23}
}