7fbf52078f
- Replaced the "通过控制台" and "通过 API" entries in the quickstart section with "资源库配置" for improved clarity. - Updated the API reference link in index.md to direct users to the main quickstart page instead of the outdated API usage example.
233 lines
5.4 KiB
Markdown
233 lines
5.4 KiB
Markdown
# 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 认证：
|
||
|
||
```bash
|
||
curl -H "Authorization: Bearer YOUR_API_KEY" \
|
||
http://localhost:8000/api/v1/assistants
|
||
```
|
||
|
||
### 通用响应格式
|
||
|
||
**成功响应**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": { ... }
|
||
}
|
||
```
|
||
|
||
**列表响应**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"items": [...],
|
||
"total": 100,
|
||
"page": 1,
|
||
"page_size": 20
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应**
|
||
|
||
```json
|
||
{
|
||
"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 协议](websocket.md) - 完整的消息格式和流程
|
||
- [错误码](errors.md) - 错误码列表和处理方式
|
||
|
||
## SDK
|
||
|
||
### JavaScript SDK
|
||
|
||
```bash
|
||
npm install @ai-video-assistant/sdk
|
||
```
|
||
|
||
```javascript
|
||
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
|
||
|
||
```bash
|
||
pip install ai-video-assistant
|
||
```
|
||
|
||
```python
|
||
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 协议](websocket.md) - 实时对话协议详解
|
||
- [错误码](errors.md) - 错误处理参考
|
||
- [快速开始](../quickstart/index.md) - 快速创建助手
|