跳转到主要内容
Qwen-Audio-TTS

Qwen-Audio-TTS Python SDK

本文介绍通过DashScope Python SDK进行Qwen-Audio-TTS实时语音合成的类定义、请求参数和示例代码。

接口地址

SDK 的接口地址需在初始化前设置为下方地址。 wss://maas.qianwenaiapi.com/api-ws/v1/inference

SpeechSynthesizer

包路径:dashscope.audio.tts_v2.SpeechSynthesizer

构造方法

SpeechSynthesizer(
    model: str,
    voice: str,
    format: AudioFormat = AudioFormat.MP3_22050HZ_MONO_256KBPS,
    volume: int = 50,
    speech_rate: float = 1.0,
    pitch_rate: float = 1.0,
    callback: ResultCallback = None)

call() - 非流式调用

方法签名:
def call(self, text: str) -> bytes
参数说明:
参数类型必填说明
textstr是待合成的完整文本,长度不得超过20000字符。
返回值:bytes,完整音频数据。 说明:非流式调用,阻塞等待并一次性返回完整音频数据。适用于短文本、对实时性无严格要求的场景。每次调用前需重新初始化SpeechSynthesizer实例。

streaming_call() - 流式调用

方法签名:
def streaming_call(self, text: str) -> None
参数说明:
参数类型必填说明
textstr是当前待合成的文本片段。可多次调用以追加文本,单次不超过20000字符,累计不超过20万字符。
说明:双向流式调用,支持分片提交文本并通过回调实时获取合成音频。适用于与大语言模型对接、边生成文本边合成语音的场景。发送完毕后需调用streaming_complete()结束合成。

streaming_complete() - 结束流式合成

方法签名:
def streaming_complete(self) -> None
说明:通知服务端所有文本已发送完毕,阻塞当前线程直到剩余文本合成完成并返回所有音频数据。未调用此方法可能导致尾部文本无法转换为语音。

streaming_cancel() - 取消流式合成

方法签名:
def streaming_cancel(self, complete_timeout_millis: int = 10000) -> None
参数说明:
参数类型必填说明
complete_timeout_millisint否等待服务端返回 task-finished 事件的超时时间,单位毫秒。默认值:10000。
说明:取消当前轮次的流式语音合成任务。调用后,SDK 会立即结束当前任务。取消后可在当前连接上继续发起新的合成任务,无需重新初始化 SpeechSynthesizer 实例。
版本要求:使用该功能需要 Python SDK 版本不低于 1.26.4。

get_last_request_id() - 获取请求ID

方法签名:
def get_last_request_id(self) -> str
返回值:str,最近一次请求的request_id,可用于问题排查和日志关联。

get_first_package_delay() - 获取首包延迟

方法签名:
def get_first_package_delay(self) -> float
返回值:float,从发送文本到收到第一块音频数据的延迟时间(毫秒)。需在合成完成后调用。

get_response() - 获取响应消息

方法签名:
def get_response(self) -> dict
返回值:dict,最近一次合成任务的响应消息(含 header/payload 键)。

构造参数

以下参数通过SpeechSynthesizer构造方法设置,用于控制合成音频的模型、音色、格式和音频特征。
参数类型是否必须说明
modelstr是模型名称。
voicestr是语音合成所使用的音色。
  • 系统音色:参见Qwen-Audio-TTS音色列表
  • 复刻音色:通过声音复刻功能定制
  • 声音设计音色:通过声音设计功能定制
formatenum否音频编码格式及采样率。 默认值:AudioFormat.MP3_22050HZ_MONO_256KBPS。 AudioFormat枚举类的包路径:dashscope.audio.tts_v2,支持MP3、WAV、PCM等格式。
volumeint否音量。 默认值:50。 取值范围:[0, 100]。
speech_ratefloat否语速。 默认值:1.0。 取值范围:[0.5, 2.0]。
pitch_ratefloat否音调。 默认值:1.0。 取值范围:[0.5, 2.0]。
bit_rateint否音频码率(kbps)。音频格式为mp3或opus时,支持通过bit_rate参数调整码率。 默认值:32。 取值范围:[6, 510]。 bit_rate需要通过additional_params参数进行设置: 示例 1 请参见表格下方
word_timestamp_enabledbool否是否开启字级别时间戳。 默认值:false。 仅在流式输出模式下可用。支持复刻音色;支持的系统音色请参见Qwen-Audio-TTS音色列表。 word_timestamp_enabled需要通过additional_params参数进行设置: 示例 2 请参见表格下方
seedint否生成时使用的随机数种子,使合成的效果产生变化。在模型版本、文本、音色及其他参数均相同的前提下,使用相同的seed可复现相同的合成结果。 默认值0。 取值范围:[0, 65535]。
language_hintslist[str]否提示: - 此参数为数组,但当前版本仅处理第一个元素,因此建议只传入一个值。
  • 此参数用于指定语音合成的目标语言,该设置与声音复刻时的样本音频的语种无关。如需设置复刻任务的源语言,请参见声音复刻API参考。
指定语音合成的目标语言,提升合成效果。 当数字、缩写、符号等朗读方式或者小语种合成效果不符合预期时使用,例如:
  • 数字朗读方式不符合预期,“hello, this is 110”读成“hello, this is one one zero”而非“hello, this is 幺幺零”
  • 符号朗读不准确,“@”读成“艾特”而非“at”
  • 小语种合成效果差,合成不自然
  • zh:中文
  • en:英语
  • fr:法语
  • de:德语
  • ja:日语
  • ko:韩语
  • ru:俄语
  • pt:葡萄牙语
  • th:泰语
  • id:印尼语
  • vi:越南语
  • es:西班牙语
  • it:意大利语
  • ms:马来西亚语
  • fil:菲律宾语
  • ar:阿拉伯语
instructionstr否设置指令,用于控制方言、情感或角色等合成效果。 使用说明请参见指令控制。
enable_aigc_tagbool否是否在生成的音频中添加AIGC隐性标识。设置为true时,会将隐性标识嵌入到支持格式(wav/mp3/opus)的音频中。 默认值:false。 enable_aigc_tag、aigc_propagator和aigc_propagate_id需要通过additional_params参数进行设置: 示例 3 请参见表格下方
aigc_propagatorstr否设置AIGC隐性标识中的 ContentPropagator 字段,用于标识内容的传播者。仅在 enable_aigc_tag 为 true 时生效。 默认值:千问AI平台账号。 需要通过additional_params参数进行设置,参见enable_aigc_tag的示例。
aigc_propagate_idstr否设置AIGC隐性标识中的 PropagateID 字段,用于唯一标识一次具体的传播行为。仅在 enable_aigc_tag 为 true 时生效。 默认值:本次语音合成请求Request ID。 需要通过additional_params参数进行设置,参见enable_aigc_tag的示例。
hot_fixdict否文本热修复配置,用于自定义指定词语的发音或对待合成文本进行替换。 参数介绍:
  • pronunciation:自定义发音。指定词语的拼音标注,用于纠正默认发音不准确的情况。
  • replace:文本替换。在语音合成前将指定词语替换为目标文本,替换后的文本将作为实际合成内容。
示例: 示例 4 请参见表格下方
callbackResultCallback否回调函数实例,用于异步接收合成音频和事件通知。设置此参数时,call()方法以流式模式运行,音频数据通过on_data回调返回;不设置时,call()以非流式模式运行,直接返回完整音频的bytes数据。
示例 1(说明):
synthesizer = SpeechSynthesizer(
    model="qwen-audio-3.0-tts-flash",
    voice="longanhuan_v3.6",
    additional_params={"bit_rate": 128}
)
示例 2(说明):
synthesizer = SpeechSynthesizer(
    model="qwen-audio-3.0-tts-flash",
    voice="your_voice",  # 支持字级别时间戳的系统音色或复刻音色
    additional_params={"word_timestamp_enabled": True}
)
示例 3(说明):
synthesizer = SpeechSynthesizer(
    model="qwen-audio-3.0-tts-flash",
    voice="longanhuan_v3.6",
    additional_params={
        "enable_aigc_tag": True,
        "aigc_propagator": "your_propagator",
        "aigc_propagate_id": "your_propagate_id"
    }
)
示例 4(说明):
synthesizer = SpeechSynthesizer(
    model="qwen-audio-3.0-tts-flash",
    voice="longanhuan_v3.6", # 音色
    hot_fix={
        "pronunciation": [{"天气": "tian1 qi4"}],
        "replace": [{"今天": "金天"}]
    }
)

ResultCallback

包路径:dashscope.audio.tts_v2.ResultCallback

on_open() - 连接建立

方法签名:
def on_open(self) -> None
触发时机:WebSocket连接成功建立时触发。可在此回调中初始化音频输出流或打开文件等资源。

on_event() - 接收服务端回复

方法签名:
def on_event(self, message: str) -> None
参数说明:
参数类型必填说明
messagestr是服务端响应事件(JSON格式),包含header(请求信息)和payload(输出信息)。其中payload.output包含事件类型、原始文本等信息,详见on_event消息中的output字段。
触发时机:接收到服务端回复时触发。消息为JSON字符串,包含合成事件的输出信息(事件类型、原始文本、句子信息等)。可通过json.loads(message)解析后访问payload.output获取详细信息。

on_complete() - 合成完成

方法签名:
def on_complete(self) -> None
触发时机:所有文本合成完成且音频数据已全部通过on_data返回后触发。可在此回调中调用get_first_package_delay()获取性能指标。

on_data() - 接收音频数据

方法签名:
def on_data(self, data: bytes) -> None
参数说明:
参数类型必填说明
databytes是当前批次的音频二进制数据片段,格式由构造参数format指定。
触发时机:每接收到一块音频数据时触发,合成过程中会被多次调用。可在此回调中将数据写入文件或送入播放设备。

on_error() - 发生错误

方法签名:
def on_error(self, message: str) -> None
参数说明:
参数类型必填说明
messagestr是错误描述信息,包含错误码和详细原因。
触发时机:合成过程中发生错误时触发。触发后连接将自动关闭,建议在此回调中记录错误日志以便排查问题。

on_close() - 连接关闭

方法签名:
def on_close(self) -> None
触发时机:WebSocket连接关闭时触发(无论正常结束还是异常断开)。可在此回调中释放音频播放设备等资源。

on_event消息中的output字段

on_event回调接收的JSON消息中,payload.output包含合成事件的输出信息,可用于跟踪合成进度和获取逐句信息。以下为output字段的结构说明:
字段类型说明
typestr事件类型。取值为sentence-begin(句子合成开始)、sentence-synthesis(句子合成中)或sentence-end(句子合成结束)。
original_textstr当前句子的原始文本。在sentence-begin和sentence-end事件中返回。
sentencedict句子信息。包含index(句子序号)和words(词列表,开启word_timestamp_enabled时返回时间戳信息)。
消息示例:
{
  "header": {
    "task_id": "xxx",
    "event": "result-generated",
    "attributes": {}
  },
  "payload": {
    "output": {
      "type": "sentence-begin",
      "original_text": "今天天气怎么样?",
      "sentence": {
        "index": 0,
        "words": []
      }
    }
  }
}
解析示例:
import json

def on_event(self, message):
    data = json.loads(message)
    output = data.get('payload', {}).get('output', {})
    event_type = output.get('type', '')
    original_text = output.get('original_text', '')
    if event_type:
        print(f'事件类型: {event_type}, 原始文本: {original_text}')

示例代码

SDK提供了语音合成的关键接口,支持以下几种调用方式:
  • 非流式调用:阻塞式,一次性发送完整文本,直接返回完整音频。适合短文本语音合成场景。
  • 单向流式调用:非阻塞式,一次性发送完整文本,通过回调函数接收音频数据(可能分片)。适用于对实时性要求高的短文本语音合成场景。
  • 双向流式调用:非阻塞式,可分多次发送文本片段,通过回调函数实时接收增量合成的音频流。适合实时性要求高的长文本语音合成场景。
更多示例,请参见GitHub。
  • 非流式调用
  • 单向流式调用
  • 双向流式调用
image
单次调用发送的文本长度不得超过20000字符,超出限制将返回错误。
每次调用call方法前,需要重新初始化SpeechSynthesizer实例。
# coding=utf-8

import dashscope
from dashscope.audio.tts_v2 import *
import os

# 若没有配置环境变量,请用千问AI平台API Key将下行替换为:dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

dashscope.base_websocket_api_url='wss://maas.qianwenaiapi.com/api-ws/v1/inference'

# 模型
model = "qwen-audio-3.0-tts-flash"
# 音色
voice = "longanhuan_v3.6"

# 实例化SpeechSynthesizer,并在构造方法中传入模型(model)、音色(voice)等请求参数
synthesizer = SpeechSynthesizer(model=model, voice=voice)
# 发送待合成文本,获取二进制音频
audio = synthesizer.call("今天天气怎么样?")
# 首次发送文本时需建立 WebSocket 连接,因此首包延迟会包含连接建立的耗时
print('[Metric] requestId为:{},首包延迟为:{}毫秒'.format(
    synthesizer.get_last_request_id(),
    synthesizer.get_first_package_delay()))

# 将音频保存至本地
with open('output.mp3', 'wb') as f:
    f.write(audio)
  • dashscope CLI
export DASHSCOPE_API_KEY="your-api-key"
export DASHSCOPE_HTTP_BASE_URL="https://maas.qianwenaiapi.com/api/v1"
dashscope speech-synthesis create -m qwen-audio-3.0-tts-flash -t "你好世界" --voice longanhuan_v3.6