交互 API（Beta）

使用 Convai 的交互 API 启用实时对话式 AI。向你的 AI 角色发送文本消息，并通过服务器发送事件（SSE）接收自然、流式的回复。

此 API 仅适用于专业版及以上套餐。

概述

该 交互式 API 通过轻量级的 REST + SSE 接口。\n它允许你的应用向用户发送消息，并以最低延迟接收流式字符响应。

此 API 通过会话 ID 支持连续对话上下文，并将所有输出流式传输为 服务器发送事件（SSE） 以提供流畅的实时反馈。

---

身份验证

所有 API 请求都需要在请求头中使用 API 密钥进行身份验证：

X-API-Key: your_api_key_here

---

端点

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

向 AI 角色发送文本查询并接收流式响应。

请求格式： multipart/form-data

参数	类型	说明
character_id*	UUID	AI 角色的唯一标识符
text_input*	string	你发送给角色的文本查询/消息
character_session_id	string	用于继续现有对话的会话 ID

示例请求

cURL

curl -X POST https://live.convai.com/connect/stream \\
  -H "X-API-Key: YOUR_API_KEY" \\
  -F "character_id=7bd3274c-1745-11ee-a3af-42010a400002" \\
  -F "text_input=Hello, how are you?" \\
  --no-buffer

Python

import httpx
import json

async with httpx.AsyncClient(timeout=30.0) as client:
    async with client.stream(
        'POST',
        'https://live.convai.com/connect/stream',
        headers={'X-API-Key': 'YOUR_API_KEY'},
        data={
            'character_id': '7bd3274c-1745-11ee-a3af-42010a400002',
            'text_input': 'Hello, how are you?'
        }
    ) as response:
        async for line in response.aiter_lines():
            if line.startswith('data: '):
                data = json.loads(line[6:])
                if data.get('type') == 'bot-llm-text':
                    print(data['data']['text'], end='', flush=True)

JavaScript

const formData = new FormData();
formData.append('character_id', '7bd3274c-1745-11ee-a3af-42010a400002');
formData.append('text_input', 'Hello, how are you?');

const response = await fetch('https://live.convai.com/connect/stream', {
  method: 'POST',
  headers: { 'X-API-Key': 'YOUR_API_KEY' },
  body: formData,
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split('\\n');

  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = JSON.parse(line.slice(6));
      if (data.type === 'bot-llm-text') {
        console.log(data.data.text);
      }
    }
  }
}

响应： 服务器发送事件（SSE）流

data: {"type": "connection-started", "message": {"session_id": "abc123", "transport": "sse", "character_session_id": "def456"}}

data: {"label": "rtvi-ai", "type": "bot-llm-started"}

data: {"label": "rtvi-ai", "type": "bot-llm-text", "data": {"text": "你好"}}

data: {"label": "rtvi-ai", "type": "bot-llm-text", "data": {"text": "！我很好，谢谢你的关心。"}}

data: {"label": "rtvi-ai", "type": "bot-transcription", "data": {"text": "你好！我很好，谢谢你的关心。"}}

data: {"label": "rtvi-ai", "type": "bot-llm-stopped"}

data: {"type": "connection-stoppped"}

---

重要提示

• 请求体必须是 multipart/form-data 格式。使用 -F 在 cURL 中使用 -F 标志（而不是 -d).
• 省略 character_session_id 以开始新对话。添加它以继续现有对话。
• 角色会话 ID 是字符串。请勿发送 -1 或其他占位值。
• 响应通过服务器发送事件（SSE）流式传输。请将超时设置为 30 秒以上。
• 所有交互均受内容审核政策约束。重复违规可能导致 API 密钥被暂停。
• 每个 API 密钥都有速率限制。对于速率限制错误，请实现指数退避。

继续对话

为保持对话上下文，请保存 character_session_id 首次响应中的内容，并在后续请求中包含它。

示例请求

cURL

首次请求：

curl -X POST https://live.convai.com/connect/stream \\
  -H "X-API-Key: YOUR_API_KEY" \\
  -F "character_id=7bd3274c-1745-11ee-a3af-42010a400002" \\
  -F "text_input=My name is Alice" \\
  --no-buffer

响应包括：

{"type": "connection-started", "message": {"character_session_id": "9a98ab9b-5a6c-406e-9721-cc5bb0d527bb", ...}}

第二次请求（带会话 ID）：

curl -X POST https://live.convai.com/connect/stream \\
  -H "X-API-Key: YOUR_API_KEY" \\
  -F "character_id=7bd3274c-1745-11ee-a3af-42010a400002" \\
  -F "text_input=What is my name?" \\
  -F "character_session_id=9a98ab9b-5a6c-406e-9721-cc5bb0d527bb" \\
  --no-buffer

机器人记得： “你的名字是 Alice。”

Python

import httpx
import json
import asyncio

session_id = None

async def chat(message):
    global session_id

    data = {
        'character_id': '7bd3274c-1745-11ee-a3af-42010a400002',
        'text_input': message,
    }

    if session_id:
        data['character_session_id'] = session_id

    async with httpx.AsyncClient(timeout=30.0) as client:
        async with client.stream(
            'POST',
            'https://live.convai.com/connect/stream',
            headers={'X-API-Key': 'YOUR_API_KEY'},
            data=data,
        ) as response:
            async for line in response.aiter_lines():
                if line.startswith('data: '):
                    msg = json.loads(line[6:])

                    if msg.get('type') == 'connection-started':
                        session_id = msg['message']['character_session_id']
                    elif msg.get('type') == 'bot-llm-text':
                        print(msg['data']['text'], end='', flush=True)
            print()

# 用法
await chat('My name is Alice')
await chat('What is my name?')  # 机器人记得："Your name is Alice"

JavaScript

let sessionId = null;

async function chat(message) {
  const formData = new FormData();
  formData.append('character_id', '7bd3274c-1745-11ee-a3af-42010a400002');
  formData.append('text_input', message);

  if (sessionId) {
    formData.append('character_session_id', sessionId);
  }

  const response = await fetch('https://live.convai.com/connect/stream', {
    method: 'POST',
    headers: { 'X-API-Key': 'YOUR_API_KEY' },
    body: formData,
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let buffer = '';

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    buffer += decoder.decode(value, { stream: true });
    const lines = buffer.split('\\n');
    buffer = lines.pop();

    for (const line of lines) {
      if (line.startsWith('data: ')) {
        const data = JSON.parse(line.slice(6));

        if (data.type === 'connection-started') {
          sessionId = data.message.character_session_id;
        } else if (data.type === 'bot-llm-text') {
          process.stdout.write(data.data.text);
        }
      }
    }
  }
  console.log();
}

// 用法
await chat('My name is Alice');
await chat('What is my name?');  // 机器人记得："Your name is Alice"

响应消息类型

connection-started

在连接建立时发送。

{
  "type": "connection-started",
  "message": {
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "transport": "sse",
    "character_session_id": "660e8400-e29b-41d4-a716-446655440001"
  }
}

字段：

• session_id：此连接的唯一标识符
• transport：传输类型（始终为 "sse"）
• character_session_id: 保存它以在未来的请求中继续对话

bot-llm-started

在 LLM 开始生成响应时发送。

{
  "label": "rtvi-ai",
  "type": "bot-llm-started"
}

bot-llm-text

机器人响应文本，在生成时按块流式传输。

{
  "label": "rtvi-ai",
  "type": "bot-llm-text",
  "data": {
    "text": "你好呀！"
  }
}

字段：

• text：机器人响应文本的一部分

bot-transcription

机器人响应的完整转录（在所有文本块发送完毕后发送）。

{
  "label": "rtvi-ai",
  "type": "bot-transcription",
  "data": {
    "text": "你好呀！完整的响应文本。"
  }
}

字段：

• text：机器人完整响应文本

bot-llm-stopped

在 LLM 生成完成时发送。

{
  "label": "rtvi-ai",
  "type": "bot-llm-stopped"
}

connection-stoppped

在响应完成且连接即将关闭时发送。

{
  "type": "connection-stoppped"
}

---

错误响应

所有端点都返回标准 HTTP 错误代码：

状态码	说明
400	错误请求 - 参数无效
401	未授权 - API 密钥无效或缺失
404	未找到 - 未找到角色
422	无法处理的实体 - 验证错误
429	请求过多 - 超出速率限制
500	服务器内部错误

错误响应格式：

{
  "detail": "描述出错原因的错误消息"
}

例如：

{
  "detail": "API 密钥无效"
}

结论

该 交互式 API（测试版） 通过文本与您的 Convai 角色进行动态实时通信。\n通过结合流式响应、上下文持久化和基于 SSE 的传输，它提供了适合聊天、游戏和交互式 AI 应用的响应迅速且低延迟的对话体验。