跳转到主要内容
CosyVoice

CosyVoice服务端事件

本文介绍 CosyVoice 实时语音合成服务通过 WebSocket 推送给客户端的服务端事件,包括 task-started、result-generated、task-finished、task-failed 四类事件的数据结构与字段含义。

事件交互流程

  1. 发送 run-task 启动并配置任务,等待 task-started。
  2. 收到 task-started 后,通过 continue-task 发送文本,同时接收 result-generated 和合成音频。
  3. 文本全部发送完毕后,发送 finish-task,继续接收剩余结果和音频,直到收到 task-finished;任务失败时返回 task-failed。
result-generated 返回句子元信息,音频数据通过独立通道传输:WebSocket 使用二进制帧,AOQ 使用 Audio Track。连接、鉴权和音频传输方式请参见 WebSocket API 或 AOQ 接入。

task-started

任务启动成功,是客户端开始发送待合成文本的信号。
收到 task-started 后才能发送 continue-task。 run-task 只用于启动和配置任务,待合成文本通过 continue-task 发送。
{
  "header": {
    "action": "run-task",
    "task_id": "24a2157d-7eb1-4e8e-958f-5af8acfa8929",
    "streaming": "duplex"
  },
  "payload": {
    "input": {},
    "task_group": "audio",
    "task": "tts",
    "function": "SpeechSynthesizer",
    "model": "cosyvoice-v3-plus",
    "parameters": {
      "text_type": "PlainText",
      "voice": "longanyang",
      "format": "mp3",
      "sample_rate": 22050
    }
  }
}
参数类型说明
header.task_idstring客户端生成的任务 ID。
header.eventstring事件类型,固定为 task-started。
payloadobject无内容,为空对象。

result-generated

返回句子元信息,包括句子开始、音频数据块标记和句子结束。
sentence-end 只表示当前句子合成结束,不表示整个任务结束。 任务结束以 task-finished 为准。音频通过 WebSocket 二进制帧或 AOQ Audio Track 返回。
以下示例在启动任务时已设置 word_timestamp_enabled=true。
{
  "header": {
    "action": "continue-task",
    "task_id": "23ff08d9-5c49-4ce8-88b8-d3c6b60591ea",
    "streaming": "duplex"
  },
  "payload": {
    "input": {
      "text": "你好,欢迎使用语音合成。"
    }
  }
}
参数类型说明
header.task_idstring客户端生成的任务 ID。
header.eventstring事件类型,固定为 result-generated。
payload.outputobject输出信息。
payload.output.typestring子事件类型,取值:
  • sentence-begin:句子开始,返回待合成的文本内容
  • sentence-synthesis:标识音频数据块,每个事件后立即通过 WebSocket binary 通道传输一个音频数据帧
  • sentence-end:句子结束,返回文本内容和累计字符数
payload.output.sentence.indexinteger句子编号,从 0 开始。
payload.output.sentence.wordsarray字级别时间戳信息数组。
payload.output.sentence.words.textstring字的文本内容。
payload.output.sentence.words.begin_indexinteger字在句子中的开始位置索引,从 0 开始。
payload.output.sentence.words.end_indexinteger字在句子中的结束位置索引,从 1 开始。
payload.output.sentence.words.begin_timeinteger字对应音频的开始时间戳,单位:毫秒。
payload.output.sentence.words.end_timeinteger字对应音频的结束时间戳,单位:毫秒。
payload.output.original_textstring分句后的句子文本内容。
payload.usageobject计费信息,在 sentence-end 事件中返回。 说明: usage 表示当前任务的累计用量,不要将各事件中的 usage 相加。任务完成后,以 task-finished 中的最终累计用量为准。
payload.usage.charactersinteger截止当前累计的计费字符数。

task-finished

服务端返回 task-finished 事件,标志任务已结束。客户端可以关闭 WebSocket 连接或复用连接开启新任务。
{
  "header": {
    "action": "finish-task",
    "task_id": "24a2157d-7eb1-4e8e-958f-5af8acfa8929",
    "streaming": "duplex"
  },
  "payload": {
    "input": {}
  }
}
参数类型说明
header.task_idstring客户端生成的任务 ID。
header.eventstring事件类型,固定为 task-finished。
payload.usage.charactersinteger截止当前累计的计费字符数。

task-failed

当任务失败时,服务端返回 task-failed 事件。客户端需要关闭 WebSocket 连接并处理错误。 以下示例使用不支持的音频格式;任务启动后发送文本,服务端随后返回错误。错误码和错误信息随失败原因而变化。
{
  "header": {
    "action": "run-task",
    "task_id": "27928f57-cf3b-4f3d-a245-aef64895a3c9",
    "streaming": "duplex"
  },
  "payload": {
    "input": {},
    "task_group": "audio",
    "task": "tts",
    "function": "SpeechSynthesizer",
    "model": "cosyvoice-v3-plus",
    "parameters": {
      "text_type": "PlainText",
      "voice": "longanyang",
      "format": "invalid-format",
      "sample_rate": 22050
    }
  }
}
参数类型说明
header.task_idstring客户端生成的任务 ID。
header.eventstring事件类型,固定为 task-failed。
header.error_codestring错误码。
header.error_messagestring具体错误信息。