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

通过 API 创建助手

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

前提条件

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

步骤 1：创建助手

请求

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
  }'

响应

{
  "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

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

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 模型

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

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

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：发布助手

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

步骤 6：测试 WebSocket 连接

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 示例

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 协议详解
• 错误码参考
• 配置知识库