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.
- Markdown filtering: Convert Markdown content such as tables into text suitable for reading aloud. See Markdown filtering.
Note
- 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
Get an API key in the console and set the environment variable DASHSCOPE_API_KEY.
Install the example dependency:
pip install requests
Qwen-Audio-TTS (Recommended)
The following examples use qwen-audio-3.1-tts-flash and the longanhuan_v3.1 system voice in Singapore to demonstrate non-streaming and streaming output.
Non-streaming output
import os
import requests
response = requests.post(
'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer',
headers={"Authorization": f"Bearer {os.environ['DASHSCOPE_API_KEY']}"},
json={
"model": "qwen-audio-3.1-tts-flash",
"input": {
"text": "Hello, welcome to Alibaba Cloud Model Studio.",
"voice": "longanhuan_v3.1",
"format": "wav",
"sample_rate": 24000
}
},
timeout=60,
)
response.raise_for_status()
audio_url = response.json()["output"]["audio"]["url"]
audio_response = requests.get(audio_url, timeout=60)
audio_response.raise_for_status()
with open("output.wav", "wb") as f:
f.write(audio_response.content)
The audio is saved as output.wav in the current directory.
Streaming output
This example prints the returned SSE events line by line. The output.audio.data field contains a Base64-encoded audio chunk.
import os
import requests
response = requests.post(
'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer',
headers={"Authorization": f"Bearer {os.environ['DASHSCOPE_API_KEY']}", "X-DashScope-SSE": "enable"},
json={
"model": "qwen-audio-3.1-tts-flash",
"input": {
"text": "Hello, welcome to Alibaba Cloud Model Studio.",
"voice": "longanhuan_v3.1",
"format": "wav",
"sample_rate": 24000
}
},
stream=True,
timeout=60,
)
response.raise_for_status()
for line in response.iter_lines():
print(line.decode("utf-8"))
response.close()
CosyVoice
The following examples use cosyvoice-v3-flash and the longanyang system voice in Beijing to demonstrate non-streaming and streaming output.
Non-streaming output
import os
import requests
response = requests.post(
'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer',
headers={"Authorization": f"Bearer {os.environ['DASHSCOPE_API_KEY']}"},
json={
"model": "cosyvoice-v3-flash",
"input": {
"text": "Hello, welcome to Alibaba Cloud Model Studio.",
"voice": "longanyang",
"format": "wav",
"sample_rate": 24000
}
},
timeout=60,
)
response.raise_for_status()
audio_url = response.json()["output"]["audio"]["url"]
audio_response = requests.get(audio_url, timeout=60)
audio_response.raise_for_status()
with open("output.wav", "wb") as f:
f.write(audio_response.content)
The audio is saved as output.wav in the current directory.
Streaming output
This example prints the returned SSE events line by line. The output.audio.data field contains a Base64-encoded audio chunk.
import os
import requests
response = requests.post(
'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer',
headers={"Authorization": f"Bearer {os.environ['DASHSCOPE_API_KEY']}", "X-DashScope-SSE": "enable"},
json={
"model": "cosyvoice-v3-flash",
"input": {
"text": "Hello, welcome to Alibaba Cloud Model Studio.",
"voice": "longanyang",
"format": "wav",
"sample_rate": 24000
}
},
stream=True,
timeout=60,
)
response.raise_for_status()
for line in response.iter_lines():
print(line.decode("utf-8"))
response.close()
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.
Markdown filtering
When synthesizing content with Markdown tables or links, set enable_markdown_filter to true to convert Markdown into text suitable for reading aloud. Qwen-Audio-TTS and CosyVoice support this feature, except for cosyvoice-v2. For configuration details, see the Qwen-Audio-TTS API and CosyVoice API.
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.
NoteTo 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
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": "Speak in Dutch, slowly and clearly."}
CosyVoice
NoteFor CosyVoice, instruction must not exceed 100 characters. Chinese characters, including simplified and traditional characters and Chinese characters used in Japanese and Korean, count as two characters each. Other characters, including punctuation, letters, digits, kana, and Hangul, count as one each.
| Model | Applicable voices | Instruction requirements | Instruction text languages |
|---|---|---|---|
cosyvoice-v3.5-plus, cosyvoice-v3.5-flash | Cloned and designed voices No system voices. | Natural-language instructions. | Chinese, English, French, German, Japanese, Korean, Russian, Portuguese, Thai, Indonesian, and Vietnamese. |
cosyvoice-v3-plus | System voices | Use the fixed format and content in the voice list. Cloned and designed voices do not support instruction control. | Use the language specified in the voice list. |
cosyvoice-v3-flash | System voices | Use the fixed format and content in the voice list. | Chinese. |
Cloned and designed voices | Natural-language instructions. | Chinese, English, French, German, Japanese, Korean, and Russian. |
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
-
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 the instruction control parameter
instruction.NoteFor the multilingual and dialect voices of qwen-audio-3.1-tts-flash, you can also use
language_hintsto specify a dialect. See the multilingual and dialect voice settings. -
Cloned voices: Specify a dialect with the instruction control parameter
instruction. -
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.
CosyVoice
- System voices: Select a voice that directly supports the dialect, such as
longshange_v3, or a voice that supports dialect instructions, such aslonganhuan_v3. Follow the format in the voice list. - Cloned voices: Use
instructionwith a model that supports instruction control to specify a dialect. - Designed voices: Dialects are not supported.
NoteCloned voices for cosyvoice-v3-plus do not support specifying a dialect through instructions.
In the CosyVoice getting started example, replace input with the following content to generate the Henan dialect with longanhuan_v3:
{
"text": "叫你去买盐,你买回来一袋面,这不是弄啥嘞吗!",
"voice": "longanhuan_v3",
"format": "wav",
"sample_rate": 24000,
"instruction": "请用河南话表达。"
}
Qwen3-TTS uses system voices that support the target dialect. See the Qwen3-TTS voice list.
Emotion and nonverbal tags
NoteApplies 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]What a beautiful day![laughing]Let us go outside and have some fun!
This text switches to an excited delivery in the second sentence:
[serious]Please pay attention to the safety instructions.[excited]Now, let us get started!
Supported tags
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
- 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
China (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
- CosyVoice: cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-plus, cosyvoice-v3-flash, cosyvoice-v2
- 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.