AI-VideoAssistant/docs/content/quickstart/api.md

# 通过 API 创建助手

本指南介绍如何通过 REST API 程序化创建和管理 AI 助手。

## 前提条件

- 已部署 API 服务（默认端口 8080）
- 已配置 LLM 和 TTS 模型
- 有可用的 HTTP 客户端（curl、Postman 等）

## 步骤 1：创建助手

### 请求

```bash
curl -X POST "http://localhost:8080/api/v1/assistants" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "客服助手",
    "prompt": "你是一个友好的客服助手，负责解答用户问题。保持简洁、专业的回复风格。",
    "opener": "你好，我是客服助手，请问有什么可以帮您？",
    "language": "zh-CN",
    "temperature": 0.7,
    "max_tokens": 2048
  }'
```

### 响应

```json
{
  "success": true,
  "data": {
    "id": "asst_abc123",
    "name": "客服助手",
    "prompt": "你是一个友好的客服助手...",
    "opener": "你好，我是客服助手...",
    "language": "zh-CN",
    "temperature": 0.7,
    "created_at": "2025-01-01T00:00:00Z"
  }
}
```

记下返回的 `id`，后续步骤需要使用。

## 步骤 2：配置语音

### 配置 TTS

```bash
curl -X PATCH "http://localhost:8080/api/v1/assistants/asst_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "voice": {
      "vendor": "aliyun",
      "voice_id": "xiaoyun",
      "speed": 1.0,
      "volume": 80,
      "pitch": 1.0
    }
  }'
```

### 配置 ASR

```bash
curl -X PATCH "http://localhost:8080/api/v1/assistants/asst_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "asr": {
      "vendor": "sensevoice",
      "language": "zh-CN"
    }
  }'
```

## 步骤 3：关联 LLM 模型

```bash
curl -X PATCH "http://localhost:8080/api/v1/assistants/asst_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "llm_id": "llm_xyz789"
  }'
```

## 步骤 4：关联知识库（可选）

```bash
curl -X PATCH "http://localhost:8080/api/v1/assistants/asst_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "knowledge_base_id": "kb_def456",
    "knowledge": {
      "similarity_threshold": 0.7,
      "top_k": 3
    }
  }'
```

## 步骤 5：发布助手

```bash
curl -X POST "http://localhost:8080/api/v1/assistants/asst_abc123/publish"
```

## 步骤 6：测试 WebSocket 连接

### JavaScript 示例

```javascript
const assistantId = 'asst_abc123';
const ws = new WebSocket(`ws://localhost:8000/ws?assistant_id=${assistantId}`);

ws.onopen = () => {
  console.log('连接已建立');
  
  // 发送 session.start
  ws.send(JSON.stringify({
    type: 'session.start',
    audio: {
      encoding: 'pcm_s16le',
      sample_rate_hz: 16000,
      channels: 1
    }
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('收到事件:', data.type);
  
  if (data.type === 'session.started') {
    // 发送文本消息测试
    ws.send(JSON.stringify({
      type: 'input.text',
      text: '你好，你能做什么？'
    }));
  }
  
  if (data.type === 'assistant.response.final') {
    console.log('助手回复:', data.data.text);
  }
};

ws.onerror = (error) => {
  console.error('连接错误:', error);
};

ws.onclose = () => {
  console.log('连接已关闭');
};
```

### Python 示例

```python
import asyncio
import websockets
import json

async def test_assistant():
    uri = "ws://localhost:8000/ws?assistant_id=asst_abc123"
    
    async with websockets.connect(uri) as ws:
        # 发送 session.start
        await ws.send(json.dumps({
            "type": "session.start",
            "audio": {
                "encoding": "pcm_s16le",
                "sample_rate_hz": 16000,
                "channels": 1
            }
        }))
        
        # 等待 session.started
        response = await ws.recv()
        print(f"收到: {response}")
        
        # 发送文本消息
        await ws.send(json.dumps({
            "type": "input.text",
            "text": "你好，你能做什么？"
        }))
        
        # 接收响应
        while True:
            response = await ws.recv()
            data = json.loads(response)
            print(f"事件: {data['type']}")
            
            if data['type'] == 'assistant.response.final':
                print(f"回复: {data['data']['text']}")
                break

asyncio.run(test_assistant())
```

## 完整 API 参考

### 助手管理 API

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/v1/assistants | 获取助手列表 |
| POST | /api/v1/assistants | 创建助手 |
| GET | /api/v1/assistants/{id} | 获取助手详情 |
| PATCH | /api/v1/assistants/{id} | 更新助手 |
| DELETE | /api/v1/assistants/{id} | 删除助手 |
| POST | /api/v1/assistants/{id}/publish | 发布助手 |

### 助手字段说明

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | 助手名称 |
| prompt | string | 是 | 系统提示词 |
| opener | string | 否 | 开场白 |
| language | string | 否 | 语言代码 |
| temperature | number | 否 | 温度参数（0-1） |
| max_tokens | number | 否 | 最大输出长度 |
| llm_id | string | 否 | 关联的 LLM 模型 ID |
| voice | object | 否 | TTS 配置 |
| asr | object | 否 | ASR 配置 |

## 错误处理

常见错误及解决方案：

| 错误码 | 说明 | 解决方案 |
|--------|------|---------|
| 400 | 请求参数错误 | 检查请求体格式 |
| 404 | 助手不存在 | 确认 assistant_id 正确 |
| 500 | 服务器错误 | 查看服务端日志 |

## 下一步

- [WebSocket 协议详解](../api-reference/websocket.md)
- [错误码参考](../api-reference/errors.md)
- [配置知识库](../customization/knowledge-base.md)