> 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) 以查看所有消息类型及其信封格式的摘要。

大多数服务器消息都使用在 [`interaction-created`](#interaction-created)下所示的 RTVI 信封格式。后续示例仅显示内部 `data` 有效载荷。 `服务器响应` 使用扁平的旧式结构，而 [机器人输出流](#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`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": "当然，马上就到。" } }
```

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

在省略某些能力或 `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": {} }
```

**建议操作：** 显示和隐藏“thinking”指示器。不要使用 `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-started-speaking / bot-stopped-speaking

标记机器人轮次的音频边界。这些消息使用 `server-message` 信封，并且还会重复 `label` 在 `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
  }
}
```

| 字段                  | 类型  | Presence | 说明                |
| ------------------- | --- | -------- | ----------------- |
| `label`             | 字符串 | 始终可用     | 始终可用 `"rtvi-ai"`  |
| `response_id`       | 字符串 | 仅在设置时    | 此机器人回复的标识符        |
| `neurosync_turn_id` | 整数  | 仅在设置时    | NeuroSync 轮次标识符   |
| `epoch`             | 整数  | 仅在设置时    | NeuroSync 连接/会话纪元 |
| `sequence`          | 整数  | 仅在设置时    | 每轮消息序号            |

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

***

### 确认

#### 服务器响应

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

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

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

**状态值**

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

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

| `event_type`        | `extras` 字段                                                                                                                                                                              |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `context-update`    | `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`        | `enabled`                                                                                                                                                                                |
| `stt-toggle`        | `muted`                                                                                                                                                                                  |
| `usage-toggle`      | `enabled`                                                                                                                                                                                |
| `trigger-message`   | `trigger_name`, `has_speak_tag`                                                                                                                                                          |
| `user_text_message` | `文本`                                                                                                                                                                                     |
| `action-result`     | `tool_call_id`, `幂等`；错误还包括 `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` 字段 `服务器响应`。处理 `"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` 有效载荷**

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

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

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

***

#### 达到使用上限

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

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

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

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

***

#### bot-turn-completed

当机器人到达终止轮次状态时发送：它已说完、被用户中断，或因无法交付所需输出而中止。

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

| 字段                | 类型  | 说明                                         |
| ----------------- | --- | ------------------------------------------ |
| `type`            | 字符串 | 始终可用 `"bot-turn-completed"`                |
| `was_interrupted` | 布尔值 | `是` 如果用户中断了机器人； `否` 如果该轮正常完成               |
| `was_aborted`     | 布尔值 | 可选。 `是` 如果该轮因无法交付所需的机器人输出而结束               |
| `error_reason`    | 字符串 | 可选。机器可读的中止原因；当前为 `"audio_delivery_failed"` |

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

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

***

#### user-idle-warning

当用户在设定时间内处于空闲时发送，提醒即将断开连接。

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

| 字段                  | 类型          | 说明                         |
| ------------------- | ----------- | -------------------------- |
| `type`              | 字符串         | 始终可用 `"user-idle-warning"` |
| `remaining_seconds` | 整数          | 连接断开前剩余的秒数                 |
| `message`           | 字符串 \| 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`   | 字符串         | 始终可用 `"llm-no-response"`      |
| `reason` | 字符串 \| 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`           | 字符串         | 始终可用 `"final-user-transcription"` |
| `文本`             | 字符串         | 转录文本                              |
| `speaker_id`     | 字符串 \| null | 说话者标识符                            |
| `speaker_name`   | 字符串 \| null | 说话者显示名称                           |
| `participant_id` | 字符串 \| null | 参与者标识符                            |

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

***

#### moderation-response

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

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

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

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

***

#### behavior-tree-response

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

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

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

***

### 规范化模型输出

#### 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`            | 字符串   | 始终可用 `"model-output"`.                                                                      |
| `版本`              | 整数    | 始终可用 `2`.                                                                                   |
| `output_id`       | 字符串   | 信封标识符。通过此字段去重重复传递。                                                                          |
| `logical_turn_id` | 字符串   | 可选的相关 ID，由同一逻辑轮次的输出信封共享。存在的值最多为 `128` UTF-8 字节。                                             |
| `format`          | 字符串   | `"text"`, `"convai-combined-json"`, `"semantic-actions-json"`，或 `"client-tool-calls-json"`. |
| `raw`             | 字符串   | 为诊断保留的精确提供方或运行时输出。切勿将此字段作为可信内容执行或渲染。                                                        |
| `items`           | 对象\[] | Convai 验证过的语义项。                                                                             |
| `final`           | 布尔值   | 始终可用 `是` 对于这个已完成的信封。它并不意味着之后不会有另一个信封共享相同的 `logical_turn_id`.                                |

| 条目 `type`         | 字段                             | 含义                                                                                                                                             |
| ----------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `message`         | `role`, `channel`, `content`   | 助手文本，用于 `"final"` 或 `"commentary"`.                                                                                                            |
| `semantic_action` | `ID`, `名称`, `目标`               | 已解析的语义动作。 `目标` 可能是 `null`.                                                                                                                     |
| `工具调用`            | `ID`, `名称`, `目标`, `arguments`  | 关联的客户端工具调用。返回 [`action-result`](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#action-result) 其 `ID`. |
| `情绪`              | `名称`, `强度`                     | 带强度级别的情绪 `1`, `2`，或 `3`.                                                                                                                       |
| `扩展`              | `模式`, `版本`, `有效载荷`, `fallback` | 带模式版本的扩展项。此预览未定义显示或快速响应扩展模式。                                                                                                                   |

当前生产者会发出最终通道消息、语义动作、客户端工具调用和情绪。评论通道消息和 `扩展` 这些项由候选协议和解析器表示，但当前运行时不会生成它们。

多个信封可以共享一个 `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": "动作响应",
  "actions": [
    { "name": "移动到", "target": "立方体" },
    { "name": "挥手" }
  ]
}
```

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

旧版语义动作使用 `{ 名称, 目标? }`。Convai 会在发出前根据会话能力校验语义动作名称以及任何非空目标。

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

```json
{
  "type": "动作响应",
  "actions": [
    {
      "kind": "工具调用",
      "id": "call_abc123",
      "name": "open_training_record",
      "arguments": {
        "record_id": "record-42"
      }
    }
  ]
}
```

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

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

***

### 动画与口型同步

#### bot-emotion

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

```json
{
  "type": "机器人情绪",
  "emotion": "高兴",
  "scale": 2
}
```

| 字段     | 类型  | 说明                                      |
| ------ | --- | --------------------------------------- |
| `type` | 字符串 | 始终可用 `"机器人情绪"`                          |
| `情绪`   | 字符串 | 情绪名称，例如 `"快乐"`, `"悲伤"`, `"兴奋"`，或 `"愤怒"` |
| `强度`   | 整数  | 强度级别： `1` = 轻微， `2` = 中等， `3` = 强烈      |

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

***

#### 口型素

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

```json
{
  "type": "口型素",
  "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` | 字符串 | 始终可用 `"口型素"`              |
| `口型素`  | 对象  | 口型素键到混合权重的映射（`0.0`–`1.0`) |

**口型素键**

| 键     | 音素        |
| ----- | --------- |
| `sil` | 静音        |
| `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`        | 字符串      | 始终可用 `"neurosync-blendshapes"`    |
| `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`        | 字符串         | 始终可用 `"chunked-neurosync-blendshapes"` |
| `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": "中断"
}
```

| 字段                          | 类型      | 说明                                     |
| --------------------------- | ------- | -------------------------------------- |
| `response_id`               | 字符串     | 要取消的生命周期响应标识符                          |
| `neurosync_turn_id`         | 整数      | 要取消的 NeuroSync 轮次标识符                   |
| `epoch`                     | 整数      | NeuroSync 连接/会话纪元                      |
| `sequence`                  | 整数      | 每轮消息序列                                 |
| `valid_through_frame_index` | 整数 \| 空 | 由已释放音频支持的包含式最后帧索引。省略时或 `null`，立即丢弃所属者的 |
| `reason`                    | 字符串     | 取消原因，例如 `"中断"`                         |

**建议操作：** 让消息中标识的所属者的缓冲混合形状失效。

* 如果 `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`                          | 字符串   | 始终可用 `"blendshape-turn-stats"` |
| `stats.total_blendshapes`       | 整数    | 该轮中生成的混合形状帧总数                  |
| `stats.total_audio_bytes`       | 整数    | 音频数据总大小（字节）                    |
| `stats.total_turn_duration_ms`  | float | 该轮总时长（毫秒）                      |
| `stats.total_audio_duration_ms` | float | 音频总时长（毫秒）                      |
| `stats.fps`                     | float | 每秒混合形状帧数                       |
| `stats.was_interrupted`         | 布尔值   | `是` 如果该轮在完成前被中断                |

***

### 音频

#### audio-data

当音频通过数据通道路由而不是（或除了）标准 WebRTC 音频轨道时发送。此消息仅在 `audio_routing` 设置为 `"仅数据"` 或 `"both"` 的 `audio_config` 中的 `/connect` 请求。

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

| 字段                    | 类型  | 说明                                       |
| --------------------- | --- | ---------------------------------------- |
| `type`                | 字符串 | 始终可用 `"audio-data"`                      |
| `采样率`                 | 整数  | 音频采样率（Hz），例如 `16000`, `24000`，或 `48000`  |
| `声道`                  | 整数  | 音频声道数： `1` = 单声道， `2` = 立体声              |
| `音频`                  | 字符串 | Base64 编码的音频数据（原始 PCM 或带头部的 WAV）         |
| `includes_wav_header` | 布尔值 | `是` 如果音频载荷包含 44 字节的 WAV 头部； `否` 对于原始 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
}
```

| 字段            | 类型  | 说明                                       |
| ------------- | --- | ---------------------------------------- |
| `时间戳`         | 字符串 | STT 取消静音时的 ISO 8601 时间戳                  |
| `pre_roll_ms` | 整数  | 已捕获的音频量 *在……之前* 被预先添加到流中的语音检测内容，以免遗漏任何内容 |

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

***

#### vad-stt-stopped

拖尾期结束后，STT 服务已被静音。

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

| 字段                  | 类型      | 说明                     |
| ------------------- | ------- | ---------------------- |
| `时间戳`               | 字符串     | STT 被静音时的 ISO 8601 时间戳 |
| `reason`            | 字符串     | 转写停止的原因，例如 `"拖尾期已结束"`  |
| `audio_duration_ms` | 整数 \| 空 | 此片段中处理的音频总量            |

**建议操作：** 移除“正在聆听”指示器。

***

#### vad-stt-debug

详细的 VAD 状态变化、语音检测和静音检测事件。仅在会话以 `debug: true` 并启用了调试事件时发出。负载结构会因事件而异，旨在用于诊断而非应用逻辑。

***

### 诊断

这些消息仅在会话以 `debug: true`.

| 消息             | 用途                                                                                                                                   |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
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=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.