AI-VideoAssistant/docs/content/api-reference/index.md

API 参考

本节提供 Realtime Agent Studio (RAS) 的完整 API 文档。

API 概览

Realtime Agent Studio (RAS) 提供两种类型的 API：

API 类型	用途	协议
REST API	管理助手、模型、知识库等资源	HTTP
WebSocket API	实时语音对话	WebSocket

REST API

基础地址

http://localhost:8000/api/v1

认证

REST API 使用 Bearer Token 认证：

curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost:8000/api/v1/assistants

通用响应格式

成功响应

{
  "success": true,
  "data": { ... }
}

列表响应

{
  "success": true,
  "data": {
    "items": [...],
    "total": 100,
    "page": 1,
    "page_size": 20
  }
}

错误响应

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "错误描述"
  }
}

主要端点

助手管理

方法	路径	说明
GET	/assistants	获取助手列表
POST	/assistants	创建助手
GET	/assistants/{id}	获取助手详情
PUT	/assistants/{id}	更新助手
DELETE	/assistants/{id}	删除助手
GET	/assistants/{id}/config	获取引擎配置
GET	/assistants/{id}/opener-audio	获取开场音频状态
POST	/assistants/{id}/opener-audio/generate	生成开场音频

模型管理

方法	路径	说明
GET	/llm	获取 LLM 模型列表
POST	/llm	添加 LLM 模型
PUT	/llm/{id}	更新 LLM 模型
DELETE	/llm/{id}	删除 LLM 模型
POST	/llm/{id}/test	测试 LLM 连接
POST	/llm/{id}/preview	预览模型输出
GET	/asr	获取 ASR 模型列表
POST	/asr	添加 ASR 模型
PUT	/asr/{id}	更新 ASR 模型
DELETE	/asr/{id}	删除 ASR 模型
POST	/asr/{id}/test	测试 ASR 连接
POST	/asr/{id}/preview	上传音频预览识别
GET	/voices	获取语音列表
POST	/voices	添加语音配置
PUT	/voices/{id}	更新语音配置
DELETE	/voices/{id}	删除语音配置
POST	/voices/{id}/preview	预览声音

知识库管理

方法	路径	说明
GET	/knowledge/bases	获取知识库列表
POST	/knowledge/bases	创建知识库
PUT	/knowledge/bases/{id}	更新知识库
DELETE	/knowledge/bases/{id}	删除知识库
POST	/knowledge/bases/{id}/documents	上传文档
POST	/knowledge/bases/{id}/documents/{doc_id}/index	索引文档内容
DELETE	/knowledge/bases/{id}/documents/{doc_id}	删除文档
POST	/knowledge/search	搜索知识库
GET	/knowledge/bases/{id}/stats	获取统计信息

工具管理

方法	路径	说明
GET	/tools/list	获取内置工具列表
GET	/tools/resources	获取工具资源列表
POST	/tools/resources	创建工具资源
PUT	/tools/resources/{id}	更新工具资源
DELETE	/tools/resources/{id}	删除工具资源
GET	/tools/health	健康检查
POST	/tools/autotest	运行自动测试
POST	/tools/test-message	发送测试消息

历史记录

方法	路径	说明
GET	/history	获取对话历史
GET	/history/{id}	获取对话详情
POST	/history	创建通话记录
PUT	/history/{id}	更新通话记录
DELETE	/history/{id}	删除通话记录
POST	/history/{id}/transcripts	添加转写片段
GET	/history/{id}/audio/{turn_index}	获取音频文件

WebSocket API

连接地址

ws://localhost:8000/ws?assistant_id=<assistant_id>

协议概述

WebSocket API 使用双向消息通信：

• 文本帧：JSON 格式的控制消息
• 二进制帧：PCM 音频数据

详细文档

• WebSocket 协议 - 完整的消息格式和流程
• 错误码 - 错误码列表和处理方式

SDK

下面的 SDK 包名和类名沿用当前包标识；产品名称在文档中统一使用 Realtime Agent Studio（RAS）。

JavaScript SDK

npm install @ai-video-assistant/sdk

import { AIVideoAssistant } from '@ai-video-assistant/sdk';

const assistant = new AIVideoAssistant({
  apiUrl: 'http://localhost:8080',
  wsUrl: 'ws://localhost:8000'
});

// 创建助手
const result = await assistant.create({
  name: '客服助手',
  prompt: '你是一个友好的客服助手'
});

// 开始对话
const conversation = await assistant.connect(result.id);
conversation.on('response', (text) => {
  console.log('助手回复:', text);
});

Python SDK

pip install ai-video-assistant

from ai_video_assistant import AIVideoAssistant

client = AIVideoAssistant(
    api_url="http://localhost:8080",
    ws_url="ws://localhost:8000"
)

# 创建助手
assistant = client.assistants.create(
    name="客服助手",
    prompt="你是一个友好的客服助手"
)

# 开始对话
async with client.connect(assistant.id) as conv:
    response = await conv.send_text("你好")
    print(f"助手回复: {response}")

速率限制

端点类型	限制
REST API	100 请求/分钟
WebSocket	10 并发连接/用户

超出限制会返回 429 Too Many Requests。

下一步

• WebSocket 协议 - 实时对话协议详解
• 错误码 - 错误处理参考
• 快速开始 - 快速创建助手