Skip to main content
Text-to-speech

Non-real-time speech synthesis

Convert complete text to speech over HTTP. Explore model features, make your first request, and improve synthesis quality.

Features

Non-real-time speech synthesis accepts complete text in one HTTP request and supports non-streaming and SSE streaming output. Non-streaming output returns the complete audio after synthesis finishes. Streaming output returns audio in chunks.
  • Languages and dialects: Select a model and voice for the target language, or use an instruction to specify a dialect. See Dialects.
  • Expressive speech: Adjust delivery with natural-language instructions, or insert emotion and nonverbal tags into the text. See Instruction control and Emotion and nonverbal tags.
  • Custom voices: Create a voice from an audio sample with voice cloning, or from a text description with voice design.
  • Fine-grained control and formulas: Use SSML and LaTeX to control pauses and pronunciation, or convert formulas to speech.
  • Supported features vary by model and voice. Check the scope in the corresponding feature documentation.
  • To submit text incrementally, use real-time speech synthesis.

Get started

  • Obtain an API key and set the environment variable DASHSCOPE_API_KEY. Use a key for the region in the example.
  • The Qwen-Audio-TTS examples use the Singapore endpoint. For another region, replace ap-southeast-1 in the URL. The CosyVoice examples use China North 2 (Beijing), the only region where CosyVoice is available through this API. See Regions.
  • Install the example dependency:
pip install requests
  • CosyVoice

Improve synthesis quality

Languages and pronunciation

If numbers, abbreviations, or symbols are pronounced incorrectly, use language_hints to specify the target synthesis language, or use hot_fix to customize pronunciation and text replacement. For supported models and configuration, see the Qwen-Audio-TTS API or CosyVoice API. Use SSML to control pauses, the reading of numbers, or word pronunciation. For supported Qwen-Audio-TTS and CosyVoice models, voices, interfaces, and tags, see SSML and LaTeX.

Instruction control

Add instruction to the request’s input object to specify the synthesis language and describe the speech rate, emotion, or speaking style in natural language.
To create a new voice with a specific gender, age, or vocal character, or for guidance and examples on writing voice descriptions, see voice design.
  • Qwen-Audio-TTS
  • CosyVoice
System, cloned, and designed voices for qwen-audio-3.1-tts-plus, qwen-audio-3.1-tts-flash, qwen-audio-3.0-tts-plus, and qwen-audio-3.0-tts-flash all support natural-language instructions through instruction in synthesis requests.We recommend specifying the synthesis language and desired effect in instruction to improve synthesis quality. The language specified in the instruction must match the language of the text to be synthesized. For example, when synthesizing Dutch text, set:
{"instruction": "请用荷兰话说,每个字都慢慢说"}

Dialects

Use dialect synthesis to generate speech in Chinese dialects such as Henan or Sichuan dialect. How you select a dialect depends on the model and voice type.
  • Qwen-Audio-TTS
  • CosyVoice
  • System voices: Select a voice from the Qwen-Audio-TTS voice list that supports the dialect. A voice that directly supports the dialect requires no additional setting. For voices that support dialect instructions, use instruction.
  • Cloned voices: Specify a dialect with instruction, such as 请用河南话表达。.
  • Designed voices: Dialects are not supported.
For voices that support dialect instructions, set instruction="请讲上海话。" in the request's input object to synthesize Chinese text in Shanghainese.
Qwen3-TTS uses system voices that support the target dialect. See the Qwen3-TTS voice list.

Emotion and nonverbal tags

Applies to qwen-audio-3.1-tts-plus, qwen-audio-3.1-tts-flash, qwen-audio-3.0-tts-plus, and qwen-audio-3.0-tts-flash.
Emotion and paralinguistic tags control the emotion and style of speech and insert sounds such as laughter or sighs at specific positions. Write the tags directly in the text to synthesize, text, without additional parameters.

Usage examples

This text starts with an excited delivery, inserts laughter, and then continues speaking:
[excited]今天的天气真不错![laughing]我们一起出去玩吧!
This text switches to an excited delivery in the second sentence:
[serious]请注意安全事项。[excited]好了,现在让我们开始吧!

Supported tags

  • Control tags
  • Nonverbal tags
A control tag sets the emotion or style of the following text until the next control tag. When long sentences are automatically segmented, the effect is bounded by the resulting text segment.
TagDescription
[sad]Sad
[amazed]Amazed
[deep and loud shouting]Deep, loud shouting
[trembling]Trembling
[angry]Angry
[excited]Excited
[sarcastic]Sarcastic
[curious]Curious
[like dracula]Dracula-like delivery
[bored]Bored
[tired]Tired
[scornful]Scornful
[shouting]Shouting
[asmr]Soft ASMR delivery
[panicked]Panicked
[mischievously]Mischievous
[empathetic]Empathetic
[whispers]Whispering
[reluctantly]Reluctant
[crying]Crying
[serious]Serious
[very slowly]Very slow
[very fast]Very fast

Apply in production

For audio downloads and storage, format and player compatibility, concurrency management, and troubleshooting, see Speech synthesis best practices. Keep request frequency and concurrency within the model's rate limits.

Supported models

  • Singapore
  • China North 2 (Beijing)
  • Qwen-Audio-TTS: qwen-audio-3.1-tts-plus, qwen-audio-3.1-tts-flash, qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash
  • Qwen3-TTS: qwen3-tts-flash
For system voices and audio samples, see the Qwen-Audio-TTS, CosyVoice, and Qwen3-TTS voice lists. A cloned or designed voice must be used with the target model specified when the voice was created.

API reference

Non-real-time speech synthesis - QwenCloud