非实时语音合成Qwen-Audio-TTS Python SDK参考

本文介绍非实时语音合成Qwen-Audio-TTS的Python SDK调用方法，支持非流式和流式两种调用模式。

前提条件

• 已获取与配置 API Key并将其配置到环境变量
• 已安装符合版本要求的DashScope Python SDK，建议安装最新版，SDK版本需≥2.0.1

核心资源（client.audio.tts.http）

资源路径：client.audio.tts.http

功能：基于HTTP的语音合成，synthesize方法为非流式调用（音频以URL返回），stream方法为流式调用（SSE逐片返回音频数据）。

synthesize() / stream() - 语音合成调用

方法签名：

def synthesize(self,
               text: str,
               *,
               model: str,
               voice: str,
               format: str = None,
               sample_rate: int = None,
               language_type: str = None,
               parameters: Dict = None,
               extra_input: Dict = None,
               timeout: float = None,
               ...) -> HttpSynthesis

def stream(self,
           text: str,
           *,
           model: str,
           voice: str,
           format: str = None,
           sample_rate: int = None,
           language_type: str = None,
           parameters: Dict = None,
           extra_input: Dict = None,
           timeout: float = None,
           ...) -> HttpSynthesisStream

参数说明（model、text、voice、format、sample_rate、language_type为具名参数，其余输入参数通过extra_input字典传入）：

"hot_fix": {
  "pronunciation": [
    {"天气": "tian1 qi4"}
  ],
  "replace": [
    {"今天": "金天"}
  ]
}

返回值：

• 非流式模式（synthesize）：返回结果对象（HttpSynthesis），包含以下属性：

  • audio_url：音频下载URL（有效期有限）。
  • audio_id：音频ID。
  • expires_at：URL过期时间。
  • usage：用量信息。

• 流式模式（stream）：返回迭代器（HttpSynthesisStream），每个元素（HttpSynthesisChunk）包含以下属性：

  • audio：当前分片的音频二进制数据（bytes，已解码）。
  • sentence：句子级别的合成信息（如有）。
  • is_final：是否为收尾分片（finish_reason == "stop"）。
  • usage：用量信息（收尾分片携带）。
  重要流式模式下，收尾分片（is_final为True）会额外携带audio_url（完整音频的下载地址）、audio_id与expires_at。遍历迭代器拼接音频时，以chunk.audio是否非空决定是否写入，避免同一段内容重复播放。

示例代码

以下示例展示Qwen-Audio-TTS语音合成的非流式和流式调用方式。运行前请确保已设置环境变量DASHSCOPE_API_KEY。

# -*- coding: utf-8 -*-
import os
import dashscope

# 以下为华北2（北京）地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。
client = dashscope.Client(
    # 若没有将API Key配置到环境变量中，请将下行替换为自己的API Key：api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

# 非流式调用，返回音频URL
result = client.audio.tts.http.synthesize(
    "今天是个好日子，适合构建人们喜爱的产品！",
    model="qwen-audio-3.0-tts-flash",  # 更换模型时，需同步更换为对应版本的音色
    voice="longanhuan_v3.6",
    format="wav",
    sample_rate=24000,
)

# 获取音频URL
print(f"音频 URL: {result.audio_url}")
print(f"音频 ID: {result.audio_id}")
if result.audio_id:
    request_id = result.audio_id.removeprefix("audio_")
    print(f"请求 Id: {request_id}")
print(f"过期时间: {result.expires_at}")

# -*- coding: utf-8 -*-
import os
import dashscope

# 以下为华北2（北京）地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。
client = dashscope.Client(
    # 若没有将API Key配置到环境变量中，请将下行替换为自己的API Key：api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

# 流式调用，逐段返回音频数据
stream_result = client.audio.tts.http.stream(
    "今天是个好日子，适合构建人们喜爱的产品！",
    model="qwen-audio-3.0-tts-flash",  # 更换模型时，需同步更换为对应版本的音色
    voice="longanhuan_v3.6",
    format="wav",
    sample_rate=24000,
)

# 遍历迭代器，逐段接收音频数据
audio_chunks = []
for chunk in stream_result:
    if chunk.audio:  # 只写入非空的音频分片，避免音频重复
        audio_chunks.append(chunk.audio)
        print(f"收到音频数据块，大小: {len(chunk.audio)} bytes")

    if chunk.sentence:
        print(f"句子信息: {chunk.sentence}")

    if chunk.is_final:  # 收尾分片：携带完整音频的下载地址与用量
        print(f"Audio ID: {chunk.audio_id}")
        request_id = chunk.audio_id.removeprefix("audio_")
        print(f"请求 Id: {request_id}")
        print(f"音频 URL: {chunk.audio_url}")
        print(f"用量: {chunk.usage}")

# 合并所有音频数据并保存
full_audio = b"".join(audio_chunks)
print(f"总音频大小: {len(full_audio)} bytes")

with open("output.wav", "wb") as f:
    f.write(full_audio)
print("音频已保存到 output.wav")