Skip to main content

非实时语音合成（Qwen-TTS）API参考

非实时语音合成（Qwen-TTS）API 的请求参数与返回字段说明。

请求体

  • 非流式输出
  • 流式输出
  • Python
  • Java
  • curl
DashScope Python SDK中的SpeechSynthesizer接口已统一为MultiModalConversation，使用方法和参数保持完全一致。 
# 请安装 DashScope SDK 的最新版本
import os
import dashscope

# 以下为华北2（北京）地域的配置。
dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'

text = "那我来给大家推荐一款T恤，这款呢真的是超级好看，这个颜色呢很显气质，而且呢也是搭配的绝佳单品，大家可以闭眼入，真的是非常好看，对身材的包容性也很好，不管啥身材的宝宝呢，穿上去都是很好看的。推荐宝宝们下单哦。"
# SpeechSynthesizer接口使用方法：dashscope.audio.qwen_tts.SpeechSynthesizer.call(...)
response = dashscope.MultiModalConversation.call(
    model="qwen3-tts-flash",
    # 新加坡和北京地域的API Key不同。获取API Key：https://help.aliyun.com/zh/model-studio/get-api-key
    # 若没有配置环境变量，请用阿里云百炼API Key将下行替换为：api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    text=text,
    voice="Cherry"
)
print(response)
modelstring（必选）模型名称，详情请参见支持的模型。
inputobject（必选）输入参数。

属性

text string （必选）要合成的文本，支持多语种混合输入。最大输入长度为 600 字符。voice string （必选）使用的音色，参见支持的系统音色。language_type string （可选）合成音频的语种。默认为 Auto。
  • Auto：适用于文本包含多种语言或语种不确定的场景。模型自动为不同语言片段匹配发音，但无法保证完全精准。
  • 指定语种：适用于单一语种文本。指定具体语种能显著提升合成质量，效果通常优于 Auto。可选值：
    • Chinese
    • English
    • German
    • Italian
    • Portuguese
    • Spanish
    • Japanese
    • Korean
    • French
    • Russian

返回对象（流式与非流式输出格式一致） 

{
    "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 integerHTTP状态码。遵循 RFC 9110标准定义。例如：
• 200：请求成功，正常返回结果
• 400：客户端请求参数错误
• 401：未授权访问
• 404：资源未找到
• 500：服务器内部错误。
request_id string本次请求的唯一标识，可用于问题排查。
code string请求失败时展示错误码（参见错误码）。
message string请求失败时展示错误信息（参见错误码）。
outputobject模型的输出。

属性

textstring始终为null，无需关注该参数。choicesstring始终为null，无需关注该参数。finish_reasonstring生成状态标识：
  • 正在生成时为"null"；
  • 模型输出自然结束或触发了停止条件时为 "stop"。
audio object模型输出的音频信息。

属性

url string完整音频文件的 URL，有效期 24 小时。
流式输出说明：流式模式下，API 返回多个 chunk。中间 chunk 的 audio.data 包含 Base64 编码的音频片段，audio.url 为空；最后一个 chunk 的 audio.data 为空字符串，audio.url 包含完整音频文件的 OSS 地址。开发者可在最后一个 chunk 中通过 url 字段下载完整音频。非流式模式下，该字段直接返回完整音频文件 URL。
data stringBase64 编码的音频数据。非流式输出和流式输出的中间 chunk 中返回 Base64 编码的音频片段；流式输出的最后一个 chunk 中该字段为空字符串，音频通过同级的 url 字段获取。id string音频的唯一标识。expires_at integerURL 过期时间的 UNIX 时间戳。
usage object本次请求的字符消耗信息。

属性

output_tokens integer输出音频的 Token 消耗量。对于千问3-TTS-Flash模型，该字段固定为0。input_tokens integer输入文本的 Token 消耗量。对于千问3-TTS-Flash模型，该字段固定为0。characters integer输入文本的字符数。仅千问3-TTS-Flash模型返回该字段。
request_id string本次请求的 ID。

音频下载与播放

运行示例前，请先获取并配置 API Key，并安装 DashScope SDK。Python 播放示例还依赖 PyAudio 和 NumPy；PyAudio 的安装方式见代码注释，NumPy 可通过 pip install numpy 安装。

下载音频（Java）

需要导入 Gson 依赖，Maven 或 Gradle 添加方式如下：
  • Maven
  • Gradle
在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()
                // 新加坡和北京地域的API Key不同。获取API Key：https://help.aliyun.com/zh/model-studio/get-api-key
                // 若没有配置环境变量，请用阿里云百炼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") // 建议与文本语种一致，以获得正确的发音和自然的语调。
                .build();
        MultiModalConversationResult result = conv.call(param);
        String audioUrl = result.getOutput().getAudio().getUrl();
        System.out.print(audioUrl);

        // 下载音频文件到本地
        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("\n音频文件已下载到本地：downloaded_audio.wav");
        } catch (Exception e) {
            System.out.println("\n下载音频文件时出错：" + e.getMessage());
        }
    }
    public static void main(String[] args) {
        try {
            // 以下为华北2（北京）地域的配置。
            Constants.baseHttpApiUrl = "https://dashscope.aliyuncs.com/api/v1";
            call();
        } catch (ApiException | NoApiKeyException | UploadFileException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}

流式播放

  • 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

# 以下为华北2（北京）地域的配置。
dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'

p = pyaudio.PyAudio()
# 创建音频流
stream = p.open(format=pyaudio.paInt16,
                channels=1,
                rate=24000,
                output=True)

text = "你好啊，我是千问"
response = dashscope.MultiModalConversation.call(
    # 新加坡和北京地域的API Key不同。获取API Key：https://help.aliyun.com/zh/model-studio/get-api-key
    # 若没有配置环境变量，请用阿里云百炼API Key将下行替换为：api_key = "sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    model="qwen3-tts-flash",
    text=text,
    voice="Cherry",
    language_type="Chinese",  # 建议与文本语种一致，以获得正确的发音和自然的语调。
    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)
          # 直接播放音频数据
          stream.write(audio_np.tobytes())
      if chunk.output.finish_reason == "stop":
          print(f"finish at: {chunk.output.audio.expires_at}")
time.sleep(0.8)
# 清理资源
stream.stop_stream()
stream.close()
p.terminate()
使用 API
文本生成
图像生成
视频生成
世界模型
3D模型生成
音频
    • 声音设计
  • 音频生成
实时多模态
Realtime API
  • 概述
向量与排序
翻译模型
决策模型
更多模型
工具包/框架
TokenPlan
模型生产
文件管理
账单
模型管理
更多