> 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/connect-api.md). # 连接 API 为你的 Convai 角色建立一个实时聊天机器人会话，使用户能够通过音频或视频连接并保持对话上下文。 该 **连接 API** 在终端用户和 Convai 角色之间建立实时交互会话。复用返回的 `character_session_id` 以在连接之间继续对话上下文。 {% hint style="warning" %} 本页上的 Actions protocol v2 字段描述的是一种可选启用的候选功能表面。这里出现这些字段并不表示已可用于生产，也不表示已发布 SDK 版本。依赖这些能力之前，请先验证目标环境返回的已选能力。 {% endhint %} ## 连接到角色 `POST` `https://live.convai.com/connect` ### 标头
名称类型说明
X-API-Key*字符串你的 Convai API 密钥。
Content-Type字符串必须设置为 application/json.
*** ### 请求体 单角色会话只需要 `character_id`；其他所有字段都有服务器端默认值。多角色房间会发送 `角色` 以及一个非空的 `end_user_id` 而不是 `character_id`. **会话标识** | 名称 | 类型 | 说明 | | ---------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------- | | `character_id` | 字符串 | 要连接的角色的唯一 ID。单角色会话必填；当你发送 `角色`. | | `connection_type` | 字符串 | 连接模式。 `“audio”` （默认）， `“video”`，或 `"text"`. | | `character_session_id` | 字符串 | 用于保持对话连续性的现有会话 ID。若省略，将生成新的会话 ID。 | | `end_user_id` | 字符串 | 你为终端用户提供的唯一标识符。用于标记会话并启用长期记忆。当你发送 `角色`时必填，以及当你使用 `mode: "join"` 和房间定位器（`room_session_id` 或 `shared_session_key`）加入现有房间而不是角色时也必填。 | | `end_user_metadata` | JSON | 与终端用户关联的任意元数据。会在响应中回传。 | **多角色房间** 多角色房间仅对已启用该功能的账户开放，并且你的账户的角色和参与者限制仍然适用。 | 名称 | 类型 | 说明 | | ------------ | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `角色` | JSON | 有序列表，包含 `{ "character_id", "character_session_id" }` 条目，每个角色实例一条；第一条是初始实例。 `character_id` 是必需的，且必须是裸 UUID； `character_session_id` 是可选的，并会延续该实例之前的对话。发送 `character_id` 或 `角色`中的任意一个，不要同时发送二者。参见 [使用多角色会话](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/multi-character-sessions.md). | | `group_chat` | 布尔值 | 将房间设为群聊模式，在该模式下多个实例会回应同一条消息。默认 `false`。在创建时固定；加入时会继承它。参见 [构建群聊](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/build-a-group-chat.md). | | `room_brief` | 字符串 | 最多 4000 个字符，作为上下文提供给房间中的每个角色，包括之后添加的角色。在创建时固定。仅在 `group_chat: true`. | **角色行为与上下文** | 名称 | 类型 | 说明 | | ------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `action_config` | [JSON](#action_config) | 语义动作能力以及该会话可选的客户端执行工具声明。参见 [响应契约与解析](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/response-contract-and-parsing.md). | | `capabilities` | [JSON](#agentic-actions-v2-preview) | 显式协议选择。省略此字段可保留旧版 v1 响应结构。 | | `dynamic_info` | [JSON](#dynamic-info) | 用于影响对话流程的实时上下文数据。 | | `scene_description` | [JSON](#scene_description) | 当前场景或环境的描述。仅用于描述性上下文—— **不会授予动作能力**. | | `narrative_template_keys` | JSON | 替换到角色提示模板中的键/值对。 | | `emotion_config` | JSON | 情绪检测与表达的配置。 | | `thinking_mode` | 布尔值 | 在响应前启用更长的模型推理。默认 `false`. | | `respond_modes` | JSON | 按模态控制角色何时必须响应。 | **模型与提供方** | 名称 | 类型 | 说明 | | ----------------------- | --- | -------------------------------------------------------------------------- | | `llm_provider` | 字符串 | `“dynamic”` （默认）， `“gemini-live”`, `“gemini-live-beta”`，或 `“gemini-baml”`. | | `stt_provider` | 字符串 | 为此会话覆盖语音转文字提供方。 | | `disable_live_fallback` | 布尔值 | 阻止回退到非实时模型。默认 `true`. | **音频、语音与轮流发言** | 名称 | 类型 | 说明 | | ----------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `audio_config` | [JSON](#audio_config) | 音频输出行为。仅适用于 LiveKit 传输（默认）。 | | `default_tts_enabled` | 布尔值 | 是否在开始时启用机器人音频。默认 `true`。之后可通过 [`tts-toggle`](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#tts-toggle). | | `default_stt_enabled` | 布尔值 | 是否在开始时启用麦克风输入。默认 `true`。之后可通过 [`stt-toggle`](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#stt-toggle). | | `vad_params` | JSON | 语音活动检测调优： `置信度`, `start_secs`, `stop_secs`, `最小音量`. | | `turn_detection_config` | JSON | 轮次检测策略覆盖。 | **头像与视觉** | 名称 | 类型 | 说明 | | --------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `blendshape_provider` | 字符串 | `“not_provided”` （默认）， `“ovr”`，或 `“neurosync”`。决定你会收到哪些面部动画消息。 | | `blendshape_config` | JSON | 提供方特定的 blendshape 配置。 | | `vision_input_config` | JSON | 视觉输入配置，包括采样窗口。启用被 [`vision-status`](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#vision-status) 和 [`vision-trigger`](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#vision-trigger). | | `video_track_name` | 字符串 | 传入视频轨道的名称。默认 `“camera”`. | **多参与者会话** | 名称 | 类型 | 说明 | | ---------------------- | --- | -------------------------------------------------------------- | | `max_num_participants` | 整数 | 房间中 **人类** 参与者的最大数量。默认 `1`。这里不计算角色实例；成员列表大小由 `角色` 设置，并由账户上限限制。 | | `shared_session_key` | 字符串 | 用于确定性地将参与者放入同一房间的分组键。1–128 个字符，字母数字加 `-` 和 `_`. | | `mode` | 字符串 | `“create”` （默认）或 `“join”`. | | `room_name` | 字符串 | 要创建或加入的显式房间名称。 | **诊断** | 名称 | 类型 | 说明 | | --------------------- | ---- | ---------------------------------------------------- | | `调试` | 布尔值 | 启用 RTVI 指标， `turn-trace`，以及 `server-log` 以及数据通道上的消息。 | | `debug_row_cap` | 整数 | 覆盖每个会话的诊断行上限。仅在 `调试` 是 `true`. | | `invocation_metadata` | JSON | 调用方提供的归因与分析元数据。 | {% tabs %} {% tab title="action\_config" %} ```json { "actions": ["Move To", "Pick Up", "Drop", "Follow"], "objects": [ { "name": "cube", "description": "A red cube on the table" }, { "name": "lever", "description": "A metal lever on the wall" } ], "characters": [ { "name": "Player", "bio": "The current user" }, { "name": "Guard", "bio": "A nearby guard" } ], "current_attention_object": "cube" } ``` **字段** **`动作`** — 角色可发出的语义动作名称。可接受字符串数组或 `{ "value": "..." }` 对象。Convai 会在将语义动作名称投射通过之前进行验证 [`action-response`](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#action-response). **`对象`** — `{ name, description }` 条目，用于锚定并验证语义动作目标。 **`角色`** — `{ name, bio }` 条目，用于锚定并验证语义动作目标。 **`current_attention_object`** — 用户当前正在查看或指代的对象名称。用于锚定诸如 *"this"*, *"that"*，以及 *"it"*这样的代词。必须匹配 `objects[].name` 中的某个值。可接受字符串或完整对象。 `动作`, `对象`，以及 `角色` 约束旧版语义动作投射。仅在 `scene_description` 中提到的对象不会成为语义动作目标。客户端执行的 v2 工具使用其自己的 JSON Schema 参数，并且在执行前仍需要客户端侧授权。 整个契约可以在会话期间用 [`上下文更新`](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#context-update). {% endtab %} {% tab title="动态信息" %} ```json { "text": "string" } ``` {% endtab %} {% tab title="scene\_description" %} ```json [ { "name": "string", "description": "string" } ] ``` {% endtab %} {% tab title="audio\_config" %} ```json { "output": { "audio_routing": "audio_only", // 默认: "audio_only" | "data_only" | "both" "max_chunk_duration_ms": 100, // 默认: 100，范围: 10-1000ms "add_wav_header": false // 默认: false } } ``` **字段** **`音频路由`** - 控制音频传递方式： * `"audio_only"` （默认）- 标准 WebRTC 音频轨道（推荐） * `"data_only"` - 通过 `audio-data` 数据通道接收消息，用于自定义处理 * `"both"` - 同时通过音频轨道和数据通道接收 **`max_chunk_duration_ms`** - 音频分块大小（10-1000ms，默认：100ms） * 更低的值 = 更低的延迟，更多开销 * 更高的值 = 更适合不稳定网络 * 向上取整到最接近的 10ms： `95ms → 100ms`, `45ms → 50ms` **`add_wav_header`** - 在数据通道分块中包含 WAV 头（默认：false） * 仅在使用时适用 `data_only` 或 `both` 路由 {% endtab %} {% endtabs %} *** ## Agentic Actions v2 预览 协议选择彼此独立。只请求你的客户端实现了的行为： ```json { "character_id": "CHARACTER_ID", "capabilities": { "action_protocol_version": 2, "model_output_version": 2, "bot_llm_text_mode": "legacy" }, "action_config": { "actions": ["Wave"], "objects": [], "characters": [], "tools": [ { "name": "open_training_record", "description": "在操作员确认记录 ID 后打开培训记录。", "inputSchema": { "type": "object", "properties": { "record_id": { "type": "string" } }, "required": ["record_id"] } } ] } } ``` | 字段 | 取值 | 行为 | | -------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `capabilities.action_protocol_version` | `1` 或 `2` | 版本 `2` 启用相关联的客户端工具调用以及 [`action-result`](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#action-result). | | `capabilities.model_output_version` | `1` 或 `2` | 版本 `2` 启用规范的 [`model-output`](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#model-output) 消息。 | | `capabilities.bot_llm_text_mode` | `"legacy"` 或 `"raw"` | `"legacy"` 保留过滤后的聊天投影。 `"raw"` 通过 `bot-llm-text`流式传输提供方可见文本；切勿在未经应用审查的情况下执行或说出此流。 | | `action_config.tools` | 工具声明数组 | 声明可由客户端而非 Convai 执行的工具，但前提是要在验证每次调用后执行。需要 action protocol v2。 | 每个工具声明都需要 `name`, `描述`，以及一个以对象为根的 `inputSchema`。根模式接受 `type`, `properties`，以及 `必填`；可以在属性模式中使用受支持的验证关键字。工具名称必须唯一，必须以字母或下划线开头，并且可以包含字母、数字、下划线或连字符。 候选实现强制执行以下限制： | 限制 | 值 | | -------- | ---------- | | 每个连接的工具数 | `32` | | 工具名称 | `64` 角色 | | 工具描述 | `1,024` 角色 | | 序列化输入模式 | `16 KiB` | | 输入模式嵌套深度 | `8` | 任何 v2 动作选择、v2 模型输出选择或 raw `bot-llm-text` 选择都需要 `mode: "create"`，一个单一的 `character_id`时，不会发送 `shared_session_key`，以及 `max_num_participants: 1`。已加入、名册、共享会话以及多参与者拓扑会被拒绝。 角色的显式 **启用智能体操作** 设置仍然是权威来源。当它关闭时，Convai 不会把 Actions 契约、语义动作工具或客户端工具模式添加到模型中。当该设置缺失时，若某个角色保存了一个或多个旧版 Character Actions，则该角色会继承启用状态，适用于模型输出 v1 和 v2；若角色没有保存的旧版动作，则默认对模型输出 v2 关闭。读取这种继承状态不会持久化新的设置。即使 Actions 关闭，仍然可以发出仅文本的模型输出 v2。 客户端工具还需要一个支持提供方原生函数调用的已解析模型。仅仅完成能力协商并不授权某个工具，也不能保证所选模型可以调用它。 工具声明是按连接范围生效的。一个 [`上下文更新`](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#context-update) 可以替换语义动作列表，但它不能替换 `action_config.tools`；要更改工具集，请重新连接。 当请求包含 `capabilities`时，响应会报告所选字段： ```json { "capabilities": { "action_protocol_version": 2, "model_output_version": 2, "bot_llm_text_mode": "legacy" } } ``` 如果请求省略 `capabilities`，响应也会省略它。此时会话使用动作协议 v1、模型输出 v1，以及旧版 `bot-llm-text` 行为。 *** ### 响应 {% tabs %} {% tab title="200：成功。与你角色对应的 webrtc 房间已创建。" %} ```json { "session_id": "<你在实时会话中的临时会话 id>", "request_trace_id": "<此 /connect 请求的服务器端跟踪 id>", "character_session_id": "<你的会话 id。若为新会话，则返回新生成的值；否则返回旧值>", "room_url": "<你的客户端需要加入的房间 URL>", "room_name": "<要加入的房间名称>", "token": "<用于让客户端加入房间的令牌>", "end_user_id": "<会话中用户的 end_user_id；如果请求中未发送则为 null>", "end_user_metadata": "<与终端用户关联的元数据；如果请求中未发送则为 null>", "room_session_id": null, "active_membership_id": null, "route_epoch": null, "roster_epoch": null, "partial_dispatch": false, "characters": null } ``` 最后六个键会出现在每个响应中，并且只会为名册房间填充。 | 字段 | 类型 | 说明 | | ---------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `session_id` | 字符串 | 本次实时会话的临时令牌。 | | `request_trace_id` | 字符串 | 服务器端跟踪 ID。请在支持请求中包含它——它会将你的会话与服务器日志、遥测和会话记录关联起来。 | | `character_session_id` | 字符串 | 对话会话 ID。在之后的 `/connect` 中复用它，以继续同一段对话。 | | `room_url` | 字符串 | 你的客户端加入的房间 URL。 | | `room_name` | 字符串 | 房间名称。仅限 LiveKit 传输。 | | `token` | 字符串 | 用于加入房间的认证令牌。 | | `end_user_id` | 字符串 \| null | 从请求中回显。 | | `end_user_metadata` | 对象 \| null | 从请求中回显。 | | `capabilities` | 对象 | 仅当请求显式包含 `capabilities`时存在。包含服务器选择的协议字段。 | | `room_session_id` | 字符串 \| null | 标识房间；会随每个房间命令一起发送。适用于任何名册房间，包括 `mode: "join"` 响应； `null` 用于单角色会话。 | | `active_membership_id` | 字符串 \| null | 当前正在接收用户轮次的角色实例。在创建时，这是第一个 `角色` 条目；在加入时，它是当时处于活动状态的那个实例，因为 [切换活动角色](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/multi-character-sessions.md#switch-the-active-character) 会改变它。适用于任何名册房间； `null` 用于单角色会话。 | | `route_epoch` | 整数 \| null | 发送为 `expected_route_epoch` 用于第一条房间命令。适用于任何名册房间，包括 `mode: "join"` 响应； `null` 用于单角色会话。 | | `roster_epoch` | 整数 \| null | 发送为 `expected_roster_epoch` 用于第一条 `character-roster-update`。适用于任何名册房间，包括 `mode: "join"` 响应； `null` 用于单角色会话。 | | `partial_dispatch` | 布尔值 | `true` 如果任何角色实例启动失败。始终 `false` 用于单角色会话。 | | `角色` | 数组 \| null | 每个角色实例一条： `membership_id`, `session_id`, `is_initial`, `provisioning_status`, `failure_code`, `display_name`, `描述`，以及在 [使用多角色会话](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/multi-character-sessions.md#map-each-character-instance)。适用于任何名册房间，包括 `mode: "join"` 响应； `null` 用于单角色会话。 | | {% endtab %} | | | {% tab title="404：未找到。请求的响应生成失败" %} ```json { "detail": "找不到角色或该角色不属于该用户" } ``` {% endtab %} {% tab title="422：请求错误时" %} ```json { "detail": [ { "type": "<请求正文问题的类型>", "loc": [], "msg": "<消息>", "input": "<输入值>", "ctx": { "error": "关于该错误的更多细节" } } ] } ``` {% endtab %} {% endtabs %} *** ## 重要说明 {% hint style="warning" %} Convai 严格遵循 **OpenAI 的内容政策** 用于 API 使用。\ 用户不得生成或分发有毒、有害或不当内容。\ 重复违规将导致你的 API 密钥被 **已列入黑名单**. {% endhint %} 重用相同的 `character_session_id` 以在交互之间保持上下文。新的 `character_session_id` 会在没有先前对话上下文的情况下启动会话。 *** ## 示例请求 {% tabs %} {% tab title="Python" %} ```python import requests url = "https://live.convai.com/connect" headers = { "Content-Type": "application/json", "X-API-Key": "" # 替换为您的实际 Convai API 密钥 } data = { "character_id": "", "connection_type": "audio", # 或 "video" "character_session_id": "string" # 可选 ## 如需指定场景描述 ## "scene_description": [ ## { ## "name": "string", ## "description": "string" ## } ## ], ##如果需要指定动态信息 ## "dynamic_info": { ## "text": "string" ## }, } response = requests.post(url, headers=headers, json=data) print("Status Code:", response.status_code) print("Response:", response.text) ``` {% endtab %} {% tab title="cURL" %} ```shell curl --location 'https://live.convai.com/connect' \ --header 'Content-Type: application/json' \ --header 'X-API-Key: ' \ --data '{ "character_id": "", "connection_type": "audio", // 或 "video" 用于视频功能 "character_session_id": "string" // 可选 "dynamic_info": { // 可选 "text": "string" }, "scene_description": [ { "name": "string", "description": "string" } ], // 可选 }' ``` {% endtab %} {% endtabs %} *** ## 连接后 使用以下方式加入房间 `room_url` 和 `token`。从那一刻起，会话完全由 WebRTC 数据通道上的消息以及音频轨道驱动。 * [回合生命周期和消息顺序](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/turn-lifecycle-and-message-ordering.md) — 机器人回合如何传递，以及您可以依赖的顺序 * [响应契约与解析](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/response-contract-and-parsing.md) — 旧版文本、规范输出、动作和原始文本有何区别 * [客户端到服务器的消息](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md) — 更新上下文、切换音频、发送文本 * [服务器到客户端的消息](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md) — 您收到的所有内容的完整字段参考 --- # 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/connect-api.md?ask=&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.