前提条件
Qwen-Audio-TTS
接口地址
SDK的接口地址由Client构造参数workspace/region决定(对应下方地址,包含WorkspaceId)。如需切换到其他地域,请修改 Client构造参数为对应地域的值。
- 新加坡
- 华北2(北京)
- dashscope CLI
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference调用时请将{WorkspaceId}替换为真实的Workspace ID。CosyVoice
接口地址
SDK的接口地址由Client构造参数workspace/region决定(对应下方地址,包含WorkspaceId)。如需切换到其他地域,请修改Client构造参数为对应地域的值。
- 新加坡
- 华北2(北京)
- dashscope CLI
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference调用时请将{WorkspaceId}替换为真实的Workspace ID。快速开始
Qwen-Audio-TTS / CosyVoice
SDK提供了语音合成的关键接口,支持以下几种调用方式:
- 非流式调用:阻塞式,一次性发送完整文本,直接返回完整音频。适合短文本语音合成场景。
- 单向流式调用:非阻塞式,一次性发送完整文本,通过迭代
stream返回的音频分片接收数据。适用于对实时性要求高的短文本语音合成场景。 - 双向流式调用:非阻塞式,可分多次发送文本片段,通过会话的
audio_chunks()/events()迭代实时接收增量合成的音频流。适合实时性要求高的长文本语音合成场景。
- 非流式调用
- 单向流式调用
- 双向流式调用
单次调用发送的文本长度不得超过20000字符,超出限制将返回错误。
CosyVoice
SDK提供了语音合成的关键接口,支持以下几种调用方式:
- 非流式调用:阻塞式,一次性发送完整文本,直接返回完整音频。适合短文本语音合成场景。
- 单向流式调用:非阻塞式,一次性发送完整文本,通过迭代
stream返回的音频分片接收数据。适用于对实时性要求高的短文本语音合成场景。 - 双向流式调用:非阻塞式,可分多次发送文本片段,通过会话的
audio_chunks()/events()迭代实时接收增量合成的音频流。适合实时性要求高的长文本语音合成场景。
- 非流式调用
- 单向流式调用
- 双向流式调用
单次调用发送的文本长度不得超过20000字符,超出限制将触发
DashScopeError 异常。按相同调用方式复用 共用代码示例,将 model 设为 cosyvoice-v3-plus,将 voice 设为 longanyang。请求参数
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 | 否 | 文本热修复配置,用于自定义指定词语的发音或对待合成文本进行替换。参数介绍:
|
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-v3-flash复刻音色支持该功能。
enable_markdown_filter需要通过parameters字典进行设置: |
接口参考
核心资源(client.audio.tts)
资源路径:client.audio.tts
功能:基于WebSocket的语音合成,提供一次性合成(synthesize)、流式合成(stream)与双向流式会话(connect)三种调用形态。
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()直到剩余文本合成完成并返回所有音频数据。未调用此方法可能导致尾部文本无法转换为语音。
会话指标与响应(会话属性)
first_package_delay:float,从发送文本到收到第一块音频数据的延迟时间(毫秒)。需在合成完成后读取。usage:dict,最近一次合成任务的用量信息。last_response:dict,最近一次合成任务的响应消息(含header/payload键)。最近一次请求的request_id可从session.last_response的header中获取,可用于问题排查和日志关联。
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时返回时间戳信息)。 |
Qwen-Audio-TTS
共享说明
- 核心资源(
client.audio.tts) - stream() - 流式调用
- send_text() - 流式输入(会话方法)
- stop() - 结束流式输入(会话方法)
- 会话指标与响应(会话属性)
- audio_chunks() - 迭代音频数据
- events() - 迭代服务端事件
- 错误处理
- 会话生命周期
- events()事件中的output字段
调用入口
synthesize() - 非流式调用
方法签名:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
text | str | 是 | 待合成的完整文本,长度不得超过20000字符。 |
bytes,完整音频数据。
说明:非流式调用,阻塞等待并一次性返回完整音频数据。适用于短文本、对实时性无严格要求的场景。synthesize与stream每次调用自建会话,无需复用实例。
cancel() - 取消流式合成(会话方法)
方法签名:
会话与事件迭代
流式合成不再使用回调接口:音频与服务端事件通过会话的迭代方法接收。stream()/synthesize()无需会话管理;双向流式会话(client.audio.tts.connect(...))的生命周期为:进入with上下文自动建立连接 → 多次send_text() → stop() → 读完全部结果 → 退出上下文自动关闭。
CosyVoice
共享说明
- 核心资源(
client.audio.tts) - stream() - 流式调用
- send_text() - 流式输入(会话方法)
- stop() - 结束流式输入(会话方法)
- 会话指标与响应(会话属性)
- audio_chunks() - 迭代音频数据
- events() - 迭代服务端事件
- 错误处理
- 会话生命周期
- events()事件中的output字段
调用入口
synthesize() - 非流式调用
方法签名:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
text | str | 是 | 待合成的完整文本,长度不得超过20000字符。 |
bytes,完整音频数据。
说明:非流式调用,阻塞等待并一次性返回完整音频数据。适用于短文本、对实时性无严格要求的场景。synthesize与stream每次调用自建会话,无需复用实例。
cancel() - 取消流式合成(会话方法)
方法签名:
会话与事件迭代
流式合成不再使用回调接口:音频与服务端事件通过会话的迭代方法接收。stream()/synthesize()无需会话管理;双向流式会话(client.audio.tts.connect(...))的生命周期为:进入with上下文自动建立连接 → 多次send_text() → stop() → 读完全部结果 → 退出上下文自动关闭。