> 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 角色建立一个实时聊天机器人会话，使用户能够通过音频或视频连接并保持对话上下文。 该 **Connect API** 在终端用户与 Convai 角色之间建立一个实时交互会话。重用返回的 `character_session_id` 以在连接之间继续对话上下文。 {% hint style="warning" %} 本页上的 Actions 协议 v2 字段描述的是一个可选启用的候选接口面。这里出现它们并不表示生产环境可用或已发布 SDK 版本。请在依赖这些能力之前，先验证目标环境返回的所选能力。 {% endhint %} ## 连接到角色 `POST` `https://live.convai.com/connect` ### 标头
名称输入描述
X-API-Key*字符串你的 Convai API 密钥。
Content-Type字符串必须设置为 application/json.
*** ### 请求体 单角色会话只需要 `character_id`；其他所有字段都有服务器端默认值。多角色房间发送 `characters` 以及一个非空的 `end_user_id` 代替 `character_id`. **会话标识** | 名称 | 输入 | 描述 | | ---------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------- | | `character_id` | 字符串 | 要连接的角色的唯一 ID。单角色会话时必填；当你发送 `characters`. | | `connection_type` | 字符串 | 连接模式。 `"audio"` （默认）， `"video"`，或者 `"text"`. | | `character_session_id` | 字符串 | 用于保持对话连续性的现有会话 ID。若省略，将生成新的。 | | `end_user_id` | 字符串 | 你为终端用户提供的唯一标识符。用于标记会话并启用长期记忆。与发送 `characters`以及加入带有 `mode: "join"` 和房间定位器（`room_session_id` 或 `shared_session_key`）的现有房间时必填，而不是角色。 | | `end_user_metadata` | JSON | 与终端用户相关的任意元数据。会在响应中回传。 | **多角色房间** 多角色房间仅对已启用该功能的账号可用，并且仍受你账号的角色和参与者限制约束。 | 名称 | 输入 | 描述 | | ------------ | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `characters` | JSON | 有序列表，包含 `{ "character_id", "character_session_id" }` 条目，每个角色实例一个；第一项是初始实例。 `character_id` 是必需的，且必须是裸 UUID； `character_session_id` 是可选的，并延续该实例之前的对话。发送其中之一， `character_id` 或 `characters`，不要同时发送。参见 [使用多角色会话](/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). | | `能力` | [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`, `min_volume`. | | `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`。这里不计算角色实例；名册大小由 `characters` 设定，并受账号上限限制。 | | `shared_session_key` | 字符串 | 用于确定性地将参与者放入同一房间的分组键。1–128 个字符，字母数字加 `-` 和 `_`. | | `mode` | 字符串 | `"create"` （默认）或 `"join"`. | | `room_name` | 字符串 | 要创建或加入的显式房间名称。 | **诊断** | 名称 | 输入 | 描述 | | --------------------- | ---- | -------------------------------------------------- | | `debug` | 布尔 | 启用 RTVI 指标， `turn-trace`，并且 `server-log` 数据通道上的消息。 | | `debug_row_cap` | 整数 | 覆盖每个会话的诊断行上限。仅在 `debug` 为 `true`. | | `invocation_metadata` | JSON | 调用方提供的用于归因和分析的元数据。 | {% tabs %} {% tab title="action\_config" %} ```json { "actions": ["Move To", "Pick Up", "Drop", "Follow"], "objects": [ { "name": "cube", "description": "桌上的一个红色立方体" }, { "name": "lever", "description": "墙上的一个金属杠杆" } ], "characters": [ { "name": "Player", "bio": "当前用户" }, { "name": "Guard", "bio": "附近的一名守卫" } ], "current_attention_object": "cube" } ``` **字段** **`actions`** —— 角色可发出的语义动作名称。接受字符串数组或 `{ "value": "..." }` 对象。Convai 会在通过 [`action-response`](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#action-response). **`objects`** —— `{ name, description }` 条目，用于锚定并验证语义动作目标。 **`characters`** —— `{ name, bio }` 条目，用于锚定并验证语义动作目标。 **`current_attention_object`** —— 用户当前正在看或提及的对象名称。为诸如 *"this"*, *"that"*，并且 *"it"*之类的代词提供锚定。必须与以下项之一匹配： `objects[].name` 的值。接受字符串或完整对象。 `actions`, `objects`，并且 `characters` 限制旧版语义动作投射。仅在 `scene_description` 中提及的对象不会成为语义动作目标。客户端执行的 v2 工具使用其自己的 JSON Schema 参数，并且在执行前仍需要客户端侧授权。 整个契约可以在会话中途通过 [`context-update`](/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_routing`** - 控制音频传送方式： * `"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 协议 v2。 | 每个工具声明都需要 `名称`, `说明`，以及一个以对象为根的 `inputSchema`。根模式接受 `type`, `properties`，并且 `required`；支持的校验关键字可用于属性模式内部。工具名称必须唯一，必须以字母或下划线开头，并且可以包含字母、数字、下划线或连字符。 候选实现强制执行以下限制： | 限制 | 值 | | -------- | ------------------ | | 每个连接的工具数 | `32` | | 工具名称 | `64` characters | | 工具描述 | `1,024` characters | | 序列化输入模式 | `16 KiB` | | 输入模式嵌套深度 | `8` | 任何 v2 动作选择、v2 模型输出选择，或原始 `bot-llm-text` 选择都需要 `mode: "create"`，一个单一的 `character_id`，没有 `shared_session_key`，并且 `max_num_participants: 1`。已加入、名册、共享会话和多参与者拓扑都会被拒绝。 角色显式的 **启用 Agentic Actions** 设置仍然具有权威性。当其关闭时，Convai 不会向模型添加 Actions 契约、语义动作工具或客户端工具模式。当该设置缺失时，带有一个或多个已保存旧版 Character Actions 的角色，会继承对模型输出 v1 和 v2 的启用状态；没有已保存旧版动作的角色，默认对模型输出 v2 关闭。读取这个继承状态不会持久化新设置。即使 Actions 关闭，仍然可以发出仅文本的模型输出 v2。 客户端工具还需要一个支持提供方原生函数调用的已解析模型。仅靠能力协商并不授权某个工具，也不能保证所选模型能够调用它。 工具声明是按连接作用域生效的。一个 [`context-update`](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#context-update) 可以替换语义动作列表，但不能替换 `action_config.tools`；要更改工具集，请重新连接。 当请求包含 `能力`时，响应会报告所选字段： ```json { "capabilities": { "action_protocol_version": 2, "model_output_version": 2, "bot_llm_text_mode": "legacy" } } ``` 如果请求省略 `能力`，响应也会省略它。此时会话使用 action 协议 v1、模型输出 v1 和旧版 `bot-llm-text` 行为。 *** ### 响应 {% tabs %} {% tab title="200：成功 你的角色对应的 webrtc 房间已创建。" %} ```json { "session_id": "<实时会话的临时会话 id>", "request_trace_id": "<此 /connect 请求的服务器端 trace 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` | 字符串 | 服务器端 trace ID。请在支持请求中包含它——它会将你的会话与服务器日志、遥测和会话记录关联起来。 | | `character_session_id` | 字符串 | 对话会话 ID。稍后在 `/connect` 中重用它，以继续同一段对话。 | | `room_url` | 字符串 | 你的客户端加入的房间 URL。 | | `room_name` | 字符串 | 房间名称。仅适用于 LiveKit 传输。 | | `token` | 字符串 | 用于加入房间的身份验证令牌。 | | `end_user_id` | 字符串 \| null | 从请求中回显。 | | `end_user_metadata` | 对象 \| null | 从请求中回显。 | | `能力` | 对象 | 仅在请求显式包含时才存在 `能力`。包含服务器选择的协议字段。 | | `room_session_id` | 字符串 \| null | 标识该房间；随每个房间命令发送。适用于任何名册房间，包括一个 `mode: "join"` 响应； `null` 用于单角色会话。 | | `active_membership_id` | 字符串 \| null | 当前接收用户轮次的角色实例。在创建时，这是第一个 `characters` 条目；在加入时，则是当时处于活动状态的那个实例，因为 [切换活动角色](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/multi-character-sessions.md#switch-the-active-character) 会改变它。适用于任何 roster 房间； `null` 用于单角色会话。 | | `route_epoch` | 整数 \| null | 发送为 `expected_route_epoch` 在第一个房间命令中。适用于任何 roster 房间，包括一个 `mode: "join"` 响应； `null` 用于单角色会话。 | | `roster_epoch` | 整数 \| null | 发送为 `expected_roster_epoch` 在第一个 `character-roster-update`。适用于任何 roster 房间，包括一个 `mode: "join"` 响应； `null` 用于单角色会话。 | | `partial_dispatch` | 布尔 | `true` 如果有任何角色实例启动失败。始终 `false` 用于单角色会话。 | | `characters` | 数组 \| null | 每个角色实例一条记录： `membership_id`, `session_id`, `is_initial`, `provisioning_status`, `failure_code`, `：即要显示给该实例的名称。该字段尽力提供；若不存在，则回退到该 membership 的`, `说明`，以及其中列出的标识符 [使用多角色会话](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/multi-character-sessions.md#map-each-character-instance)。适用于任何 roster 房间，包括一个 `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("状态码:", response.status_code) print("响应:", 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 数据通道上的消息以及音频轨道驱动。 * [Turn 生命周期和消息顺序](/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 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/connect-api.md?ask=&goal= ``` `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.