连接 API
为你的 Convai 角色建立一个实时聊天机器人会话，使用户能够通过音频或视频连接并保持对话上下文。
该 Connect API 在终端用户与 Convai 角色之间建立一个实时交互会话。重用返回的 character_session_id 以在连接之间继续对话上下文。
本页上的 Actions 协议 v2 字段描述的是一个可选启用的候选接口面。这里出现它们并不表示生产环境可用或已发布 SDK 版本。请在依赖这些能力之前，先验证目标环境返回的所选能力。
连接到角色
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，不要同时发送。参见 使用多角色会话.
room_brief
字符串
最多 4000 个字符，作为上下文提供给房间中的每个角色，包括之后添加的角色。在创建时固定。仅在与 group_chat: true.
角色行为与上下文
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.
音频、语音和轮次切换
vad_params
JSON
语音活动检测调优： 置信度, start_secs, stop_secs, min_volume.
turn_detection_config
JSON
轮次检测策略覆盖项。
头像与视觉
blendshape_provider
字符串
"not_provided" （默认）， "ovr"，或者 "neurosync"。决定你接收哪类面部动画消息。
blendshape_config
JSON
提供方特定的 blendshape 配置。
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
调用方提供的用于归因和分析的元数据。
字段
actions —— 角色可发出的语义动作名称。接受字符串数组或 { "value": "..." } 对象。Convai 会在通过 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.
字段
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路由
Agentic Actions v2 预览
协议选择彼此独立。只请求你的客户端实现了的行为：
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 可以替换语义动作列表，但不能替换 action_config.tools；要更改工具集，请重新连接。
当请求包含 能力时，响应会报告所选字段：
如果请求省略 能力，响应也会省略它。此时会话使用 action 协议 v1、模型输出 v1 和旧版 bot-llm-text 行为。
响应
最后六个键会出现在每个响应中，并且仅针对名册房间填充。
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 条目；在加入时，则是当时处于活动状态的那个实例，因为 切换活动角色 会改变它。适用于任何 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 的, 说明，以及其中列出的标识符 使用多角色会话。适用于任何 roster 房间，包括一个 mode: "join" 响应； null 用于单角色会话。
重要说明
Convai 严格遵循 OpenAI 的内容政策 用于 API 使用。 用户不得生成或传播有毒、有害或不适当的内容。 重复违规将导致您的 API 密钥被 列入黑名单.
重复使用相同的 character_session_id 以在交互之间保持上下文。新的 character_session_id 会在没有先前对话上下文的情况下启动会话。
示例请求
连接后
使用以下方式加入房间 room_url 和 token。从那一刻起，会话完全由 WebRTC 数据通道上的消息以及音频轨道驱动。
Turn 生命周期和消息顺序 — 机器人回合如何传递，以及你可以依赖的顺序
响应契约与解析 — 旧版文本、规范输出、动作和原始文本有何区别
客户端到服务器的消息 — 更新上下文、切换音频、发送文本
服务器到客户端的消息 — 你收到的所有内容的完整字段参考
最后更新于
这有帮助吗？