本文介绍通过DashScope Python SDK进行CosyVoice实时语音合成的类定义、请求参数和示例代码。
接口地址
SDK的接口地址需在初始化前设置为下方地址(包含WorkspaceId)。如需切换到其他地域,请修改 dashscope.base_websocket_api_url为对应地域的URL。
- 新加坡
- 华北2(北京)
- dashscope CLI
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference调用时请将{WorkspaceId}替换为真实的Workspace ID。SpeechSynthesizer
包路径:dashscope.audio.tts_v2.SpeechSynthesizer
构造方法
call() - 非流式调用
方法签名:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
text | str | 是 | 待合成的完整文本,长度不得超过20000字符。 |
bytes,完整音频数据。
说明:非流式调用,阻塞等待并一次性返回完整音频数据。适用于短文本、对实时性无严格要求的场景。每次调用前需重新初始化SpeechSynthesizer实例。
streaming_call() - 流式调用
方法签名:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
text | str | 是 | 当前待合成的文本片段。可多次调用以追加文本,单次不超过20000字符,累计不超过20万字符。 |
streaming_complete() - 结束流式合成
方法签名:
streaming_cancel() - 取消流式合成
方法签名:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
complete_timeout_millis | int | 否 | 等待服务端返回 task-finished 事件的超时时间,单位毫秒。默认值:10000。 |
SpeechSynthesizer 实例。
get_last_request_id() - 获取请求ID
方法签名:
str,最近一次请求的request_id,可用于问题排查和日志关联。
get_first_package_delay() - 获取首包延迟
方法签名:
float,从发送文本到收到第一块音频数据的延迟时间(毫秒)。需在合成完成后调用。
get_response() - 获取响应消息
方法签名:
dict,最近一次合成任务的响应消息(含 header/payload 键)。
构造参数
以下参数通过SpeechSynthesizer构造方法设置,用于控制合成音频的模型、音色、格式和音频特征。
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
model | str | 是 | 模型名称。 |
voice | str | 是 | 语音合成所使用的音色。
|
format | enum | 否 | 音频编码格式及采样率。默认值:AudioFormat.MP3_22050HZ_MONO_256KBPS。AudioFormat枚举类的包路径:dashscope.audio.tts_v2,支持MP3、WAV、PCM等格式。 |
volume | int | 否 | 音量。默认值:50。取值范围:[0, 100]。 |
speech_rate | float | 否 | 语速。默认值:1.0。取值范围:[0.5, 2.0]。 |
pitch_rate | float | 否 | 音调。默认值:1.0。取值范围:[0.5, 2.0]。 |
bit_rate | int | 否 | 音频码率(kbps)。音频格式为mp3或opus时,支持通过bit_rate参数调整码率。默认值:32。取值范围:[6, 510]。bit_rate需要通过additional_params参数进行设置: |
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需要通过additional_params参数进行设置: |
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需要通过additional_params参数进行设置: |
aigc_propagator | str | 否 | 设置AIGC隐性标识中的 ContentPropagator 字段,用于标识内容的传播者。仅在 enable_aigc_tag 为 true 时生效。默认值:阿里云UID。仅cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2支持该功能。 additional_params参数进行设置,参见enable_aigc_tag的示例。 |
aigc_propagate_id | str | 否 | 设置AIGC隐性标识中的 PropagateID 字段,用于唯一标识一次具体的传播行为。仅在 enable_aigc_tag 为 true 时生效。默认值:本次语音合成请求Request ID。仅cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2支持该功能。 additional_params参数进行设置,参见enable_aigc_tag的示例。 |
hot_fix | dict | 否 | 文本热修复配置,用于自定义指定词语的发音或对待合成文本进行替换。 cosyvoice-v2不支持该功能。
|
enable_markdown_filter | bool | 否 | 仅cosyvoice-v3-flash复刻音色支持该功能。
enable_markdown_filter需要通过additional_params参数进行设置: |
callback | ResultCallback | 否 | 回调函数实例,用于异步接收合成音频和事件通知。设置此参数时,call()方法以流式模式运行,音频数据通过on_data回调返回;不设置时,call()以非流式模式运行,直接返回完整音频的bytes数据。 |
ResultCallback
包路径:dashscope.audio.tts_v2.ResultCallback
on_open() - 连接建立
方法签名:
on_event() - 接收服务端回复
方法签名:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
message | str | 是 | 服务端响应事件(JSON格式),包含header(请求信息)和payload(输出信息)。其中payload.output包含事件类型、原始文本等信息,详见on_event消息中的output字段。 |
json.loads(message)解析后访问payload.output获取详细信息。
on_complete() - 合成完成
方法签名:
on_data() - 接收音频数据
方法签名:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
data | bytes | 是 | 当前批次的音频二进制数据片段,格式由构造参数format指定。 |
on_error() - 发生错误
方法签名:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
message | str | 是 | 错误描述信息,包含错误码和详细原因。 |
on_close() - 连接关闭
方法签名:
on_event消息中的output字段
on_event回调接收的JSON消息中,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时返回时间戳信息)。 |
示例代码
SDK提供了语音合成的关键接口,支持以下几种调用方式:
- 非流式调用:阻塞式,一次性发送完整文本,直接返回完整音频。适合短文本语音合成场景。
- 单向流式调用:非阻塞式,一次性发送完整文本,通过回调函数接收音频数据(可能分片)。适用于对实时性要求高的短文本语音合成场景。
- 双向流式调用:非阻塞式,可分多次发送文本片段,通过回调函数实时接收增量合成的音频流。适合实时性要求高的长文本语音合成场景。
- 非流式调用
- 单向流式调用
- 双向流式调用
单次调用发送的文本长度不得超过20000字符,超出限制将返回错误。