> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md).

# 服务器到客户端消息

Convai 在 Live API 中通过 WebRTC 数据通道发送给客户端的所有消息的完整参考，包括字段、类型和建议操作。

Convai Live API 服务器会在活动会话期间通过 WebRTC 数据通道发送这些消息。每种消息类型表示一个不同的事件——确认、机器人状态变化、动画数据或会话限制。请参见 [消息术语表](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/message-glossary.md) 以查看所有消息类型及其信封格式的摘要。

大多数服务器消息使用下方所示的 RTVI 信封格式 [`interaction-created`](#interaction-created)。后续示例仅展示内部的 `data` payload。 `server-response` 使用扁平的旧版结构，而 [bot 输出流](#bot-output-stream) 将其事件类型放在顶层。请参见 [回合生命周期和消息顺序](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/turn-lifecycle-and-message-ordering.md#two-envelope-forms) 以了解分流逻辑。

字段出现并不一致。某些可选字段会以 `null`形式发出，而其他字段则会被省略。请读取 [字段存在规则](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/turn-lifecycle-and-message-ordering.md#field-presence-rules) 并使用可选访问，而不要假设某个键一定存在。

***

### 机器人输出流

这些消息携带角色的回复文本及其语音状态转换。与本页其余部分不同，它们将事件类型放在消息的 **顶层** 处，而不是将其嵌套在 `data`.

#### bot-llm-text

机器人文本投影，以分块方式流式传输。按顺序拼接 `data.text` 以重建在 `/connect`.

**完整消息**

```json
{"label":"rtvi-ai","type":"bot-llm-text","data":{"text":"当然，马上就来。"}}
```

| 字段     | 类型     | 说明           |
| ------ | ------ | ------------ |
| `text` | string | 所选文本投影的一个增量块 |

在省略能力或 `bot_llm_text_mode: "legacy"`，这是用于对话路径的过滤文本。对于 `bot_llm_text_mode: "raw"`，它是在 Convai 的结构化输出解析和对话过滤之前，供提供方可见的文本。原始模式仅用于诊断，可能包含 JSON、控制语法、拒绝文本或其他不应被执行或发送到语音合成的内容。不能保证它会携带非文本的原生工具调用增量。请参见 [响应契约与解析](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/response-contract-and-parsing.md#bot-llm-text-modes).

**建议操作：** 追加到转录 UI 中正在进行的机器人消息里。

***

#### bot-llm-started / bot-llm-stopped

为一次回合的模型生成阶段划定边界。两者都携带一个空的 `data` 对象。

```json
{ "label": "rtvi-ai", "type": "bot-llm-started", "data": {} }
{ "label": "rtvi-ai", "type": "bot-llm-stopped", "data": {} }
```

**建议操作：** 显示和隐藏“思考中”指示器。不要使用 `bot-llm-stopped` 来门控动作执行——请参见 [顺序保证](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/turn-lifecycle-and-message-ordering.md#ordering-guarantees).

***

#### bot-tts-started

本回合的语音合成已开始。携带一个空的 `data` 对象。

```json
{ "label": "rtvi-ai", "type": "bot-tts-started", "data": {} }
```

***

#### bot 开始说话 / bot 停止说话

标记 bot 回合的音频边界。这些消息使用 `server-message` 信封，并且还会重复 `标签` 在……内部 `data`.

**完整消息**

```json
{
  "label": "rtvi-ai",
  "type": "server-message",
  "data": {
    "label": "rtvi-ai",
    "type": "bot-started-speaking",
    "response_id": "session-id:r4",
    "epoch": 1,
    "sequence": 3
  }
}
```

| 字段                  | 类型      | 存在情况  | 说明                |
| ------------------- | ------- | ----- | ----------------- |
| `标签`                | string  | 始终    | 始终 `"rtvi-ai"`    |
| `response_id`       | string  | 仅在设置为 | 此 bot 回复的标识符      |
| `neurosync_turn_id` | integer | 仅在设置为 | NeuroSync 回合标识符   |
| `epoch`             | integer | 仅在设置为 | NeuroSync 连接/会话周期 |
| `sequence`          | integer | 仅在设置为 | 每轮消息序号            |

**建议操作：** 驱动一个 `isSpeaking` 指示器。使用 `response_id` 来将 blendshape 和取消消息与生成它们的回合关联起来。

***

### 确认

#### server-response

`server-response` 会针对每条客户端到服务器的消息发送，以确认收到并报告处理结果。它使用 **直接（旧版）格式** ——而不是 RTVI 信封——因此这些字段出现在 JSON 对象顶层，而不是嵌套在 `data`.

```json
{
  "type": "server-response",
  "event_type": "tts-toggle",
  "status": "success",
  "message": "TTS 已启用",
  "extras": {
    "enabled": true
  }
}
```

| 字段           | 类型             | 说明                                                         |
| ------------ | -------------- | ---------------------------------------------------------- |
| `type`       | string         | 始终 `"server-response"`                                     |
| `event_type` | string         | 触发此响应的客户端消息类型                                              |
| `status`     | string         | 处理状态： `"success"`, `"error"`, `"processing"`，或 `"pending"` |
| `message`    | string \| null | 结果的可读说明                                                    |
| `extras`     | 对象 \| 空        | 额外的事件特定数据                                                  |

**状态值**

| 值              | 含义                      |
| -------------- | ----------------------- |
| `"success"`    | 消息已成功处理                 |
| `"error"`      | 发生错误；请参见 `message` 了解详情 |
| `"processing"` | 消息正在异步处理                |
| `"pending"`    | 消息已收到，但处理延迟             |

**`extras` 按事件类型划分的字段**

| `event_type`        | `extras` 字段                                                                                                                                                                              |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `上下文更新`             | `token_count`, `static_token_count`, `runtime_token_count`, `max_tokens`, `static_max_tokens`, `runtime_max_tokens`, `remaining_tokens`, `content`, `update_id`, `revision`, `duplicate` |
| `tts-toggle`        | `启用`                                                                                                                                                                                     |
| `stt-toggle`        | `muted`                                                                                                                                                                                  |
| `usage-toggle`      | `启用`                                                                                                                                                                                     |
| `trigger-message`   | `trigger_name`, `has_speak_tag`                                                                                                                                                          |
| `user_text_message` | `text`                                                                                                                                                                                   |
| `action-result`     | `tool_call_id`, `idempotent`；错误还包括 `error_code`                                                                                                                                          |

**关于 `message` 字段**

`message` 是一个 **面向开发者和日志的可读诊断字符串**。它不是一个稳定标识符。

{% hint style="danger" %}
不要根据 `message`的文本来分支应用逻辑。它没有版本控制，其措辞可能会在不同版本之间变化。请根据 `status`以及 `extras`.
{% endhint %}

中的字段来分支。

| 情况                    | 示例 `message`                                       |
| --------------------- | -------------------------------------------------- |
| 上下文已正常应用              | `上下文已成功更新（追加模式，run_llm=auto）`                      |
| 上下文已应用，但因用户正在说话而未返回响应 | `上下文已静默更新（请求了 run_llm=true，但用户正在说话——机器人会在用户说完后回应）` |
| 上下文已应用，但因机器人状态而未返回响应  | `上下文已静默更新（请求了 run_llm=true，但因机器人状态：正在说话而降级）`       |
| 上下文已应用，并且机器人已被打断以进行回应 | `上下文已更新并发生中断（run_llm=true 打断了机器人的说话，触发新的响应）`       |
| 切换项                   | `TTS 已启用`, `STT 已静音`, `Usage-update 流式传输已启用`       |
| 去抖动重复项                | `TTS 切换已去抖动（窗口内重复启用）`, `机器人中断已去抖动（窗口内重复）`          |
| 成功的空操作                | `触发消息已处理，但没有响应`, `触发已处理，但未生成上下文`                   |
| 失败                    | `叙事设计服务不可用`, `动态信息中未提供文本`, `已超过使用限制`               |
| 未处理的服务器错误             | `处理 <event_type> 失败：<error detail>`                |

当处理程序成功但无需报告任何内容时， `message` 是 **会被完全省略** ，而不是作为空字符串或 `null`.

**错误示例**

```json
{
  "type": "server-response",
  "event_type": "tts-toggle",
  "status": "error",
  "message": "TTS 绕过过滤器不可用"
}
```

**验证错误 — JSON 无效**

```json
{
  "type": "server-response",
  "event_type": "parse-error",
  "status": "error",
  "message": "解析消息失败：JSON 无效或 UTF-8 编码无效"
}
```

**验证错误 — 缺少 type 字段**

```json
{
  "type": "server-response",
  "event_type": "validation-error",
  "status": "error",
  "message": "消息缺少必需的 'type' 字段"
}
```

**验证错误 — 未知消息类型**

```json
{
  "type": "server-response",
  "event_type": "unknown-message-type",
  "status": "error",
  "message": "未知的消息类型：unknown-message-type",
  "extras": {
    "supported_types": ["trigger-message", "context-update", "tts-toggle"]
  }
}
```

**建议操作：** 检查 `status` 字段于每个 `server-response`。处理 `"error"` 响应时，请读取 `message` 并更新你的 UI。使用 `extras` 字段来反映当前状态——例如，在 `event_type` 是 `stt-toggle`.

***

### 会话与生命周期

#### interaction-created

在会话生命周期早期、创建 interaction ID 时发送。这是第一条携带完整 RTVI 信封的消息。

**完整 RTVI 信封**

```json
{
  "label": "rtvi-ai",
  "type": "server-message",
  "data": {
    "type": "interaction-created",
    "interaction_id": "int_abc123def456",
    "character_session_id": "cs_xyz789"
  }
}
```

**内部 `data` payload**

```json
{
  "type": "interaction-created",
  "interaction_id": "int_abc123def456",
  "character_session_id": "cs_xyz789"
}
```

| 字段                     | 类型     | 说明                         |
| ---------------------- | ------ | -------------------------- |
| `type`                 | string | 始终 `"interaction-created"` |
| `interaction_id`       | string | 此交互会话的唯一标识符                |
| `character_session_id` | string | 角色会话标识符                    |

**建议操作：** 存储 `interaction_id` 用于分析、日志记录或会话跟踪。

***

#### usage-limit-reached

当使用配额超出时发送。处理此消息以显示适当的反馈并关闭会话。

```json
{
  "type": "usage-limit-reached",
  "quota_type": "minutes",
  "message": "你已超过每月配额"
}
```

| 字段           | 类型     | 说明                                      |
| ------------ | ------ | --------------------------------------- |
| `type`       | string | 始终 `"usage-limit-reached"`              |
| `quota_type` | string | 被超出的配额类型，例如 `"minutes"` 或 `"api_calls"` |
| `message`    | string | 解释该限制的人类可读消息                            |

**建议操作：** 向用户显示 `message` 并优雅地结束会话。

***

#### bot-turn-completed

当机器人到达终止回合状态时发送：它已完成说话、被用户打断，或者因为所需输出无法送达而中止。

```json
{
  "type": "bot-turn-completed",
  "was_interrupted": false
}
```

| 字段                | 类型     | 说明                                         |
| ----------------- | ------ | ------------------------------------------ |
| `type`            | string | 始终 `"bot-turn-completed"`                  |
| `was_interrupted` | 布尔值    | `true` 如果用户打断了机器人； `false` 如果该回合正常完成       |
| `was_aborted`     | 布尔值    | 可选。 `true` 如果该回合因为所需的机器人输出无法送达而结束          |
| `error_reason`    | string | 可选。机器可读的中止原因；当前为 `"audio_delivery_failed"` |

`was_aborted` 和 `error_reason` 是可叠加的可选字段。正常完成时会省略它们。

**建议操作：** 当此消息到达时，更新 UI 状态并重新启用用户输入控件。

***

#### user-idle-warning

当用户在已配置的时长内处于空闲状态时发送，警告即将断开连接。

```json
{
  "type": "user-idle-warning",
  "remaining_seconds": 300,
  "message": "你已处于空闲状态。你将在 5 分钟后断开连接。"
}
```

| 字段                  | 类型             | 说明                       |
| ------------------- | -------------- | ------------------------ |
| `type`              | string         | 始终 `"user-idle-warning"` |
| `remaining_seconds` | integer        | 会话断开前剩余的秒数               |
| `message`           | string \| null | 可选的人类可读警告消息              |

**建议操作：** 向用户显示警告并提示活动，或者发送一个 [`reset-idle-timer`](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#reset-idle-timer) 消息以重置空闲计时器。

***

#### llm-no-response

当 LLM 明确决定不响应用户输入时发送。

```json
{
  "type": "llm-no-response",
  "reason": "abstain"
}
```

| 字段       | 类型             | 说明                            |
| -------- | -------------- | ----------------------------- |
| `type`   | string         | 始终 `"llm-no-response"`        |
| `reason` | string \| null | 无响应的原因； `"abstain"` 表示模型选择不发言 |

**建议操作：** 更新你的 UI，以指示机器人选择了不响应，或者根据你的 UX 需求静默处理该事件。

***

### 交互与转录

#### final-user-transcription

随当前回合中用户所说内容的最终转录一起发送。

```json
{
  "type": "final-user-transcription",
  "text": "你好，你今天怎么样？",
  "speaker_id": "user_123",
  "speaker_name": "Alice",
  "participant_id": "participant_456"
}
```

| 字段               | 类型             | 说明                              |
| ---------------- | -------------- | ------------------------------- |
| `type`           | string         | 始终 `"final-user-transcription"` |
| `text`           | string         | 转录文本                            |
| `speaker_id`     | string \| null | 说话者标识符                          |
| `speaker_name`   | string \| null | 说话者显示名称                         |
| `participant_id` | string \| null | 参与者标识符                          |

**建议操作：** 显示 `text` 在聊天 UI 中，或者将其追加到对话历史中。

***

#### moderation-response

当内容审核已处理用户输入时发送。

```json
{
  "type": "moderation-response",
  "result": false,
  "user_input": "被标记的内容",
  "reason": "不当语言"
}
```

| 字段           | 类型             | 说明                             |
| ------------ | -------------- | ------------------------------ |
| `type`       | string         | 始终 `"moderation-response"`     |
| `result`     | 布尔值            | `true` 如果内容通过审核； `false` 如果被阻止 |
| `user_input` | string         | 被审核的输入文本                       |
| `reason`     | string \| null | 阻止原因； `null` 如果内容通过            |

**建议操作：** 如果 `result` 是 `false`，则可选择向用户显示反馈，说明输入已被阻止。

***

#### behavior-tree-response

随角色 AI 行为的行为树数据一起发送。

```json
{
  "type": "behavior-tree-response",
  "bt_code": "...",
  "bt_constants": "...",
  "narrative_section_id": "section_1"
}
```

| 字段                     | 类型     | 说明                            |
| ---------------------- | ------ | ----------------------------- |
| `type`                 | string | 始终 `"behavior-tree-response"` |
| `bt_code`              | string | 行为树代码                         |
| `bt_constants`         | string | 行为树常量                         |
| `narrative_section_id` | string | 当前叙事章节标识符                     |

***

### 规范化模型输出

#### model-output

当客户端协商时发送 `capabilities.model_output_version: 2`。这是可渲染和可执行模型输出的类型化权威来源。旧版 `action-response` 也可能作为兼容性投影发出；请处理一个权威来源，而不是两者都处理。

```json
{
  "type": "model-output",
  "version": 2,
  "output_id": "out_abc123",
  "logical_turn_id": "turn_42",
  "format": "convai-combined-json",
  "raw": "{\"response\":\"我会把它打开。\",\"actions\":[\"Wave\"]}",
  "items": [
    {
      "type": "message",
      "role": "assistant",
      "channel": "final",
      "content": "我会把它打开。"
    },
    {
      "type": "semantic_action",
      "id": "act_abc123",
      "name": "Wave",
      "target": null
    }
  ],
  "final": true
}
```

| 字段                | 类型      | 说明                                                                                          |
| ----------------- | ------- | ------------------------------------------------------------------------------------------- |
| `type`            | string  | 始终 `"model-output"`.                                                                        |
| `版本`              | integer | 始终 `2`.                                                                                     |
| `output_id`       | string  | 信封标识符。请根据此字段对重复投递去重。                                                                        |
| `logical_turn_id` | string  | 一个可选的关联 ID，由同一逻辑回合的输出信封共享。若存在，其值最多为 `128` UTF-8 字节。                                         |
| `format`          | string  | `"text"`, `"convai-combined-json"`, `"semantic-actions-json"`，或 `"client-tool-calls-json"`. |
| `原始`              | string  | 保留用于诊断的精确提供方或运行时输出。切勿将此字段作为可信内容执行或渲染。                                                       |
| `items`           | 对象数组    | Convai 验证过的语义项。                                                                             |
| `final`           | 布尔值     | 始终 `true` 针对这个已完成的信封。它并不意味着之后不会有另一个信封共享同一个 `logical_turn_id`.                               |

| 物品 `type` | 字段                                    | 含义                                                                                                                                                |
| --------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `message` | `role`, `channel`, `content`          | 用于 `"final"` 或 `"commentary"`.                                                                                                                    |
| `语义动作`    | `id`, `name`, `target`                | 已解析的语义动作。 `target` 可能是 `null`.                                                                                                                    |
| `工具调用`    | `id`, `name`, `target`, `arguments`   | 相关联的客户端工具调用。返回 [`action-result`](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#action-result) 用于其 `id`. |
| `情绪`      | `name`, `级别`                          | 带有刻度的回合情绪 `1`, `2`，或 `3`.                                                                                                                         |
| `扩展`      | `schema`, `版本`, `payload`, `fallback` | 带 schema 版本的扩展项。此预览未定义显示或快速响应扩展 schema。                                                                                                           |

当前生产者会发出 final 通道消息、语义动作、客户端工具调用和情绪。candidate 协议和解析器表示了 commentary 通道消息和 `扩展` items，但当前运行时并不生成它们。

多个信封可以共享一个 `logical_turn_id`，例如文本信封后跟一个语义动作或客户端工具调用。仅按 `output_id`. Convai 不执行或授权 `工具调用` 项目；在返回结果之前，请在您的应用中验证并执行它们。

***

### 动作

#### action-response

随语义动作或客户端工具调用的有序兼容性投影发送。请参阅 [连接 API](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/connect-api.md) 用于 `action_config` 以及能力选择。

```json
{
  "type": "action-response",
  "actions": [
    { "name": "移动到", "target": "cube" },
    { "name": "挥手" }
  ]
}
```

| 字段                 | 类型     | 说明                     |
| ------------------ | ------ | ---------------------- |
| `type`             | string | 始终 `"action-response"` |
| `动作`               | 对象数组   | 要触发的有序动作数组             |
| `actions[].name`   | string | 动作或动画标识符               |
| `actions[].target` | string | 可选的目标对象或角色名称           |

旧版语义动作使用 `{ name, target? }`. Convai 在发出前会根据会话可供性验证语义动作名称以及任何非空目标。

动作协议 v2 也会以这种形式投影客户端工具调用：

```json
{
  "type": "action-response",
  "actions": [
    {
      "kind": "tool_call",
      "id": "call_abc123",
      "name": "open_training_record",
      "arguments": {
        "record_id": "record-42"
      }
    }
  ]
}
```

| 字段          | 类型     | 说明                              |
| ----------- | ------ | ------------------------------- |
| `类型`        | string | 始终 `"tool_call"` 用于 v2 客户端工具调用。 |
| `id`        | string | 所需终态结果的关联 ID。                   |
| `name`      | string | 声明的客户端工具名称。                     |
| `target`    | string | 可选兼容字段。不要将其视为该工具参数的授权。          |
| `arguments` | object | 根据该工具声明的输入模式进行验证的 JSON 对象。      |

数组顺序会被保留，但 Convai 不执行这些操作，也不保证按顺序的客户端执行。请应用您自己的授权、调度、取消和重试策略。如果您协商使用了模型输出 v2，请消费 `model-output.items` 并忽略重复的 `action-response` 投影。

***

### 动画与口型同步

#### bot-emotion

当机器人表达情绪时发送。可用它来触发头像动画或更新视觉反馈元素。

```json
{
  "type": "bot-emotion",
  "emotion": "高兴",
  "scale": 2
}
```

| 字段     | 类型      | 说明                                              |
| ------ | ------- | ----------------------------------------------- |
| `type` | string  | 始终 `"bot-emotion"`                              |
| `情绪`   | string  | 情绪名称，例如 `"happy"`, `"悲伤"`, `"excited"`，或 `"愤怒"` |
| `级别`   | integer | 强度级别： `1` = 轻微， `2` = 中等， `3` = 强烈              |

**建议操作：** 为接收到的内容触发相应的头像表情或动画 `情绪` 和 `级别`.

***

#### 音素口型

在机器人讲话期间会频繁发送，包含用于头像口部动画的口型同步数据。值表示各个口型形状的混合权重。

```json
{
  "type": "visemes",
  "visemes": {
    "sil": 0.0,
    "pp": 0.8,
    "ff": 0.0,
    "th": 0.0,
    "dd": 0.0,
    "kk": 0.0,
    "ch": 0.0,
    "ss": 0.0,
    "nn": 0.0,
    "rr": 0.0,
    "aa": 0.2,
    "e": 0.0,
    "ih": 0.0,
    "oh": 0.0,
    "ou": 0.0
  }
}
```

| 字段     | 类型     | 说明                         |
| ------ | ------ | -------------------------- |
| `type` | string | 始终 `"visemes"`             |
| `音素口型` | object | 音素口型键到混合权重的映射（`0.0`–`1.0`) |

**音素口型键**

| 键    | 音素      |
| ---- | ------- |
| `静音` | 静音      |
| `pp` | P、B、M   |
| `ff` | F、V     |
| `th` | TH      |
| `dd` | T、D     |
| `kk` | K、G     |
| `ch` | CH、J、SH |
| `ss` | S、Z     |
| `nn` | N、L     |
| `rr` | R       |
| `aa` | 一个      |
| `e`  | E       |
| `ih` | I       |
| `oh` | O       |
| `ou` | U、W     |

**建议操作：** 每次收到此消息时，将音素口型权重应用到头像口型同步混合形状。

***

#### neurosync-blendshapes

随单帧面部动画混合形状数据发送（每帧 251 个值）。

```json
{
  "type": "neurosync-blendshapes",
  "blendshapes": [0.0, 0.1, 0.05, 0.0]
}
```

| 字段     | 类型       | 说明                                 |
| ------ | -------- | ---------------------------------- |
| `type` | string   | 始终 `"neurosync-blendshapes"`       |
| `混合形状` | float\[] | 251 个混合形状值的数组，每个值都在范围内 `0.0`–`1.0` |

**建议操作：** 将混合形状值应用到当前帧的头像面部骨骼绑定。

***

#### chunked-neurosync-blendshapes

将多帧混合形状数据批量封装到一条消息中发送。请使用此消息类型代替 `neurosync-blendshapes` 当服务器为提高效率发送批量数据时。

```json
{
  "type": "chunked-neurosync-blendshapes",
  "blendshapes": [
    [0.0, 0.1, 0.05],
    [0.02, 0.12, 0.04],
    [0.01, 0.09, 0.06]
  ]
}
```

| 字段     | 类型          | 说明                                   |
| ------ | ----------- | ------------------------------------ |
| `type` | string      | 始终 `"chunked-neurosync-blendshapes"` |
| `混合形状` | float\[]\[] | 混合形状帧数组；每帧包含 251 个值，范围为 `0.0`–`1.0`  |

**建议操作：** 将这些帧入队并按顺序应用，以生成平滑的面部动画。

***

#### neurosync-blendshapes-cancel

当一个提前送达的 NeuroSync 轮次被截断时发送——可能由于中断、强制轮次结束或被替代的输出会话。正常完成不会 **包含** 发出此消息。仅发送给选择接收提前送达分块的客户端。

```json
{
  "type": "neurosync-blendshapes-cancel",
  "response_id": "session-id:r4",
  "neurosync_turn_id": 4,
  "epoch": 1,
  "sequence": 18,
  "valid_through_frame_index": 179,
  "reason": "interruption"
}
```

| 字段                          | 类型              | 说明                                      |
| --------------------------- | --------------- | --------------------------------------- |
| `response_id`               | string          | 要取消的生命周期响应标识符                           |
| `neurosync_turn_id`         | integer         | 要取消的 NeuroSync 轮次标识符                    |
| `epoch`                     | integer         | NeuroSync 连接/会话周期                       |
| `sequence`                  | integer         | 每轮消息序列                                  |
| `valid_through_frame_index` | integer \| null | 由已释放音频支持的包含性最后帧索引。若省略或 `null`，则强制丢弃所属者的 |
| `reason`                    | string          | 取消原因，例如 `"interruption"`                |

**建议操作：** 清除消息中标识的所有者的缓冲混合形状。

* 如果 `valid_through_frame_index` 如果存在，则保留直到该索引（含）为止的帧，并丢弃其后的所有内容。
* 如果省略或 `null`，则立即强制丢弃所有者的缓冲帧。这发生在活动中断和已完成所有者被替代的情况下；若保留视觉尾部，会导致音频停止后嘴唇仍在动。
* 请 **包含** 将取消应用于当前活动所有者，除非它与消息中的所有者匹配。

***

#### blendshape-turn-stats

在机器人轮次结束时发送，包含该轮次混合形状生成的统计信息。可用于调试或分析。

```json
{
  "type": "blendshape-turn-stats",
  "stats": {
    "total_blendshapes": 150,
    "total_audio_bytes": 48000,
    "total_turn_duration_ms": 3000.0,
    "total_audio_duration_ms": 2800.0,
    "fps": 50.0,
    "was_interrupted": false
  }
}
```

| 字段                              | 类型      | 说明                           |
| ------------------------------- | ------- | ---------------------------- |
| `type`                          | string  | 始终 `"blendshape-turn-stats"` |
| `stats.total_blendshapes`       | integer | 该轮次生成的混合形状帧总数                |
| `stats.total_audio_bytes`       | integer | 音频数据总大小（字节）                  |
| `stats.total_turn_duration_ms`  | float   | 轮次总时长（毫秒）                    |
| `stats.total_audio_duration_ms` | float   | 音频总时长（毫秒）                    |
| `stats.fps`                     | float   | 混合形状帧每秒数                     |
| `stats.was_interrupted`         | 布尔值     | `true` 如果该轮次在完成前被中断          |

***

### 音频

#### audio-data

当音频通过数据通道而不是（或除了）标准 WebRTC 音频轨道传输时发送。只有在以下情况才会收到此消息： `音频路由` 设置为 `"data_only"` 或 `"both"` ，位于 `audio_config` 的 `/connect` 请求。

```json
{
  "type": "audio-data",
  "sample_rate": 48000,
  "channels": 1,
  "audio": "AAEAAg==...",
  "includes_wav_header": false
}
```

| 字段          | 类型      | 说明                                              |
| ----------- | ------- | ----------------------------------------------- |
| `type`      | string  | 始终 `"audio-data"`                               |
| `采样率`       | integer | 音频采样率（Hz），例如 `16000`, `24000`，或 `48000`         |
| `声道数`       | integer | 音频声道数量： `1` = 单声道， `2` = 立体声                    |
| `音频`        | string  | Base64 编码的音频数据（原始 PCM 或带头部的 WAV）                |
| `包含 WAV 头部` | 布尔值     | `true` 如果音频载荷包含 44 字节的 WAV 头部； `false` 用于原始 PCM |

有关完整解码步骤、播放实现和配置选项，请参阅 [通过数据通道传输音频数据](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/audio-data-via-data-channel.md).

***

### 语音活动检测

这些消息来自基于 VAD 的语音转文本门控系统，该系统仅在检测到语音时激活 STT 服务。可用它们来驱动聆听指示器。

#### vad-stt-started

在检测到确认的语音后，STT 服务已取消静音并正在处理音频。

```json
{
  "type": "vad-stt-started",
  "timestamp": "2026-08-10T10:30:45.123Z",
  "pre_roll_ms": 1500
}
```

| 字段      | 类型      | 说明                                  |
| ------- | ------- | ----------------------------------- |
| `时间戳`   | string  | STT 取消静音时的 ISO 8601 时间戳             |
| `预录毫秒数` | integer | 捕获的音频量 *之前* 预先添加到流中的语音检测内容，以免遗漏任何内容 |

**建议操作：** 显示“正在聆听”或“正在转写”指示器。

***

#### vad-stt-stopped

在余音期结束后，STT 服务已静音。

```json
{
  "type": "vad-stt-stopped",
  "timestamp": "2026-08-10T10:30:48.456Z",
  "reason": "hangover_elapsed",
  "audio_duration_ms": 3200
}
```

| 字段          | 类型              | 说明                              |
| ----------- | --------------- | ------------------------------- |
| `时间戳`       | string          | STT 静音时的 ISO 8601 时间戳           |
| `reason`    | string          | 转写停止的原因，例如 `"hangover_elapsed"` |
| `音频持续时长毫秒数` | integer \| null | 此段中处理的音频总量                      |

**建议操作：** 移除聆听指示器。

***

#### vad-stt-debug

详细的 VAD 状态变化、语音检测和静音检测事件。仅在会话以以下方式连接时发送： `debug: true` 并且调试事件已启用。载荷形状因事件而异，旨在用于诊断而非应用逻辑。

***

### 诊断

这些消息仅在会话以以下方式连接时发送： `debug: true`.

| Message        | 用途                                                                                                                                                |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `turn-trace`   | 每轮时序和阶段转换跟踪                                                                                                                                       |
| `server-log`   | 向客户端暴露的服务器端日志行                                                                                                                                    |
| `usage-update` | 每轮使用情况和成本信息。流式传输可通过以下方式切换： [`usage-toggle`](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#usage-toggle) |
| `指标`           | 流水线性能指标。请参阅 [指标](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/metrics.md)                                                           |

{% hint style="warning" %}
诊断消息载荷不属于稳定 API 范围，可能会在不通知的情况下更改。不要基于它们构建应用逻辑。
{% endhint %}

***

### 相关页面

{% content-ref url="/pages/52997086a1139479d2cbe158e37133880276b547" %}
[消息术语表](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/message-glossary.md)
{% endcontent-ref %}

{% content-ref url="/pages/70d752d330612b0fbf1290588e718236d6a18f0e" %}
[连接 API](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/connect-api.md)
{% endcontent-ref %}

{% content-ref url="/pages/29ba5f52bd1ff6aac10fb390cafb074f474ab066" %}
[音频数据（通过数据通道）](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/audio-data-via-data-channel.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.