> 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).

# Connect API

## 概述

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

## 连接到角色

<mark style="color:绿色;">`POST`</mark> `https://live.convai.com/connect`

### 请求头

<table><thead><tr><th width="199">名称</th><th width="108.9998779296875">类型</th><th>说明</th></tr></thead><tbody><tr><td>X-API-Key<mark style="color:红色;">*</mark></td><td>字符串</td><td>你的 Convai API 密钥。</td></tr><tr><td>Content-Type</td><td>字符串</td><td>必须设置为 <code>application/json</code>.</td></tr></tbody></table>

***

### 请求体

<table><thead><tr><th width="203.6666259765625">名称</th><th width="104">类型</th><th>说明</th></tr></thead><tbody><tr><td>character_id<mark style="color:红色;">*</mark></td><td>字符串</td><td>要连接的角色的唯一 ID。</td></tr><tr><td>connection_type</td><td>字符串</td><td><p>会话的连接模式。</p><p>支持的值： <code>“audio”</code> （默认）或 <code>“video”</code>.</p></td></tr><tr><td>character_session_id</td><td>字符串</td><td>用于保持对话连续性的现有会话 ID。如省略，将生成一个新的。</td></tr><tr><td>dynamic_info</td><td><a href="#dynamic-info">JSON</a></td><td>用于影响对话流程的实时上下文数据。</td></tr><tr><td>scene_description</td><td><a href="#scene_description">JSON</a></td><td>当前场景或环境上下文的描述。</td></tr><tr><td>end_user_id</td><td>字符串</td><td>用户管理的唯一标识符，用于标记会话并使用长期记忆</td></tr><tr><td>debug</td><td>布尔</td><td>在数据通道上启用 RTVI 指标。</td></tr><tr><td>音频配置</td><td><a href="#audio_config">JSON</a></td><td>音频输出行为的配置。仅支持 LiveKit 传输（默认）。</td></tr></tbody></table>

{% tabs %}
{% tab title="动态信息" %}

```json
{
    "text": "string"
}
```

{% endtab %}

{% tab title="scene\_description" %}

```json
[
  {
    "name": "string",
    "description": "string"
  }
]
```

{% endtab %}

{% tab title="音频配置" %}

```json
{
  "output": {
    "audio_routing": "audio_only", // 默认："audio_only" | "data_only" | "both"
    "max_chunk_duration_ms": 100, // 默认：100，范围：10-1000 毫秒
    "add_wav_header": false // 默认：false
  }
}
```

#### 字段 <a href="#fields-24" id="fields-24"></a>

**`音频路由`** - 控制音频传送方式：

* `"audio_only"` （默认）- 标准 WebRTC 音频轨道（推荐）
* `"data_only"` - 通过数据通道接收 `音频数据` 消息以进行自定义处理
* `"both"` - 同时通过音频轨道和数据通道接收

**`max_chunk_duration_ms`** - 音频分块大小（10-1000 毫秒，默认：100 毫秒）

* 值越低 = 延迟越低，开销越大
* 值越高 = 更适合不稳定的网络
* 四舍五入到最接近的 10 毫秒： `95 毫秒 → 100 毫秒`, `45 毫秒 → 50 毫秒`

**`add_wav_header`** - 在数据通道分块中包含 WAV 头（默认：false）

* 仅在使用时适用 `data_only` 或 `both` 路由
  {% endtab %}
  {% endtabs %}

***

### 响应

{% tabs %}
{% tab title="200：OK，你与角色的 WebRTC 房间已创建。" %}

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

{% hint style="info" %}
始终复用同一个 **character\_session\_id** 如果你想 **保持上下文** 在交互之间。
{% endhint %}

{% hint style="info" %}
一个新的 **character\_session\_id** 会创建一个 **全新的会话** 而没有先前上下文。
{% endhint %}

***

## 示例请求

{% tabs %}
{% tab title="Python" %}

```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)
```

{% endtab %}

{% tab title="cURL" %}

```shell
curl --location 'https://live.convai.com/connect' \\
--header 'Content-Type: application/json' \\
--header 'X-API-Key: <你的 api 密钥>' \\
--data '{
    "character_id": "<你的角色 id>",
    "connection_type": "audio", // 或用于视频功能的 "video"
    "character_session_id": "string" // 可选
    "dynamic_info": { // 可选
        "text": "string"
    },
    "scene_description": [
        {
            "name": "string",
            "description": "string"
        }
    ], // 可选
}'
```

{% endtab %}
{% endtabs %}

***

## 结论

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


---

# 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:

```
GET https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/connect-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.