了解实时语音合成的模型特性、流式调用方法和合成效果优化方式。
功能介绍
实时语音合成支持分段输入文本、逐段返回音频,适合将大模型生成的文本实时转换为语音。
- 多语言与方言:根据目标语言选择模型和音色,也可通过指令指定方言。参见方言。
- 表现力控制:通过自然语言指令调整语速、情感等表达,或在文本中插入情感与富语言标签。参见指令控制和情感与富语言标签。
- 自定义音色:通过音色复刻从音频样本创建音色,或通过音色设计使用文字描述创建音色。
- 精细控制与公式朗读:使用 SSML 与 LaTeX控制停顿、发音等效果,或将公式转换为语音。
- Markdown 过滤:将包含表格等结构的 Markdown 文本转换成适合朗读的内容。参见Markdown 过滤。
- 音频控制:可调节语速、语调、音量和码率,输出 PCM、WAV、MP3、Opus 等主流音频格式,最高支持 48 kHz 采样率。具体取值与支持范围以对应 API 参数说明为准。
各模型及音色支持的能力有所不同,使用前请核对对应功能的支持范围。需要通过 HTTP 一次提交完整文本时,请参见非实时语音合成。
开始使用
- 获取 API Key并配置到环境变量
DASHSCOPE_API_KEY。 - 示例使用接入地址
wss://maas.qianwenaiapi.com/api-ws/v1/inference。 - 安装 DashScope SDK,选择 Python 或 Java 示例。
- Qwen-Audio-TTS(推荐)
- CosyVoice
以下使用
qwen-audio-3.1-tts-flash 和系统音色 longanhuan_v3.1,分段发送文本并将返回音频保存为 output.mp3。Python
合成效果优化
语言与发音
根据需要控制的内容,选择对应方式:
| 需求 | 使用方式 |
|---|---|
| 指定合成语音的目标语言 | 使用 language_hints 指定整体合成语言,帮助模型按目标语言朗读数字、缩写和符号,改善小语种合成效果。 |
| 修正特定词语的发音或替换文本 | 使用 hot_fix 为指定词语标注拼音,或在合成前将词语替换为目标文本。适合统一修正专有名词等局部内容。 |
| 精细控制停顿、数字读法或字词发音 | 使用 SSML 标签标记需要控制的文本,按标签设置停顿、读法和发音等效果。 |
| 朗读数学公式 | 使用 CosyVoice 的 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="请讲上海话。",可将中文文本合成为上海话。情感与富语言标签
适用于
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,无需额外参数。
使用示例
以下文本先使用兴奋语气,在指定位置插入笑声后继续合成正文:
支持标签
- 控制类标签
- 富语言类标签
控制类标签设置后续文本的情感或风格,直到出现下一个控制类标签;长句被自动切分时,作用范围以切分后的文本为界。
| 标签 | 说明 |
|---|---|
[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 SDK | 2.0.1 及以上版本 | 调用会话对象的 session.cancel()(client.audio.tts.connect 返回的会话)。 |
| Java SDK | 2.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模型列表
API 参考
通过 AOQ 接入的流程和示例,请参见AOQ 接入。支持的模型及版本请参见模型与协议支持范围。
常见问题
使用复刻音色生成的音频无声音如何排查?
使用复刻音色生成的音频无声音如何排查?
确认
voice 为创建成功的音色 ID,创建音色时的 target_model 与合成时的 model 一致。音色状态、源音频要求及质量建议请参见音色复刻。为什么语音合成的实际时长与 WAV 文件显示的时长不一致?
为什么语音合成的实际时长与 WAV 文件显示的时长不一致?
流式返回 WAV 时,文件头可能无法反映最终音频长度。如需准确的时长信息,可将
format 设为 pcm,接收完整音频后添加包含实际长度的 WAV 文件头。为什么音频无法播放?
为什么音频无法播放?
请按以下场景逐一排查:
-
音频保存为完整文件(如 xx.mp3)的情况
- 音频格式一致性:请求参数中的音频格式须与文件后缀一致(如参数为 wav 则文件须为 .wav)。
- 播放器兼容性:确认播放器支持该音频的格式和采样率。
-
流式播放音频的情况
- 将音频流保存为完整文件,尝试用播放器播放。如果文件无法播放,请参考场景 1 的排查方法。
- 如果文件可正常播放,则问题在流式播放实现。请确认播放器支持流式播放(如 ffmpeg、pyaudio、AudioFormat、MediaSource 等)。
为什么音频播放卡顿?
为什么音频播放卡顿?
请按以下步骤逐一排查:
- 检查文本发送速度:确保发送间隔合理,避免上段音频播完后下段文本尚未到达。
-
检查回调函数性能:
- 确认回调函数中无阻塞性业务逻辑。
- 回调运行在 WebSocket 线程,阻塞会影响数据接收。建议将音频数据写入独立缓冲区,在其他线程中处理。
- 检查网络稳定性:网络波动可能导致音频传输中断或延迟。
语音合成耗时较长是什么原因?
语音合成耗时较长是什么原因?
分段输入时,过长的文本发送间隔会增加合成总时长;首次调用还包含 WebSocket 建连开销。高并发场景下的预热与耗时统计,请参见语音合成最佳实践。
如何限制 API Key 仅用于语音合成服务(权限隔离)?
如何限制 API Key 仅用于语音合成服务(权限隔离)?
通过新建业务空间并仅授权特定模型,可限制 API Key 的使用范围。请参见业务空间管理。
子业务空间的 API Key 能否调用 Qwen-Audio-TTS/CosyVoice 模型?
子业务空间的 API Key 能否调用 Qwen-Audio-TTS/CosyVoice 模型?
默认业务空间下,所有模型均可调用。子业务空间下,需要为 API Key 对应的子业务空间进行模型授权。请参见业务空间。