语音合成 - 千问云

POST

/api/v1/services/aigc/multimodal-generation/generation

# 安装最新版本的 DashScope SDK
import os
import dashscope

dashscope.base_http_api_url = 'https://dashscope.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 接口用法：dashscope.audio.qwen_tts.SpeechSynthesizer.call(...)
response = dashscope.MultiModalConversation.call(
  # 如需使用指令控制功能，请将模型替换为 qwen3-tts-instruct-flash
  model="qwen3-tts-flash",
  # 如果未配置环境变量，请将以下行替换为您的 API 密钥：api_key="sk-xxx"
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  text=text,
  voice="Cherry"
  # 如需使用指令控制功能，请取消以下行的注释，并将模型替换为 qwen3-tts-instruct-flash
  # instructions='Fast speech rate, with a clear rising intonation, suitable for introducing fashion products.',
  # optimize_instructions=True
)
print(response)

{
  "status_code": 200,
  "request_id": "5c63c65c-cad8-4bf4-959d-xxxxxxxxxxxx",
  "code": "",
  "message": "",
  "output": {
    "text": null,
    "choices": null,
    "finish_reason": "stop",
    "audio": {
      "url": "https://example.oss.aliyuncs.com/audio-result.wav?Expires=1766113409&OSSAccessKeyId=LTAIxxxx&Signature=xxxx",
      "data": "",
      "id": "audio_5c63c65c-cad8-4bf4-959d-xxxxxxxxxxxx",
      "expires_at": 1766113409
    }
  },
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 1121,
    "characters": 195,
    "input_tokens_details": {
      "text_tokens": 76
    },
    "output_tokens_details": {
      "audio_tokens": 1045,
      "text_tokens": 0
    }
  }
}

DashScope Python SDK 使用 MultiModalConversation 而非 SpeechSynthesizer，用法和参数完全相同。

鉴权

string

header

必填

千问云 API Key。详见获取 API Key。

Header 参数

enum<string>

设置为 enable 可通过 HTTP 实现流式输出。Python SDK 使用 stream 参数代替此设置；Java SDK 使用 streamCall 接口代替此设置。

可选值：enable

请求体

application/json

string

必填

模型名称。

object

必填

语音合成的输入参数。

显示子属性

string

必填

待合成的文本内容，支持多语言混合输入。Qwen-TTS 最大支持 512 tokens 输入，其他模型最大支持 600 个字符。

string

必填

使用的音色。请参阅支持的音色列表。

enum<string>

默认值"Auto"

指定合成音频的语言类型。默认值：Auto。当输入文本为单一语言时，明确指定语言类型可显著提升合成质量。

可选值：Auto,Chinese,English,German,Italian,Portuguese,Spanish,Japanese,Korean,French,Russian

string

提供指令以引导语音合成效果。默认值为 None。长度限制：不超过 1600 tokens。仅支持中文和英文。本功能仅适用于 Qwen3-TTS-Instruct-Flash 系列模型。

boolean

默认值false

对 instructions 进行优化，以提升语音合成的自然度和表现力。默认值：false。设置为 true 时，系统会对 instructions 的内容进行语义增强和改写，生成更适合语音合成的内部指令。如需高质量、细粒度的语音表达，建议开启此功能。本参数依赖于 instructions 的设置，且仅适用于 Qwen3-TTS-Instruct-Flash 系列模型。

boolean

默认值false

是否开启流式输出。默认值：false。设置为 false 时，模型生成完成后返回音频文件的 URL；设置为 true 时，实时输出 Base64 编码的音频数据。

注意：stream 参数仅 Python SDK 支持。Java SDK 请调用 streamCall 接口实现流式输出；HTTP 请在请求头中将 X-DashScope-SSE 设置为 enable。

响应

200-application/json

integer

HTTP 状态码。示例：200（成功）、400（客户端错误）、401（未授权）、404（未找到）、500（服务器错误）。

示例:200

string

本次请求的唯一 ID，可用于定位和排查问题。

示例:5c63c65c-cad8-4bf4-959d-xxxxxxxxxxxx

string

请求失败时显示错误码。请参阅错误码说明。

示例:

string

请求失败时显示错误信息。请参阅错误码说明。

示例:

object

模型的输出结果。

显示子属性

string | null

始终为 null，请忽略此字段。

示例:null

unknown

始终为 null，请忽略此字段。

示例:null

enum<string>

生成过程中为 null；当模型输出自然结束或触发停止条件时，值为 "stop"。

可选值：stop,null

示例:stop

object

模型输出的音频信息。

显示子属性

string

模型输出的完整音频文件 URL，有效期 24 小时。

示例:https://example.oss.aliyuncs.com/audio-result.wav?Expires=1766113409&OSSAccessKeyId=LTAIxxxx&Signature=xxxx

string

流式输出时的 Base64 编码音频数据。

示例:

string

模型输出的音频信息对应的 ID。

示例:audio_5c63c65c-cad8-4bf4-959d-xxxxxxxxxxxx

integer

URL 过期时的 UNIX 时间戳。

示例:1766113409

object

Token 或字符消耗信息。Qwen-TTS 返回 token 消耗量，Qwen3-TTS-Flash 返回字符消耗量。

显示子属性

integer

输入文本消耗的 token 数量。Qwen3-TTS-Flash 返回时该字段始终为 0。

示例:0

integer

输出音频消耗的 token 数量。Qwen3-TTS-Flash 返回时该字段始终为 0。

示例:0

integer

本次请求消耗的 token 总量。仅 Qwen-TTS 返回此字段。

示例:1121

integer

输入文本的字符数量。Qwen3-TTS-Flash 返回实际字符数；Qwen-TTS 返回时该字段始终为 0。

示例:195

object

输入文本的 token 消耗详情。仅 Qwen-TTS 返回此字段。

显示子属性

integer

输入文本消耗的 token 数量。

示例:76

object

输出内容的 token 消耗详情。仅 Qwen-TTS 返回此字段。

显示子属性

integer

输出音频消耗的 token 数量。

示例:1045

integer

输出文本消耗的 token 数量（当前固定为 0）。

示例:0