CosyVoice 实时语音合成 WebSocket 客户端事件参考
用户指南： 关于模型介绍和选型建议请参见语音合成。
run-task
说明：启动语音合成任务，设置模型、音色、采样率等参数。 发送时机：建立 WebSocket 连接后立即发送。 响应事件：服务端返回 task-started 事件后才能发送后续指令。Example
复制
{
"header": {
"action": "run-task",
"task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
"streaming": "duplex"
},
"payload": {
"task_group": "audio",
"task": "tts",
"function": "SpeechSynthesizer",
"model": "cosyvoice-v3-flash",
"parameters": {
"text_type": "PlainText",
"voice": "longanyang",
"format": "mp3",
"sample_rate": 22050,
"volume": 50,
"rate": 1.0,
"pitch": 1.0,
"enable_ssml": false
},
"input": {}
}
}
object
body
必填
object
body
必填
请求体。
显示属性
显示属性
string
body
必填
任务组，固定为
audio。string
body
必填
任务类型，固定为
tts。string
body
必填
功能类型，固定为
SpeechSynthesizer。string
body
必填
模型名称。
object
body
必填
输入数据：固定为空对象
{}，待合成文本通过 continue-task 指令发送。object
body
必填
语音合成参数。
显示属性
显示属性
string
body
必填
固定为
PlainText。string
body
音频编码格式。取值范围：pcm、wav、mp3（默认）、opus。
cosyvoice-v1 不支持 opus 格式。integer
body
音频采样率（Hz）。取值范围：8000, 16000, 22050（默认）, 24000, 44100, 48000。
integer
body
音量。默认值：50。取值范围：[0, 100]。
float
body
语速。默认值：1.0。取值范围：[0.5, 2.0]。
float
body
音调。默认值：1.0。取值范围：[0.5, 2.0]。
integer
body
音频码率（kbps）。音频格式为 opus 时，支持通过
bit_rate 参数调整码率。默认值：32。取值范围：[6, 510]。cosyvoice-v1 模型不支持该参数。boolean
body
是否开启 SSML 功能。默认值：false。设为 true 后，仅允许发送一次 continue-task 指令。
boolean
body
是否开启字级别时间戳。默认值：false。适用范围：仅适用于 cosyvoice-v3-flash、cosyvoice-v3-plus 和 cosyvoice-v2 模型的复刻音色，以及音色列表中标记为支持的系统音色。
integer
body
生成时使用的随机数种子，使合成的效果产生变化。在模型版本、文本、音色及其他参数均相同的前提下，使用相同的 seed 可复现相同的合成结果。默认值：0。取值范围：[0, 65535]。cosyvoice-v1 不支持该参数。
array[string]
body
指定语音合成的目标语言，提升合成效果。当数字、缩写、符号等朗读方式或者小语种合成效果不符合预期时使用。取值范围：zh（中文）、en（英文）、fr（法语）、de（德语）、ja（日语）、ko（韩语）、ru（俄语）、pt（葡萄牙语）、th（泰语）、id（印尼语）、vi（越南语）。cosyvoice-v1 不支持该功能。
- 此参数为数组，但当前版本仅处理第一个元素，因此建议只传入一个值。
- 此参数用于指定语音合成的目标语言，该设置与声音复刻时的样本音频的语种无关。
string
body
设置指令，用于控制方言、情感或角色等合成效果。该功能仅适用于 cosyvoice-v3.5-flash、cosyvoice-v3.5-plus 和 cosyvoice-v3-flash 模型的复刻音色，以及音色列表中标记为支持 Instruct 的系统音色。长度限制：100 字符。汉字按 2 个字符计算，其他字符按 1 个字符计算。
boolean
body
是否在生成的音频中添加 AIGC 隐性标识。设置为 true 时，会将隐性标识嵌入到支持格式（wav/mp3/opus）的音频中。默认值：false。仅 cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2 支持该功能。
string
body
设置 AIGC 隐性标识中的
ContentPropagator 字段，用于标识内容的传播者。仅在 enable_aigc_tag 为 true 时生效。默认值：阿里云 UID。仅 cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2 支持该功能。string
body
设置 AIGC 隐性标识中的
PropagateID 字段，用于唯一标识一次具体的传播行为。仅在 enable_aigc_tag 为 true 时生效。默认值：本次语音合成请求 Request ID。仅 cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2 支持该功能。object
body
文本热修复配置，用于自定义指定词语的发音或对待合成文本进行替换。仅 cosyvoice-v3-flash 复刻音色支持该功能。
pronunciation：自定义发音。指定词语的拼音标注，用于纠正默认发音不准确的情况。replace：文本替换。在语音合成前将指定词语替换为目标文本。
复制
"hot_fix": {
"pronunciation": [
{"天气": "tian1 qi4"}
],
"replace": [
{"今天": "金天"}
]
}
boolean
body
是否启用 Markdown 过滤。启用该功能后，系统在合成语音前自动过滤输入文本中的 Markdown 标记符号。默认值：false。仅 cosyvoice-v3-flash 复刻音色支持该功能。
continue-task
说明：用于发送待合成文本。可一次性发送，也可分段按顺序发送。 发送时机：在接收到服务端返回的 task-started 事件后。 数量限制：- 单次调用最多发送 20000 字符
- 累计最多发送 200000 字符
- 发送间隔不得超过 23 秒，否则连接超时
Example
复制
{
"header": {
"action": "continue-task",
"task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
"streaming": "duplex"
},
"payload": {
"input": {
"text": "床前明月光，疑是地上霜"
}
}
}
object
body
必填
finish-task
说明：通知服务端文本发送完毕，请求结束任务。 发送时机：所有文本发送完毕后立即发送。 响应事件：服务端返回 task-finished 事件。Example
复制
{
"header": {
"action": "finish-task",
"task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
"streaming": "duplex"
},
"payload": {
"input": {}
}
}
object
body
必填
