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

API 参考

本节提供 AI Video Assistant 的完整 API 文档。

API 概览

AI Video Assistant 提供两种类型的 API：

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

REST API

基础地址

http://localhost:8080/api/v1

认证

REST API 使用 Bearer Token 认证：

curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost:8080/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}	获取助手详情
PATCH	/assistants/{id}	更新助手
DELETE	/assistants/{id}	删除助手

模型管理

方法	路径	说明
GET	/llm	获取 LLM 模型列表
POST	/llm	添加 LLM 模型
GET	/asr	获取 ASR 模型列表
POST	/asr	添加 ASR 模型
GET	/voices	获取语音列表
POST	/voices	添加语音配置

知识库管理

方法	路径	说明
GET	/knowledge-bases	获取知识库列表
POST	/knowledge-bases	创建知识库
POST	/knowledge-bases/{id}/documents	上传文档
DELETE	/knowledge-bases/{id}/documents/{doc_id}	删除文档

历史记录

方法	路径	说明
GET	/history	获取对话历史
GET	/history/{id}	获取对话详情
GET	/history/stats	获取统计数据

WebSocket API

连接地址

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

协议概述

WebSocket API 使用双向消息通信：

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

详细文档

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

SDK

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 协议 - 实时对话协议详解
• 错误码 - 错误处理参考
• 快速开始 - API 使用示例