通过 WebSocket 使用 DashScope Python SDK 调用 Qwen-Audio-TTS / CosyVoice。
Qwen-Audio-TTS 和 CosyVoice 均通过
SDK的接口地址由Client构造参数
SDK提供了语音合成的关键接口,支持以下几种调用方式:
SDK提供了语音合成的关键接口,支持以下几种调用方式:
以下参数通过
以下参数通过
资源路径:
下方示例使用 Qwen-Audio-TTS。使用 CosyVoice 时,可将
以下签名展示 Qwen-Audio-TTS 的参数。CosyVoice 的
参数说明:
返回值:
方法签名:
参数说明:
返回值:
双向流式会话(
参数说明:
方法签名:
说明:通知服务端所有文本已发送完毕。调用后不阻塞当前线程,接收线程需继续消费
方法签名:
说明:取消当前轮次的流式语音合成任务。调用后,SDK 会立即结束当前任务。取消后当前会话不能再发送文本,如需继续合成请新建会话。
流式合成不再使用回调接口:音频与服务端事件通过会话的迭代方法接收。
方法签名:
返回值:
方法签名:
返回值:同时产出服务端响应事件(
合成过程中发生错误时,ws层会以
会话
消息示例:
解析示例:
调用方法见本组的核心资源。
调用方法见本组的核心资源。
client.audio.tts 合成语音,支持一次性合成、流式输出和双向流式会话。选择模型后,按该模型的要求设置音色和其他参数。
前提条件
接口地址
SDK的接口地址由Client构造参数workspace/region决定(对应下方地址,包含WorkspaceId)。如需切换到其他地域,请修改Client构造参数为对应地域的值。
- 华北2(北京)
- 新加坡
wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference调用时请将{WorkspaceId}替换为真实的Workspace ID。快速开始
Qwen-Audio-TTS / CosyVoice
SDK提供了语音合成的关键接口,支持以下几种调用方式:
- 非流式调用:阻塞式,一次性发送完整文本,直接返回完整音频。适合短文本语音合成场景。
- 单向流式调用:非阻塞式,一次性发送完整文本,通过迭代
stream返回的音频分片接收数据。适用于对实时性要求高的短文本语音合成场景。 - 双向流式调用:非阻塞式,可分多次发送文本片段,通过会话的
audio_chunks()/events()迭代实时接收增量合成的音频流。适合实时性要求高的长文本语音合成场景。
- 非流式调用
- 单向流式调用
- 双向流式调用
CosyVoice
SDK提供了语音合成的关键接口,支持以下几种调用方式:
- 非流式调用:阻塞式,一次性发送完整文本,直接返回完整音频。适合短文本语音合成场景。
- 单向流式调用:非阻塞式,一次性发送完整文本,通过迭代
stream返回的音频分片接收数据。适用于对实时性要求高的短文本语音合成场景。 - 双向流式调用:非阻塞式,可分多次发送文本片段,通过会话的
audio_chunks()/events()迭代实时接收增量合成的音频流。适合实时性要求高的长文本语音合成场景。
- 非流式调用
- 单向流式调用
- 双向流式调用
单次调用发送的文本长度不得超过20000字符,超出限制将触发 完整地域表见 Base URL 总览。
DashScopeError 异常。按相同调用方式复用 共用代码示例,将 model 设为 cosyvoice-v3-plus,将 voice 设为 longanyang。- dashscope CLI
请求参数
Qwen-Audio-TTS
以下参数通过client.audio.tts的synthesize/stream/connect方法设置,用于控制合成音频的模型、音色、格式和音频特征(model、voice、format、sample_rate、volume、rate、pitch、language_hints、enable_ssml为具名参数,其余参数通过parameters字典传入)。
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
model | str | 是 | 模型名称。 |
voice | str | 是 | 语音合成所使用的音色。
|
format | str | 否 | 音频编码格式。默认值:mp3。支持mp3、wav、pcm等格式;采样率通过sample_rate参数设置,默认22050。 |
volume | int | 否 | 音量。默认值:50。取值范围:[0, 100]。 |
rate | float | 否 | 语速。默认值:1.0。取值范围:[0.5, 2.0]。 |
pitch | float | 否 | 音调。默认值:1.0。取值范围:[0.5, 2.0]。 |
bit_rate | int | 否 | 音频码率(kbps)。音频格式为mp3或opus时,支持通过bit_rate参数调整码率。默认值:32。取值范围:[6, 510]。bit_rate需要通过parameters字典进行设置: |
word_timestamp_enabled | bool | 否 | 是否开启字级别时间戳。默认值:false。仅在流式输出模式下可用。支持复刻音色;支持的系统音色请参见Qwen-Audio-TTS音色列表。word_timestamp_enabled需要通过parameters字典进行设置: |
seed | int | 否 | 生成时使用的随机数种子,使合成的效果产生变化。在模型版本、文本、音色及其他参数均相同的前提下,使用相同的seed可复现相同的合成结果。默认值0。取值范围:[0, 65535]。 |
language_hints | list[str] | 否 | 使用 qwen-audio-3.1-tts-flash 的多语种与方言音色时,可通过此参数指定语种或方言。具体用法请参见多语种与方言音色的设置方法。
取值范围
|
instruction | str | 否 | 设置指令,用于控制方言、情感或角色等合成效果。使用说明请参见指令控制。 |
enable_aigc_tag | bool | 否 | 是否在生成的音频中添加AIGC隐性标识。设置为true时,会将隐性标识嵌入到支持格式(wav/mp3/opus)的音频中。默认值:false。enable_aigc_tag、aigc_propagator和aigc_propagate_id需要通过parameters字典进行设置: |
aigc_propagator | str | 否 | 设置AIGC隐性标识中的 ContentPropagator 字段,用于标识内容的传播者。仅在 enable_aigc_tag 为 true 时生效。默认值:阿里云UID。需要通过parameters字典进行设置,参见enable_aigc_tag的示例。 |
aigc_propagate_id | str | 否 | 设置AIGC隐性标识中的 PropagateID 字段,用于唯一标识一次具体的传播行为。仅在 enable_aigc_tag 为 true 时生效。默认值:本次语音合成请求Request ID。需要通过parameters字典进行设置,参见enable_aigc_tag的示例。 |
hot_fix | dict | 否 | 文本热修复配置,用于自定义指定词语的发音或对待合成文本进行替换。参数介绍:
|
enable_markdown_filter | bool | 否 | 是否启用 Markdown 过滤。启用后,服务会在合成前将 Markdown 转换成适合朗读的文本。默认值:False。设为 True 启用。通过 parameters={"enable_markdown_filter": True} 启用。 |
CosyVoice
以下参数通过client.audio.tts的synthesize/stream/connect方法设置,用于控制合成音频的模型、音色、格式和音频特征(model、voice、format、sample_rate、volume、rate、pitch、language_hints、enable_ssml为具名参数,其余参数通过parameters字典传入)。
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
model | str | 是 | 模型名称。 |
voice | str | 是 | 语音合成所使用的音色。
|
format | str | 否 | 音频编码格式。默认值:mp3。支持mp3、wav、pcm等格式;采样率通过sample_rate参数设置,默认22050。 |
volume | int | 否 | 音量。默认值:50。取值范围:[0, 100]。 |
rate | float | 否 | 语速。默认值:1.0。取值范围:[0.5, 2.0]。 |
pitch | float | 否 | 音调。默认值:1.0。取值范围:[0.5, 2.0]。 |
bit_rate | int | 否 | 音频码率(kbps)。音频格式为mp3或opus时,支持通过bit_rate参数调整码率。默认值:32。取值范围:[6, 510]。bit_rate需要通过parameters字典进行设置: |
word_timestamp_enabled | bool | 否 | 是否开启字级别时间戳。默认值:false。仅在流式输出模式下可用。支持的音色范围:cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2模型的复刻音色,以及CosyVoice音色列表中标记为支持的系统音色。其他模型的复刻音色不支持此功能。word_timestamp_enabled需要通过parameters字典进行设置: |
seed | int | 否 | 生成时使用的随机数种子,使合成的效果产生变化。在模型版本、文本、音色及其他参数均相同的前提下,使用相同的seed可复现相同的合成结果。默认值0。取值范围:[0, 65535]。 |
language_hints | list[str] | 否 | 指定语音合成的目标语言,提升合成效果。当数字、缩写、符号等朗读方式或者小语种合成效果不符合预期时使用,例如:
取值范围
|
instruction | str | 否 | 设置指令,用于控制方言、情感或角色等合成效果。使用说明请参见指令控制。 |
enable_aigc_tag | bool | 否 | 是否在生成的音频中添加AIGC隐性标识。设置为true时,会将隐性标识嵌入到支持格式(wav/mp3/opus)的音频中。默认值:false。 仅cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2支持该功能。 enable_aigc_tag、aigc_propagator和aigc_propagate_id需要通过parameters字典进行设置: |
aigc_propagator | str | 否 | 设置AIGC隐性标识中的 ContentPropagator 字段,用于标识内容的传播者。仅在 enable_aigc_tag 为 true 时生效。默认值:阿里云UID。仅cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2支持该功能。 parameters字典进行设置,参见enable_aigc_tag的示例。 |
aigc_propagate_id | str | 否 | 设置AIGC隐性标识中的 PropagateID 字段,用于唯一标识一次具体的传播行为。仅在 enable_aigc_tag 为 true 时生效。默认值:本次语音合成请求Request ID。仅cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2支持该功能。 parameters字典进行设置,参见enable_aigc_tag的示例。 |
hot_fix | dict | 否 | 文本热修复配置,用于自定义指定词语的发音或对待合成文本进行替换。 cosyvoice-v2不支持该功能。
|
enable_markdown_filter | bool | 否 | cosyvoice-v2 不支持此功能。
enable_markdown_filter需要通过parameters字典进行设置: |
接口参考
核心资源(client.audio.tts)
资源路径:client.audio.tts
功能:基于WebSocket的语音合成,提供一次性合成(synthesize)、流式合成(stream)与双向流式会话(connect)三种调用形态。
调用入口
下方示例使用 Qwen-Audio-TTS。使用 CosyVoice 时,可将 model 改为 cosyvoice-v3-plus,将 voice 改为 longanyang。
synthesize() - 非流式调用
以下签名展示 Qwen-Audio-TTS 的参数。CosyVoice 的 synthesize() 签名中,model 默认值为 cosyvoice-v1,voice 默认值为 longxiaochun。
方法签名:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
text | str | 是 | 待合成的完整文本,长度不得超过20000字符。 |
bytes,完整音频数据。
说明:非流式调用,阻塞等待并一次性返回完整音频数据。适用于短文本、对实时性无严格要求的场景。synthesize与stream每次调用自建会话,无需复用实例。
stream() - 流式调用
方法签名:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
text | str | 是 | 待合成的完整文本,长度不得超过20000字符。 |
Iterator[bytes],逐块产出的音频数据。
说明:流式合成,一次性发送完整文本并逐块产出音频(Iterator[bytes])。适用于对实时性要求高的短文本语音合成场景。需要分片提交文本时请使用双向流式会话(connect)。
send_text() - 流式输入(会话方法)
双向流式会话(client.audio.tts.connect(...))中分片提交文本。
方法签名:
text为当前待合成的文本片段。可多次调用send_text以追加文本,单次不超过20000字符,累计不超过20万字符。发送文本与接收音频需并发进行(配合audio_chunks()/events()和stop使用)。
stop() - 结束流式输入(会话方法)
方法签名:
audio_chunks()/events()直到剩余文本合成完成并返回所有音频数据。未调用此方法可能导致尾部文本无法转换为语音。
cancel() - 取消流式合成(会话方法)
方法签名:
会话指标与响应(会话属性)
first_package_delay:float,从发送文本到收到第一块音频数据的延迟时间(毫秒)。需在合成完成后读取。usage:dict,最近一次合成任务的用量信息。last_response:dict,最近一次合成任务的响应消息(含header/payload键)。最近一次请求的request_id可从session.last_response的header中获取,可用于问题排查和日志关联。
会话与事件迭代
流式合成不再使用回调接口:音频与服务端事件通过会话的迭代方法接收。stream()/synthesize()无需会话管理;双向流式会话(client.audio.tts.connect(...))的生命周期为:进入with上下文自动建立连接 → 多次send_text() → stop() → 读完全部结果 → 退出上下文自动关闭。
audio_chunks() - 迭代音频数据
方法签名:
Iterator[bytes],逐块产出的音频二进制数据片段,格式由format参数指定。
说明:在接收线程中迭代,逐块接收音频数据,合成过程中会产出多块。可将数据写入文件或送入播放设备。同一会话只允许一个events()或audio_chunks()读取者。
events() - 迭代服务端事件
方法签名:
dict,包含header(请求信息)和payload(输出信息))与音频bytes。其中payload.output包含事件类型、原始文本等信息,详见events()事件中的output字段。
说明:在接收线程中迭代服务端回复,包含合成事件的输出信息(事件类型、原始文本、句子信息等),可直接访问payload.output获取详细信息。
错误处理
合成过程中发生错误时,ws层会以DashScopeError异常抛出,异常触发后连接将自动关闭。可在发送/接收处使用try/except捕获并记录错误日志以便排查问题:
会话生命周期
- 进入
with上下文时自动建立连接(可在此前初始化音频输出流或打开文件等资源)。 - 所有文本合成完成且音频数据已全部产出后,
events()/audio_chunks()迭代结束;此后可读取first_package_delay等性能指标。 - 退出
with上下文时自动关闭连接(可在此后释放音频播放设备等资源)。
events()事件中的output字段
会话events()迭代产出的事件dict中,payload.output包含合成事件的输出信息,可用于跟踪合成进度和获取逐句信息。以下为output字段的结构说明:
| 字段 | 类型 | 说明 |
|---|---|---|
type | str | 事件类型。取值为sentence-begin(句子合成开始)、sentence-synthesis(句子合成中)或sentence-end(句子合成结束)。 |
original_text | str | 当前句子的原始文本。在sentence-begin和sentence-end事件中返回。 |
sentence | dict | 句子信息。包含index(句子序号)和words(词列表,开启word_timestamp_enabled时返回时间戳信息)。 |