跳转到主要内容
语音合成

实时语音合成

了解实时语音合成的模型特性、流式调用方法和合成效果优化方式。

功能介绍

实时语音合成支持分段输入文本、逐段返回音频,适合将大模型生成的文本实时转换为语音。
  • 多语言与方言:根据目标语言选择模型和音色,也可通过指令指定方言。参见方言。
  • 表现力控制:通过自然语言指令调整语速、情感等表达,或在文本中插入情感与富语言标签。参见指令控制和情感与富语言标签。
  • 自定义音色:通过音色复刻从音频样本创建音色,或通过音色设计使用文字描述创建音色。
  • 精细控制与公式朗读:使用 SSML 与 LaTeX控制停顿、发音等效果,或将公式转换为语音。
  • Markdown 过滤:将包含表格等结构的 Markdown 文本转换成适合朗读的内容。参见Markdown 过滤。
  • 音频控制:可调节语速、语调、音量和码率,输出 PCM、WAV、MP3、Opus 等主流音频格式,最高支持 48 kHz 采样率。具体取值与支持范围以对应 API 参数说明为准。
各模型及音色支持的能力有所不同,使用前请核对对应功能的支持范围。需要通过 HTTP 一次提交完整文本时,请参见非实时语音合成。

开始使用

  • Qwen-Audio-TTS(推荐)
  • CosyVoice
以下使用 qwen-audio-3.1-tts-flash 和系统音色 longanhuan_v3.1,分段发送文本并将返回音频保存为 output.mp3。
Python
import os
import dashscope

# 若没有配置环境变量,请用千问AI平台API Key将下行替换为:api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.environ["DASHSCOPE_API_KEY"],
    base_url="https://maas.qianwenaiapi.com/api/v1",
)

with open("output.mp3", "wb") as audio:
  # 分段发送文本,逐段接收音频
  with client.audio.tts.connect(
      model="qwen-audio-3.1-tts-flash",
      voice="longanhuan_v3.1",
      format="mp3",
      sample_rate=24000,
  ) as session:
    for text in ["你好,欢迎使用千问AI平台。", "文本可以分段发送,音频会逐段返回。"]:
      session.send_text(text)
    session.flush()  # 触发已缓冲文本的合成(不结束输入)
    session.stop()   # 结束输入,等待剩余音频返回
    for chunk in session.audio_chunks():
      audio.write(chunk)

合成效果优化

语言与发音

根据需要控制的内容,选择对应方式:
需求使用方式
指定合成语音的目标语言使用 language_hints 指定整体合成语言,帮助模型按目标语言朗读数字、缩写和符号,改善小语种合成效果。
修正特定词语的发音或替换文本使用 hot_fix 为指定词语标注拼音,或在合成前将词语替换为目标文本。适合统一修正专有名词等局部内容。
精细控制停顿、数字读法或字词发音使用 SSML 标签标记需要控制的文本,按标签设置停顿、读法和发音等效果。
朗读数学公式使用 CosyVoice 的 LaTeX 公式朗读功能,将支持的数学公式转换为中文语音。
参数适用模型和配置方法请参见 Qwen-Audio-TTS API或 CosyVoice API;SSML 与 LaTeX 的适用模型、音色、接口及用法请参见 SSML 与 LaTeX。
使用 SSML 时,需要一次提交完整的 SSML 文本,再逐段接收音频,不支持分段输入。

Markdown 过滤

合成包含表格、链接等 Markdown 格式的内容时,可将 enable_markdown_filter 设为 true,让服务先将 Markdown 转换成适合朗读的文本。Qwen-Audio-TTS 和 CosyVoice 支持此功能,cosyvoice-v2 除外。配置方法参见 Qwen-Audio-TTS API 和 CosyVoice API。

指令控制

通过 instruction 参数,用自然语言说明要合成的语种,描述语速、情感或说话方式,控制合成语音的表现。
如需创建具有特定性别、年龄或音色特质的新音色,或参考声音描述的编写建议与示例,请参见音色设计。
  • Qwen-Audio-TTS
  • CosyVoice
qwen-audio-3.1-tts-plus、qwen-audio-3.1-tts-flash、qwen-audio-3.0-tts-plus、qwen-audio-3.0-tts-flash 的系统音色、复刻音色和设计音色均支持在合成请求中通过 instruction 设置自然语言指令。建议在 instruction 中说明合成语种和所需效果,以提升合成质量。指令中指定的语种须与待合成文本的语种一致。例如,合成荷兰语文本时,可设置:
请用荷兰话说,每个字都慢慢说

方言

通过方言功能,可将文本合成为河南话、四川话等中文方言语音。方言的选择方式取决于模型和音色类型。
  • Qwen-Audio-TTS
  • CosyVoice
  • 系统音色:从 Qwen-Audio-TTS 音色列表中选择支持目标方言的音色。直接支持该方言的音色无需额外设置;支持方言指令的音色使用 instruction 指定。
    使用 qwen-audio-3.1-tts-flash 的多语种与方言音色时,也可通过 language_hints 指定方言,参见多语种与方言音色的设置方法。
  • 复刻音色:通过 instruction 指定方言,例如 请用河南话表达。。
对于支持方言指令的音色,在初始化 SpeechSynthesizer 时传入 instruction="请讲上海话。",可将中文文本合成为上海话。
使用 Qwen3-TTS 时,请从 Qwen3-TTS 音色列表中选择支持目标方言的音色。

情感与富语言标签

适用于 qwen-audio-3.1-tts-plus、qwen-audio-3.1-tts-flash、qwen-audio-3.0-tts-plus 和 qwen-audio-3.0-tts-flash。
情感与富语言标签可控制语音的情感和风格,并在指定位置加入笑声、叹息等拟声效果。将标签直接写入待合成文本 text,无需额外参数。

使用示例

以下文本先使用兴奋语气,在指定位置插入笑声后继续合成正文:
[excited]今天的天气真不错![laughing]我们一起出去玩吧!
以下文本在第二句切换为兴奋语气:
[serious]请注意安全事项。[excited]好了,现在让我们开始吧!

支持标签

  • 控制类标签
  • 富语言类标签
控制类标签设置后续文本的情感或风格,直到出现下一个控制类标签;长句被自动切分时,作用范围以切分后的文本为界。
标签说明
[sad]悲伤
[amazed]惊叹
[deep and loud shouting]深沉大声呐喊
[trembling]颤抖
[angry]愤怒
[excited]兴奋
[sarcastic]讽刺
[curious]好奇
[like dracula]吸血鬼语气
[bored]无聊
[tired]疲倦
[scornful]轻蔑
[shouting]大喊
[asmr]ASMR 轻声
[panicked]惊慌
[mischievously]调皮
[empathetic]共情
[whispers]低声耳语
[reluctantly]不情愿
[crying]哭泣
[serious]严肃
[very slowly]非常缓慢
[very fast]非常快速

应用于生产环境

文本发送、音频播放、连接复用、并发管理和性能排查,请参见语音合成最佳实践。请求频率和并发数应遵循对应模型的限流。

取消任务

使用 Qwen-Audio-TTS 或 CosyVoice 模型时,如需中断当前轮次合成,可发送取消指令。服务端会结束当前任务并返回 task-finished。
调用方式版本要求使用方法
Python SDK2.0.1 及以上版本调用会话对象的 session.cancel()(client.audio.tts.connect 返回的会话)。
Java SDK2.22.26 及以上版本调用 SpeechSynthesizer.streamingCancel()。
WebSocket 原始协议无需 SDK发送 finish-task 事件,并在 input 中设置 directive=cancel。

支持模型

  • Qwen-Audio-TTS:qwen-audio-3.1-tts-plus、qwen-audio-3.1-tts-flash、qwen-audio-3.0-tts-plus、qwen-audio-3.0-tts-flash
  • CosyVoice:cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-plus、cosyvoice-v3-flash、cosyvoice-v2
  • Qwen3-TTS:qwen3-tts-flash-realtime
  • Sambert:sambert-zhinan-v1、sambert-zhiqi-v1、sambert-zhichu-v1、sambert-zhide-v1、sambert-zhijia-v1、sambert-zhiru-v1、sambert-zhiqian-v1、sambert-zhixiang-v1、sambert-zhiwei-v1、sambert-zhihao-v1、sambert-zhijing-v1、sambert-zhiming-v1、sambert-zhimo-v1、sambert-zhina-v1、sambert-zhishu-v1、sambert-zhistella-v1、sambert-zhiting-v1、sambert-zhixiao-v1、sambert-zhiya-v1、sambert-zhiye-v1、sambert-zhiying-v1、sambert-zhiyuan-v1、sambert-zhiyue-v1、sambert-zhigui-v1、sambert-zhishuo-v1、sambert-zhimiao-emo-v1、sambert-zhimao-v1、sambert-zhilun-v1、sambert-zhifei-v1、sambert-zhida-v1、sambert-camila-v1、sambert-perla-v1、sambert-indah-v1、sambert-clara-v1、sambert-hanna-v1、sambert-beth-v1、sambert-betty-v1、sambert-cally-v1、sambert-cindy-v1、sambert-eva-v1、sambert-donna-v1、sambert-brian-v1、sambert-waan-v1,请参见Sambert模型列表
系统音色与试听分别参见 Qwen-Audio-TTS、CosyVoice、Qwen3-TTS 和 Sambert 音色列表。使用复刻或设计音色时,合成模型须与创建音色时指定的目标模型一致。

API 参考

通过 AOQ 接入的流程和示例,请参见AOQ 接入。支持的模型及版本请参见模型与协议支持范围。

常见问题

确认 voice 为创建成功的音色 ID,创建音色时的 target_model 与合成时的 model 一致。音色状态、源音频要求及质量建议请参见音色复刻。
流式返回 WAV 时,文件头可能无法反映最终音频长度。如需准确的时长信息,可将 format 设为 pcm,接收完整音频后添加包含实际长度的 WAV 文件头。
请按以下场景逐一排查:
  1. 音频保存为完整文件(如 xx.mp3)的情况
    1. 音频格式一致性:请求参数中的音频格式须与文件后缀一致(如参数为 wav 则文件须为 .wav)。
    2. 播放器兼容性:确认播放器支持该音频的格式和采样率。
  2. 流式播放音频的情况
    1. 将音频流保存为完整文件,尝试用播放器播放。如果文件无法播放,请参考场景 1 的排查方法。
    2. 如果文件可正常播放,则问题在流式播放实现。请确认播放器支持流式播放(如 ffmpeg、pyaudio、AudioFormat、MediaSource 等)。
请按以下步骤逐一排查:
  1. 检查文本发送速度:确保发送间隔合理,避免上段音频播完后下段文本尚未到达。
  2. 检查回调函数性能:
    • 确认回调函数中无阻塞性业务逻辑。
    • 回调运行在 WebSocket 线程,阻塞会影响数据接收。建议将音频数据写入独立缓冲区,在其他线程中处理。
  3. 检查网络稳定性:网络波动可能导致音频传输中断或延迟。
分段输入时,过长的文本发送间隔会增加合成总时长;首次调用还包含 WebSocket 建连开销。高并发场景下的预热与耗时统计,请参见语音合成最佳实践。
通过新建业务空间并仅授权特定模型,可限制 API Key 的使用范围。请参见业务空间管理。
默认业务空间下,所有模型均可调用。子业务空间下,需要为 API Key 对应的子业务空间进行模型授权。请参见业务空间。