Skip to main content
Qwen3-TTS

Qwen-TTS non-real-time speech synthesis API reference

Request parameters and response fields for the non-realtime speech synthesis (Qwen-TTS) API.

Request body

  • Non-streaming output
  • Streaming output
  • Python
  • Java
  • curl
In DashScope Python SDK 2.0, non-realtime speech synthesis is called through the client.audio.tts.http resource.
# Install the latest version of the DashScope SDK
import os
import dashscope

client = dashscope.Client(
    # If the environment variable is not configured, replace the following line with your QwenCloud API key: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 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
    base_url="https://ap-southeast-1.maas.qwencloudapi.com/api/v1",
)

text = "Let me recommend a T-shirt to everyone. This one is really super nice. The color is very elegant, and it's also a perfect item to match. Everyone can buy it without hesitation. It's truly beautiful and very forgiving on the figure. No matter what body type you have, it will look great. I recommend everyone to place an order."
result = client.audio.tts.http.synthesize(
    text,
    model="qwen3-tts-flash",
    voice="Cherry"
)
print(result.audio_url, result.audio_id, result.expires_at)

Shell quoting corrections

These examples preserve all request values and use a quoted heredoc so apostrophes in the JSON text are passed literally.

Corrected streaming request

# ======= IMPORTANT NOTE =======
# If the environment variable is not configured, replace $DASHSCOPE_API_KEY with your QwenCloud API key: sk-xxx.
# === DELETE THIS COMMENT WHEN EXECUTING ===

# 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
curl -X POST 'https://ap-southeast-1.maas.qwencloudapi.com/api/v1/services/aigc/multimodal-generation/generation' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-H 'X-DashScope-SSE: enable' \
-d @- <<'JSON'
{
    "model": "qwen3-tts-flash",
    "input": {
        "text": "Let me recommend a T-shirt to you. This one is truly stunning. Its color highlights your elegance and makes it an ideal match for any outfit. You can buy it without hesitation - it looks great on everyone. It flatters all body types. Whether you're tall, short, slim, or curvy, this T-shirt suits you perfectly. We highly recommend ordering it.",
        "voice": "Cherry",
        "language_type": "English"
    }
}
JSON
ParameterTypeDescription
modelstring(required) The model name. For details, see Supported models.
inputobject(required) Input parameters.
input.textstring(required) The text to synthesize. Supports multilingual mixed input. The maximum input length is 600 characters.
input.voicestring(required) The voice to use. See Supported system voices.
input.language_typestring(optional) The language of the synthesized audio. Defaults to Auto. Use Auto for multilingual or undetermined input, or specify Chinese, English, German, Italian, Portuguese, Spanish, Japanese, Korean, French, or Russian for better single-language synthesis.

Response object (streaming and non-streaming formats are identical)

{
    "status_code": 200,
    "request_id": "5c63c65c-cad8-4bf4-959d-xxxxxxxxxxxx",
    "code": "",
    "message": "",
    "output": {
        "text": null,
        "finish_reason": "stop",
        "choices": null,
        "audio": {
            "data": "",
            "url": "http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/1d/ab/20251218/d2033070/39b6d8f2-c0db-4daa-9073-5d27bfb66b78.wav?Expires=1766113409&OSSAccessKeyId=YOUR_ACCESS_KEY_ID&Signature=YOUR_SIGNATURE",
            "id": "audio_5c63c65c-cad8-4bf4-959d-xxxxxxxxxxxx",
            "expires_at": 1766113409
        }
    },
    "usage": {
        "input_tokens": 0,
        "output_tokens": 0,
        "characters": 195
    }
}
ParameterTypeDescription
request_idstringA unique identifier for this request. Use it for troubleshooting.
status_codeintegerThe HTTP status code as defined in RFC 9110. Common values:
• 200: Request succeeded.
• 400: Invalid request parameters.
• 401: Unauthorized.
• 404: Resource not found.
• 500: Internal server error.
codestringThe error code returned on failure. See Error codes.
messagestringThe error message returned on failure. See Error codes.
usageobjectCharacter usage for this request.
usage.output_tokensintegerOutput-audio token usage. Always 0 for Qwen3-TTS-Flash.
usage.input_tokensintegerInput-text token usage. Always 0 for Qwen3-TTS-Flash.
usage.charactersintegerNumber of input characters. Returned only by Qwen3-TTS-Flash.
outputobjectThe model output.
output.textstringAlways null. Ignore this field.
output.choicesstringAlways null. Ignore this field.
output.finish_reasonstringThe generation status:
  • null — Generation is in progress.
  • stop — Generation finished normally, or a stop condition was met.
output.audioobjectThe audio output from the model.
output.audio.urlstringThe URL of the complete audio file, valid for 24 hours. In non-streaming mode, returned directly in the response. In streaming mode, only returned in the last chunk of the SSE stream (intermediate chunks do not contain this field).
output.audio.datastringBase64-encoded audio data. In non-streaming mode, this field is always an empty string (use url to get the complete audio file). In streaming mode, intermediate chunks contain Base64-encoded audio segments, while the last chunk returns an empty string (use url to get the complete audio).
output.audio.idstringA unique identifier for the audio.
output.audio.expires_atintegerThe URL expiration time as a Unix timestamp.

Audio download and playback

Before running the examples, obtain and configure an API key and install the DashScope SDK. The Python playback example also requires PyAudio and NumPy. See the code comments for PyAudio installation instructions, and install NumPy with pip install numpy.

Download audio (Java)

You must import the Gson dependency. Add it using Maven or Gradle:
  • Maven
  • Gradle
Add the following to pom.xml:
<!-- https://mvnrepository.com/artifact/com.google.code.gson/gson -->
<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.13.1</version>
</dependency>
import com.alibaba.dashscope.aigc.multimodalconversation.AudioParameters;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;

import java.io.FileOutputStream;
import java.io.InputStream;
import java.net.URL;

public class Main {
    private static final String MODEL = "qwen3-tts-flash";
    public static void call() throws ApiException, NoApiKeyException, UploadFileException {
        MultiModalConversation conv = new MultiModalConversation();
        MultiModalConversationParam param = MultiModalConversationParam.builder()
                // If you have not configured the environment variable, replace the following line with your QwenCloud API Key: .apiKey("sk-xxx")
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .model(MODEL)
                .text("Today is a wonderful day to build something people love!")
                .voice(AudioParameters.Voice.CHERRY)
                .languageType("English") // We recommend matching this with the language of the text for correct pronunciation and natural intonation.
                .build();
        MultiModalConversationResult result = conv.call(param);
        String audioUrl = result.getOutput().getAudio().getUrl();
        System.out.print(audioUrl);

        // Download the audio file to local storage
        try (InputStream in = new URL(audioUrl).openStream();
             FileOutputStream out = new FileOutputStream("downloaded_audio.wav")) {
            byte[] buffer = new byte[1024];
            int bytesRead;
            while ((bytesRead = in.read(buffer)) != -1) {
                out.write(buffer, 0, bytesRead);
            }
            System.out.println("\nAudio file downloaded to: downloaded_audio.wav");
        } catch (Exception e) {
            System.out.println("\nFailed to download audio file: " + e.getMessage());
        }
    }
    public static void main(String[] args) {
        // 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
        Constants.baseHttpApiUrl = "https://ap-southeast-1.maas.qwencloudapi.com/api/v1";
        try {
            call();
        } catch (ApiException | NoApiKeyException | UploadFileException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}

Streaming playback

  • Python
  • Java
# 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 os
import dashscope
import pyaudio
import time

client = dashscope.Client(
    # If you have not configured the environment variable, replace the following line with your QwenCloud API Key: api_key = "sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 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
    base_url="https://ap-southeast-1.maas.qwencloudapi.com/api/v1",
)

p = pyaudio.PyAudio()
# Create an audio stream
stream = p.open(format=pyaudio.paInt16,
                channels=1,
                rate=24000,
                output=True)

text = "Today is a wonderful day to build something people love!"

for chunk in client.audio.tts.http.stream(
    text,
    model="qwen3-tts-flash",
    voice="Cherry",
    language_type="English", # We recommend matching this with the language of the text for correct pronunciation and natural intonation.
):
    if chunk.audio:
        # Play audio data directly (chunk.audio is already decoded audio bytes)
        stream.write(chunk.audio)
    if chunk.is_final:
        print(f"finish at: {chunk.expires_at}")
time.sleep(0.8)
# Clean up resources
stream.stop_stream()
stream.close()
p.terminate()