跳转到主要内容
千问AI平台 home page
文档
Qwen-Audio-TTS

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

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

前提条件

HttpSpeechSynthesizer 类

包路径：dashscope.audio.http_tts.http_speech_synthesizer.HttpSpeechSynthesizer 功能：基于HTTP的语音合成，通过stream参数控制非流式或流式调用模式。

call() - 语音合成调用

方法签名： 
@classmethod
def call(cls, model: str, text: str, voice: str,
         format: str = "wav", sample_rate: int = 24000,
         volume: int = 50, rate: float = 1.0, pitch: float = 1.0,
         bit_rate: int = 32, enable_ssml: bool = False,
         word_timestamp_enabled: bool = False,
         seed: int = 0, language_hints: list = None,
         instruction: str = None,
         enable_aigc_tag: bool = False,
         aigc_propagator: str = None,
         aigc_propagate_id: str = None,
         hot_fix: dict = None,
         stream: bool = False,
         api_key: str = None, **kwargs)
参数说明：
参数类型必填说明
modelstr是语音合成模型。
textstr是待合成文本。 支持 SSML 和 LaTeX 格式输入。将待合成文本替换为对应格式即可。
  • 使用 SSML 时，需同时将 enable_ssml 设置为 True。支持的 SSML 标签及用法，请参见SSML 与 LaTeX。
  • 使用 LaTeX 时，将待合成文本替换为 LaTeX 格式即可，无需额外配置。支持的 LaTeX 语法及用法，请参见LaTeX 公式转语音。
voicestr是音色。 取值范围：
formatstr否音频编码格式。 默认值：mp3。 取值范围：
  • mp3
  • pcm
  • wav
  • opus
sample_rateint否音频采样率（Hz）。 取值范围：8000, 16000, 22050（默认）, 24000, 44100, 48000。
volumeint否音量。 默认值：50。 取值范围：[0, 100]。
ratefloat否语速。 默认值：1.0。 取值范围：[0.5, 2.0]。
pitchfloat否音调。 默认值：1.0。 取值范围：[0.5, 2.0]。
bit_rateint否音频码率（单位：kbps）。 默认值：32。 取值范围：[6, 510]。 提示： 仅在format为opus时支持使用该参数。
enable_ssmlbool否是否开启SSML功能。当text使用SSML格式时，需设为True。默认为False。支持的SSML标签及用法，请参考SSML 与 LaTeX。SSML 的使用限制（支持的模型、音色和接口），请参见使用限制。
word_timestamp_enabledbool否是否开启字级别时间戳。 默认值：False。
  • True：开启。
  • False：关闭。
仅在流式输出模式下可用。支持复刻音色；支持的系统音色请参见Qwen-Audio-TTS音色列表。
seedint否生成时使用的随机数种子，使合成的效果产生变化。在模型版本、文本、音色及其他参数均相同的前提下，使用相同的seed可复现相同的合成结果。 默认值0。 取值范围：[0, 65535]。
language_hintslist否提示： - 此参数为数组，但当前版本仅处理第一个元素，因此建议只传入一个值。
  • 此参数用于指定语音合成的目标语言，该设置与声音复刻时的样本音频的语种无关。如需设置复刻任务的源语言，请参见声音复刻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。
aigc_propagatorstr否设置AIGC隐性标识中的 ContentPropagator 字段，用于标识内容的传播者。仅在 enable_aigc_tag 为 True 时生效。 默认值：千问AI平台账号。
aigc_propagate_idstr否设置AIGC隐性标识中的 PropagateID 字段，用于唯一标识一次具体的传播行为。仅在 enable_aigc_tag 为 True 时生效。 默认值：本次语音合成请求Request ID。
hot_fixdict否文本热修复配置，用于自定义指定词语的发音或对待合成文本进行替换。 参数介绍：
  • pronunciation：自定义发音。指定词语的拼音标注，用于纠正默认发音不准确的情况。
  • replace：文本替换。在语音合成前将指定词语替换为目标文本，替换后的文本将作为实际合成内容。
示例： 示例 1 请参见表格下方
streambool否是否启用流式模式。设为False时为非流式调用，返回包含音频URL的结果对象；设为True时为流式调用，返回音频数据分片的迭代器。默认为False。
api_keystr否API Key。如果未指定，SDK会自动从环境变量DASHSCOPE_API_KEY中读取。
示例 1（说明）： 
"hot_fix": {
  "pronunciation": [
    {"天气": "tian1 qi4"}
  ],
  "replace": [
    {"今天": "金天"}
  ]
}
返回值：
  • 非流式模式（stream=False）：返回结果对象，包含以下属性：
    • audio_url：音频下载URL（有效期有限）。
    • audio_id：音频ID。
    • expires_at：URL过期时间。
  • 流式模式（stream=True）：返回迭代器，每个元素包含以下属性：
    • audio_data：当前分片的音频二进制数据（bytes）。
    • sentences：句子级别的合成信息（如有）。
    流式模式下，迭代器的最后一个元素除了包含音频数据分片外，还会额外返回audio_url（完整音频的下载地址）。如果在拼接音频数据时不跳过该元素，会导致最终生成的音频中同一段内容重复播放。因此在遍历迭代器时，需通过not chunk.audio_url条件过滤包含完整音频URL的最后一个元素。

示例代码

以下示例展示Qwen-Audio-TTS语音合成的非流式和流式调用方式。运行前请确保已设置环境变量DASHSCOPE_API_KEY。
不同模型需使用匹配的音色。更换模型时，请同步更换音色，并确认音色支持目标语言。具体对应关系请参见Qwen-Audio-TTS音色列表。
  • 非流式调用
  • 流式调用
非流式调用设置stream=False，等待合成完成后返回音频URL，通过URL下载音频文件。
# -*- coding: utf-8 -*-
import os
import dashscope
from dashscope.audio.http_tts.http_speech_synthesizer import HttpSpeechSynthesizer

# 未配置环境变量时，将下行替换为：api_key = "sk-xxx"，即替换为实际的API Key
api_key = os.getenv("DASHSCOPE_API_KEY")
dashscope.base_http_api_url = 'https://maas.qianwenaiapi.com/api/v1'

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

# 获取音频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}")