实时

CosyVoice 客户端事件

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

必填

消息头。

显示属性

string

body

必填

指令类型，固定为 run-task。

string

body

必填

客户端生成的任务 ID（UUID 格式），用于关联后续事件。和后续 continue-task、finish-task 中的 task_id 保持一致。

string

body

必填

固定为 duplex。

object

body

必填

请求体。

显示属性

string

body

必填

任务组，固定为 audio。

string

body

必填

任务类型，固定为 tts。

string

body

必填

功能类型，固定为 SpeechSynthesizer。

string

body

必填

模型名称。

object

body

必填

输入数据：固定为空对象 {}，待合成文本通过 continue-task 指令发送。

object

body

必填

语音合成参数。

显示属性

string

文生图

必填

固定为 PlainText。

string

body

必填

语音合成所使用的音色。

系统音色：参见CosyVoice音色列表
复刻音色：通过声音复刻功能定制
声音设计音色：通过声音设计功能定制

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.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-flash、cosyvoice-v3-plus 和 cosyvoice-v2 模型的复刻音色，以及CosyVoice音色列表中标记为支持的系统音色。其他模型的复刻音色不支持此功能。

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 模型的复刻音色，以及CosyVoice音色列表中标记为支持 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-v2、cosyvoice-v1 不支持该功能。

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

必填

消息头。

显示属性

string

body

必填

指令类型，固定为 continue-task。

string

body

必填

任务 ID（UUID 格式），需要和 run-task 中的 task_id 保持一致。

string

body

必填

固定为 duplex。

object

body

必填

请求体。

显示属性

object

body

必填

包含待合成文本。

显示属性

string

body

必填

待合成文本。单次最多 20000 字符，累计最多 200000 字符。

finish-task

说明：通知服务端文本发送完毕，请求结束任务。 发送时机：所有文本发送完毕后立即发送。 响应事件：服务端返回 task-finished 事件。

Example

{
    "header": {
        "action": "finish-task",
        "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
        "streaming": "duplex"
    },
    "payload": {
        "input": {}
    }
}

object

body

必填

消息头。

显示属性

string

body

必填

指令类型，固定为 finish-task。

string

body

必填

任务 ID（UUID 格式），需要和 run-task 中的 task_id 保持一致。

string

body

必填

固定为 duplex。

object

body

必填

请求体。

显示属性

object

body

必填

固定为 {}。

本页目录

run-task
continue-task
finish-task

实时

CosyVoice 服务端事件

CosyVoice 实时语音合成 WebSocket 服务端事件参考

用户指南：关于模型介绍和选型建议请参见语音合成。

task-started

当客户端发送 run-task 指令后，服务端返回 task-started 事件，标志任务已成功开启。只有在接收到该事件后，客户端才能继续发送后续指令。

Example

{
  "header": {
    "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
    "event": "task-started",
    "attributes": {}
  },
  "payload": {}
}

字段	类型	说明
header.task_id	string	客户端生成的任务 ID。
header.event	string	事件类型，固定为 `task-started`。
payload	object	无内容，为空对象。

result-generated

客户端发送文本后，服务端持续返回 result-generated 事件。该事件返回句子元信息。

sentence-begin
sentence-synthesis
sentence-end

{
  "header": {
    "task_id": "3f2d5c86-0550-45c0-801f-xxxxxxxxxx",
    "event": "result-generated",
    "attributes": {}
  },
  "payload": {
    "output": {
      "sentence": {
        "index": 0,
        "words": []
      },
      "type": "sentence-begin",
      "original_text": "床前明月光，"
    }
  }
}

{
    "header": {
        "task_id": "3f2d5c86-0550-45c0-801f-xxxxxxxxxx",
        "event": "result-generated",
        "attributes": {}
    },
    "payload": {
        "output": {
            "sentence": {
                "index": 0,
                "words": []
            },
            "type": "sentence-synthesis"
        }
    }
}

{
  "header": {
    "task_id": "3f2d5c86-0550-45c0-801f-xxxxxxxxxx",
    "event": "result-generated",
    "attributes": {}
  },
  "payload": {
    "output": {
      "sentence": {
        "index": 0,
        "words": [
          {
            "text": "床",
            "begin_index": 0,
            "end_index": 1,
            "begin_time": 0,
            "end_time": 263
          }
        ]
      },
      "type": "sentence-end",
      "original_text": "床前明月光，"
    },
    "usage": {
      "characters": 6
    }
  }
}

字段	类型	说明
header.task_id	string	客户端生成的任务 ID。
header.event	string	事件类型，固定为 `result-generated`。
payload.output.type	string	子事件类型，取值：`sentence-begin`（句子开始，返回待合成的文本内容）、`sentence-synthesis`（标识音频数据块，每个事件后立即通过 WebSocket binary 通道传输一个音频数据帧）、`sentence-end`（句子结束，返回文本内容和累计字符数）。
payload.output.sentence.index	integer	句子编号，从 0 开始。
payload.output.sentence.words	array	字级别时间戳信息数组。
payload.output.sentence.words[].text	string	字的文本内容。
payload.output.sentence.words[].begin_index	integer	字在句子中的开始位置索引，从 0 开始。
payload.output.sentence.words[].end_index	integer	字在句子中的结束位置索引，从 1 开始。
payload.output.sentence.words[].begin_time	integer	字对应音频的开始时间戳，单位：毫秒。
payload.output.sentence.words[].end_time	integer	字对应音频的结束时间戳，单位：毫秒。
payload.output.original_text	string	分句后的句子文本内容。
payload.usage.characters	integer	截止当前累计的计费字符数（在 sentence-end 事件中返回）。

task-finished

服务端返回 task-finished 事件，标志任务已结束。客户端可以关闭 WebSocket 连接或复用连接开启新任务。

Example

{
  "header": {
    "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
    "event": "task-finished",
    "attributes": {
      "request_uuid": "0a9dba9e-d3a6-45a4-be6d-xxxxxxxxxxxx"
    }
  },
  "payload": {
    "usage": {
      "characters": 13
    }
  }
}

字段	类型	说明
header.task_id	string	客户端生成的任务 ID。
header.event	string	事件类型，固定为 `task-finished`。
payload.usage.characters	integer	截止当前累计的计费字符数。

task-failed

当任务失败时，服务端返回 task-failed 事件。客户端需要关闭 WebSocket 连接并处理错误。

Example

{
  "header": {
    "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
    "event": "task-failed",
    "error_code": "InvalidParameter",
    "error_message": "[tts:]Engine return error code: 418",
    "attributes": {}
  },
  "payload": {}
}

字段	类型	说明
header.task_id	string	客户端生成的任务 ID。
header.event	string	事件类型，固定为 `task-failed`。
header.error_code	string	错误码。
header.error_message	string	具体错误信息。

本页目录

task-started
result-generated
task-finished
task-failed

Fun-ASR

​run-task

​continue-task

​finish-task

​task-started

​result-generated

​task-finished

​task-failed

run-task

continue-task

finish-task

task-started

result-generated

task-finished

task-failed