Skip to main content

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
The SpeechSynthesizer interface in the DashScope Python SDK is now unified under MultiModalConversation. Its usage and parameters remain fully consistent. 
# Install the latest version of the DashScope SDK
import os
import dashscope
# Singapore region
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.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."
# SpeechSynthesizer interface usage: dashscope.audio.qwen_tts.SpeechSynthesizer.call(...)
response = dashscope.MultiModalConversation.call(
    model="qwen3-tts-flash",
    # The API keys for Singapore and Beijing regions are different. Get your API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
    # If the environment variable is not configured, replace the following line with your Model Studio API key: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    text=text,
    voice="Cherry"
)
print(response)
modelstring(required)The model name. For details, see Supported models.
inputobject(required)Input parameters.

Properties

text string (required)The text to synthesize. Supports multilingual mixed input. The maximum input length is 600 characters.voice string (required)The voice to use. See Supported system voices.language_type string (optional)The language of the synthesized audio. Defaults to Auto.
  • Auto: Use when the input contains multiple languages or the language cannot be determined. The model automatically matches pronunciation for each language segment, though accuracy is not guaranteed.
  • Specific language: Use for single-language text. Specifying the language significantly improves synthesis quality and typically produces better results than Auto. Valid values:
    • Chinese
    • English
    • German
    • Italian
    • Portuguese
    • Spanish
    • Japanese
    • Korean
    • French
    • Russian

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
    }
}
status_code integerThe 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.
request_id stringA unique identifier for this request. Use it for troubleshooting.
code stringThe error code returned on failure. See Error codes.
message stringThe error message returned on failure. See Error codes.
outputobjectThe model output.

Properties

textstringAlways null. Ignore this field.choicesstringAlways null. Ignore this field.finish_reasonstringThe generation status:
  • null — Generation is in progress.
  • stop — Generation finished normally, or a stop condition was met.
audio objectThe audio output from the model.

Properties

url stringThe 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).data stringBase64-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).id stringA unique identifier for the audio.expires_at integerThe URL expiration time as a Unix timestamp.
usage objectCharacter usage for this request.

Properties

output_tokens integerThe number of tokens consumed by the output audio. For the Qwen3-TTS-Flash model, this field is always 0.input_tokens integerThe number of tokens consumed by the input text. For the Qwen3-TTS-Flash model, this field is always 0.characters integerThe number of characters in the input text. Returned only by the Qwen3-TTS-Flash model.
request_id stringA unique identifier for this request. Use it for troubleshooting.

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()
                // The API Keys for the Singapore and Beijing regions are different. Get an API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
                // If you have not configured the environment variable, replace the following line with your Model Studio 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) {
        // The following is the configuration for the Singapore region.
        Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.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
import base64
import numpy as np

# The following is the configuration for the Singapore region.
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.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!"
response = dashscope.MultiModalConversation.call(
    # The API Keys for the Singapore and Beijing regions are different. Get an API Key: https://www.alibabacloud.com/help/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"),
    model="qwen3-tts-flash",
    text=text,
    voice="Cherry",
    language_type="English", # We recommend matching this with the language of the text for correct pronunciation and natural intonation.
    stream=True
)

for chunk in response:
    if chunk.output is not None:
      audio = chunk.output.audio
      if audio.data is not None:
          wav_bytes = base64.b64decode(audio.data)
          audio_np = np.frombuffer(wav_bytes, dtype=np.int16)
          # Play audio data directly
          stream.write(audio_np.tobytes())
      if chunk.output.finish_reason == "stop":
          print(f"finish at: {chunk.output.audio.expires_at}")
time.sleep(0.8)
# Clean up resources
stream.stop_stream()
stream.close()
p.terminate()
API Usage
Text Generation
Image Generation
Video Generation
World models
Audio
    • Voice Design
  • Audio generation
Real-time Multimodal
Realtime API
Text Embedding
Decision Model
More Models
Toolkit/Framework
TokenPlan
Model Production
File Management
Billing
Model Management
More