b300b469dc
- Revised site name and description for clarity and detail. - Updated navigation structure to better reflect the organization of content. - Improved changelog entries for better readability and consistency. - Migrated assistant configuration and prompt guidelines to new documentation paths. - Enhanced core concepts section to clarify the roles and capabilities of assistants and engines. - Streamlined workflow documentation to provide clearer guidance on configuration and usage.
236 lines
5.5 KiB
Markdown
236 lines
5.5 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
|
||
|
||
> 下面的 SDK 包名和类名沿用当前包标识；产品名称在文档中统一使用 Realtime Agent Studio（RAS）。
|
||
|
||
### 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) - 快速创建助手
|
||
|