连接 API

为你的 Convai 角色建立一个实时聊天机器人会话，使用户能够通过音频或视频连接并保持对话上下文。

概述

该 Connect API 在最终用户与 Convai 角色之间建立实时交互会话。 它允许开发者使用 character_session_id 在每个响应中返回，并支持两种 音频 是位于 视频 连接。 可选地，可以包含场景描述或动态信息以定制交互。

连接到角色

POST https://live.convai.com/connect

请求头

名称	类型	说明
X-API-Key*	字符串	你的 Convai API 密钥。
Content-Type	字符串	必须设置为 application/json.

---

请求体

名称	类型	说明
character_id*	字符串	要连接的角色的唯一 ID。
connection_type	字符串	会话的连接模式。 支持的值： “audio” （默认）或 “video”.
character_session_id	字符串	用于保持对话连续性的现有会话 ID。如省略，将生成一个新的。
dynamic_info	JSON	用于影响对话流程的实时上下文数据。
scene_description	JSON	当前场景或环境上下文的描述。
end_user_id	字符串	用户管理的唯一标识符，用于标记会话并使用长期记忆
debug	布尔	在数据通道上启用 RTVI 指标。
音频配置	JSON	音频输出行为的配置。仅支持 LiveKit 传输（默认）。

动态信息

{
    "text": "string"
}

scene_description

音频配置

---

响应

200：OK，你与角色的 WebRTC 房间已创建。

{
  "session_id": "<你在实时会话中的临时会话 id>",
  "character_session_id": "<你的会话 id。若是新会话，则返回新生成的值，或返回旧值>",
  "room_url": "<客户端需要加入的房间 URL>",
  "room_name": "<要加入的房间名称>",
  "token": "<客户端加入房间的令牌>",
  "end_user_id": "<会话中用户的 end_user_id，若请求中未发送则为 null>"
}

404：未找到，响应生成失败，无法处理请求

422：请求有误时

---

重要说明

Convai 严格遵循 OpenAI 的内容政策 用于 API 使用。 用户不得生成或传播有毒、有害或不适当的内容。 重复违规将导致你的 API 密钥被 列入黑名单.

始终复用同一个 character_session_id 如果你想 保持上下文 在交互之间。

一个新的 character_session_id 会创建一个 全新的会话 而没有先前上下文。

---

示例请求

Python

import requests

url = "https://live.convai.com/connect"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "<你的 api 密钥>"  # 替换为你实际的 Convai API 密钥
}

data = {
    "character_id": "<你的角色 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)

cURL

---

结论

该 Connect API 是将 Convai 的实时对话能力集成到你的应用中的关键组件。 通过维护会话上下文并动态调整场景或角色信息，开发者可以构建由 Convai 驱动的无缝、上下文感知语音或视频交互。