Qwen-TTS speech synthesis API reference-Alibaba Cloud Model Studio(Model Studio)-阿里云帮助中心

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

Request body

Non-streaming output

Python

In DashScope Python SDK 2.0, non-real-time speech synthesis is called via the client.audio.tts.http resource.

# Install the latest version of the DashScope SDK
import os
import dashscope

# The following is the configuration for the China (Beijing) region. Replace "{WorkspaceId}" with your actual workspace ID when calling. The configuration varies by region.
client = dashscope.Client(
    # The API keys for the Singapore and Beijing regions are different. Get an API key: https://help.aliyun.com/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"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

text = "那我来给大家推荐一款T恤，这款呢真的是超级好看，这个颜色呢很显气质，而且呢也是搭配的绝佳单品，大家可以闭眼入，真的是非常好看，对身材的包容性也很好，不管啥身材的宝宝呢，穿上去都是很好看的。推荐宝宝们下单哦。"
result = client.audio.tts.http.synthesize(
    text,
    model="qwen3-tts-flash",
    voice="Cherry"
)
print(result.audio_url, result.audio_id, result.expires_at)

Java

// Install the latest version of the DashScope SDK
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.JsonUtils;
import com.alibaba.dashscope.utils.Constants;

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()
                .model(MODEL)
                // The API keys for the Singapore and Beijing regions are different. Get an API key: https://help.aliyun.com/en/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"))
                .text("Today is a wonderful day to build something people love!")
                .voice(AudioParameters.Voice.CHERRY)
                .parameter("language_type", "English")
                .build();
        MultiModalConversationResult result = conv.call(param);
        System.out.println(JsonUtils.toJson(result));
    }
    public static void main(String[] args) {
        // The following is the configuration for the China (Beijing) region.
        Constants.baseHttpApiUrl = "https://dashscope.aliyuncs.com/api/v1";
        try {
            call();
        } catch (ApiException | NoApiKeyException | UploadFileException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}

curl

# ======= IMPORTANT NOTE =======
# The following is the configuration for the China (Beijing) region.
# The API keys for the Singapore and Beijing regions are different. Get an API key: https://help.aliyun.com/en/model-studio/get-api-key
# If you have not configured the environment variable, replace $DASHSCOPE_API_KEY with your Model Studio API key: sk-xxx.
# === DELETE THIS COMMENT WHEN EXECUTING ===

curl -X POST 'https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
    "model": "qwen3-tts-flash",
    "input": {
        "text": "那我来给大家推荐一款T恤，这款呢真的是超级好看，这个颜色呢很显气质，而且呢也是搭配的绝佳单品，大家可以闭眼入，真的是非常好看，对身材的包容性也很好，不管啥身材的宝宝呢，穿上去都是很好看的。推荐宝宝们下单哦。",
        "voice": "Cherry",
        "language_type": "Chinese"
    }
}'

Streaming output

Python

In DashScope Python SDK 2.0, non-real-time speech synthesis is called via the client.audio.tts.http resource.

# DashScope SDK version 2.0.1 or later required
import os
import dashscope

# The following is the configuration for the China (Beijing) region. Replace "{WorkspaceId}" with your actual workspace ID when calling. The configuration varies by region.
client = dashscope.Client(
    # The API keys for the Singapore and Beijing regions are different. Get an API key: https://help.aliyun.com/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"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

text = "那我来给大家推荐一款T恤，这款呢真的是超级好看，这个颜色呢很显气质，而且呢也是搭配的绝佳单品，大家可以闭眼入，真的是非常好看，对身材的包容性也很好，不管啥身材的宝宝呢，穿上去都是很好看的。推荐宝宝们下单哦。"
for chunk in client.audio.tts.http.stream(
    text,
    model="qwen3-tts-flash",
    voice="Cherry",
):
    # chunk.audio is the decoded audio bytes (bytes). When chunk.is_final is True, it carries the URL of the complete audio.
    print(chunk)

Java

// DashScope SDK version 2.19.0 or later required
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.JsonUtils;
import com.alibaba.dashscope.utils.Constants;
import io.reactivex.Flowable;

public class Main {
    private static final String MODEL = "qwen3-tts-flash";
    public static void streamCall() throws ApiException, NoApiKeyException, UploadFileException {
        MultiModalConversation conv = new MultiModalConversation();
        MultiModalConversationParam param = MultiModalConversationParam.builder()
                .model(MODEL)
                // The API keys for the Singapore and Beijing regions are different. Get an API key: https://help.aliyun.com/en/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"))
                .text("Today is a wonderful day to build something people love!")
                .voice(AudioParameters.Voice.CHERRY)
                .parameter("language_type", "English")
                .build();
        Flowable<MultiModalConversationResult> result = conv.streamCall(param);
        result.blockingForEach(r -> {System.out.println(JsonUtils.toJson(r));
        });
    }
    public static void main(String[] args) {
        // The following is the configuration for the China (Beijing) region.
        Constants.baseHttpApiUrl = "https://dashscope.aliyuncs.com/api/v1";
        try {
            streamCall();
        } catch (ApiException | NoApiKeyException | UploadFileException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}

curl

# ======= IMPORTANT NOTE =======
# The following is the configuration for the China (Beijing) region.
# The API keys for the Singapore and Beijing regions are different. Get an API key: https://help.aliyun.com/en/model-studio/get-api-key
# If you have not configured the environment variable, replace $DASHSCOPE_API_KEY with your Model Studio API key: sk-xxx.
# === DELETE THIS COMMENT WHEN EXECUTING ===

curl -X POST 'https://dashscope.aliyuncs.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 '{
    "model": "qwen3-tts-flash",
    "input": {
        "text": "那我来给大家推荐一款T恤，这款呢真的是超级好看，这个颜色呢很显气质，而且呢也是搭配的绝佳单品，大家可以闭眼入，真的是非常好看，对身材的包容性也很好，不管啥身材的宝宝呢，穿上去都是很好看的。推荐宝宝们下单哦。",
        "voice": "Cherry",
        "language_type": "Chinese"
    }
}'

For the method of playing Base64 audio in real time, see Streaming playback.

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)

Qwen3-TTS-Flash

{
    "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 integer

The 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 string

A unique identifier for this request. Use it for troubleshooting.

code string

The error code returned on failure. See Error codes.

message string

The error message returned on failure. See Error codes.

outputobject

The model output.

Properties

textstring

Always null. Ignore this field.

choicesstring

Always null. Ignore this field.

finish_reasonstring

The generation status:

null — Generation is in progress.
stop — Generation finished normally, or a stop condition was met.

audio object

The audio output from the model.

Properties

url string

The URL of the complete audio file, valid for 24 hours.

NoteStreaming output notes: In streaming mode, the API returns multiple chunks. The audio.data of intermediate chunks contains Base64-encoded audio segments, and audio.url is empty; in the last chunk, audio.data is an empty string and audio.url contains the OSS address of the complete audio file. You can download the complete audio via the url field in the last chunk. In non-streaming mode, this field directly returns the URL of the complete audio file.

data string

Base64-encoded audio data. Base64-encoded audio segments are returned in non-streaming output and in intermediate chunks of streaming output; in the last chunk of streaming output, this field is an empty string, and the audio is obtained through the sibling url field.

id string

A unique identifier for the audio.

expires_at integer

The URL expiration time as a Unix timestamp.

usage object

Character usage for this request.

Properties

output_tokens integer

The number of tokens consumed by the output audio. For the Qwen3-TTS-Flash model, this field is always 0.

input_tokens integer

The number of tokens consumed by the input text. For the Qwen3-TTS-Flash model, this field is always 0.

characters integer

The number of characters in the input text. Returned only by the Qwen3-TTS-Flash model.

request_id string

The ID of this request.

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

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>

Gradle

Add the following to build.gradle:

// https://mvnrepository.com/artifact/com.google.code.gson/gson
implementation("com.google.code.gson:gson:2.13.1")

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://help.aliyun.com/en/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)
                .parameter("language_type", "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) {
        try {
            // The following is the configuration for the China (Beijing) region.
            Constants.baseHttpApiUrl = "https://dashscope.aliyuncs.com/api/v1";
            call();
        } catch (ApiException | NoApiKeyException | UploadFileException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}

Streaming playback

Python

# 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

# The following is the configuration for the China (Beijing) region. Replace "{WorkspaceId}" with your actual workspace ID when calling. The configuration varies by region.
client = dashscope.Client(
    # The API keys for the Singapore and Beijing regions are different. Get an API key: https://help.aliyun.com/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"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

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

text = "你好啊，我是千问"

for chunk in client.audio.tts.http.stream(
    text,
    model="qwen3-tts-flash",
    voice="Cherry",
    language_type="Chinese",  # We recommend matching this with the language of the text for correct pronunciation and natural intonation.
):
    if chunk.audio:
        # Play the 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()

Java

You must import the Gson dependency. Add it using Maven or Gradle:

Maven

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>

Gradle

Add the following to build.gradle:

// https://mvnrepository.com/artifact/com.google.code.gson/gson
implementation("com.google.code.gson:gson:2.13.1")

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 io.reactivex.Flowable;
import javax.sound.sampled.*;
import java.util.Base64;

public class Main {
    private static final String MODEL = "qwen3-tts-flash";
    public static void streamCall() 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://help.aliyun.com/en/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)
                .parameter("language_type", "English") // We recommend matching this with the language of the text for correct pronunciation and natural intonation.
                .build();
        Flowable<MultiModalConversationResult> result = conv.streamCall(param);
        result.blockingForEach(r -> {
            try {
                // 1. Get the Base64-encoded audio data
                String base64Data = r.getOutput().getAudio().getData();
                byte[] audioBytes = Base64.getDecoder().decode(base64Data);

                // 2. Configure the audio format (adjust according to the audio format returned by the API)
                AudioFormat format = new AudioFormat(
                        AudioFormat.Encoding.PCM_SIGNED,
                        24000, // Sample rate (must match the format returned by the API)
                        16,    // Bit depth
                        1,     // Number of channels
                        2,     // Frame size (in bytes)
                        24000, // Frame rate (must match the sample rate)
                        false  // Big-endian
                );

                // 3. Play audio data in real time
                DataLine.Info info = new DataLine.Info(SourceDataLine.class, format);
                try (SourceDataLine line = (SourceDataLine) AudioSystem.getLine(info)) {
                    if (line != null) {
                        line.open(format);
                        line.start();
                        line.write(audioBytes, 0, audioBytes.length);
                        line.drain();
                    }
                }
            } catch (LineUnavailableException e) {
                e.printStackTrace();
            }
        });
    }
    public static void main(String[] args) {
        // The following is the configuration for the China (Beijing) region.
        Constants.baseHttpApiUrl = "https://dashscope.aliyuncs.com/api/v1";
        try {
            streamCall();
        } catch (ApiException | NoApiKeyException | UploadFileException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}