taiyi/PetAgent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
dfa3b369df
PetAgent/docs/API_Documentation.md
taiyi e07c0046b0 第一次提交
2026-04-12 11:32:37 +08:00

8.3 KiB
Raw Blame History

云屋平台 - API文档

版本: 3.0
基础URL: https://api.yourdomain.com/api/v1 或 http://localhost:8000/api/v1 (开发环境)

概述

AI宠物伴侣平台API提供用户认证、聊天交互、背景管理、宠物配置和管理功能的端点。所有API端点遵循RESTful约定并返回JSON响应。

认证

大多数端点需要通过JWT（JSON网络令牌）进行认证。在Authorization头中包含令牌：

Authorization: Bearer <jwt_token>

错误处理

所有错误响应都遵循此格式：

{
  "detail": "错误消息"
}

端点

用户管理

POST /user/register

注册新用户。

请求体：

{
  "phone": "字符串",
  "password": "字符串",
  "nickname": "字符串",
  "openid": "字符串 (可选)"
}

响应：

{
  "access_token": "字符串",
  "refresh_token": "字符串",
  "user": {
    "id": "数字",
    "uid": "字符串",
    "nickname": "字符串",
    "avatar": "字符串",
    "phone": "字符串"
  }
}

POST /user/login

认证用户并返回令牌。

请求体：

{
  "phone": "字符串",
  "password": "字符串"
}

响应：

{
  "access_token": "字符串",
  "refresh_token": "字符串",
  "user": {
    "id": "数字",
    "uid": "字符串",
    "nickname": "字符串",
    "avatar": "字符串",
    "phone": "字符串"
  }
}

POST /user/wechat_login

使用微信OAuth登录。

请求体：

{
  "code": "字符串"
}

响应：

{
  "access_token": "字符串",
  "refresh_token": "字符串",
  "user": {
    "id": "数字",
    "uid": "字符串",
    "nickname": "字符串",
    "avatar": "字符串",
    "phone": "字符串"
  }
}

GET /user/profile

获取当前用户资料。

响应：

{
  "id": "数字",
  "uid": "字符串",
  "nickname": "字符串",
  "avatar": "字符串",
  "phone": "字符串",
  "status": "数字",
  "created_at": "日期时间"
}

PUT /user/profile

更新用户资料。

请求体：

{
  "nickname": "字符串 (可选)",
  "avatar": "字符串 (可选)"
}

响应：

{
  "id": "数字",
  "uid": "字符串",
  "nickname": "字符串",
  "avatar": "字符串",
  "phone": "字符串",
  "status": "数字",
  "updated_at": "日期时间"
}

背景管理

GET /background/list

获取用户可用背景列表。

查询参数：

  • visibility (可选): 按可见性过滤 (1=公开, 2=私有, 3=VIP)
  • page (可选): 页码 (默认: 1)
  • size (可选): 页面大小 (默认: 20)

响应：

{
  "data": [
    {
      "id": "数字",
      "name": "字符串",
      "resource_url": "字符串",
      "resource_type": "数字",
      "visibility": "数字",
      "bgm_url": "字符串",
      "is_locked": "布尔值",
      "lock_desc": "字符串",
      "price_points": "数字",
      "is_owned": "布尔值",
      "is_default": "布尔值"
    }
  ],
  "total": "数字",
  "page": "数字",
  "size": "数字"
}

GET /background/detail/{background_id}

获取特定背景的详细信息。

响应：

{
  "id": "数字",
  "name": "字符串",
  "resource_url": "字符串",
  "resource_type": "数字",
  "visibility": "数字",
  "bgm_url": "字符串",
  "is_locked": "布尔值",
  "lock_desc": "字符串",
  "price_points": "数字",
  "pets": [
    {
      "id": "数字",
      "name": "字符串",
      "avatar": "字符串",
      "coordinate_x": "字符串",
      "coordinate_y": "字符串",
      "scale": "字符串",
      "scene_prompt": "字符串",
      "hello_message": "字符串"
    }
  ]
}

POST /background/purchase

购买锁定的背景。

请求体：

{
  "background_id": "数字"
}

响应：

{
  "success": "布尔值",
  "message": "字符串"
}

宠物管理

GET /pet/list

获取当前背景中可用的宠物列表。

查询参数：

  • background_id: 背景ID

响应：

{
  "data": [
    {
      "id": "数字",
      "name": "字符串",
      "avatar": "字符串",
      "global_prompt": "字符串",
      "tts_voice_id": "字符串",
      "tts_speed": "字符串",
      "tts_volume": "字符串",
      "coordinate_x": "字符串",
      "coordinate_y": "字符串",
      "scale": "字符串",
      "scene_prompt": "字符串",
      "hello_message": "字符串"
    }
  ]
}

GET /pet/detail/{pet_id}

获取特定宠物的详细信息。

响应：

{
  "id": "数字",
  "name": "字符串",
  "avatar": "字符串",
  "global_prompt": "字符串",
  "tts_voice_id": "字符串",
  "tts_speed": "字符串",
  "tts_volume": "字符串",
  "status": "数字"
}

聊天管理

POST /chat/send

向AI宠物发送消息。

请求体：

{
  "message": "字符串",
  "pet_id": "数字",
  "background_id": "数字",
  "conversation_id": "字符串 (可选)"
}

响应：

{
  "response": "字符串",
  "conversation_id": "字符串",
  "tokens_used": {
    "input": "数字",
    "output": "数字"
  }
}

GET /chat/history

获取对话的聊天历史记录。

查询参数：

  • conversation_id: 对话ID
  • page (可选): 页码 (默认: 1)
  • size (可选): 页面大小 (默认: 20)

响应：

{
  "data": [
    {
      "id": "数字",
      "user_msg": "字符串",
      "ai_msg": "字符串",
      "created_at": "日期时间"
    }
  ],
  "total": "数字",
  "page": "数字",
  "size": "数字"
}

POST /chat/audio_stream

发送音频流进行实时处理（需要WebSocket连接）。

WebSocket端点： /ws/audio/{user_id}

消息格式：

{
  "type": "audio_data | end_of_speech",
  "data": "二进制音频数据 | null",
  "timestamp": "ISO字符串"
}

管理功能

GET /admin/users

获取用户列表（仅管理员）。

查询参数：

  • status (可选): 按状态过滤
  • page (可选): 页码 (默认: 1)
  • size (可选): 页面大小 (默认: 20)

响应：

{
  "data": [
    {
      "id": "数字",
      "uid": "字符串",
      "nickname": "字符串",
      "avatar": "字符串",
      "phone": "字符串",
      "status": "数字",
      "created_at": "日期时间"
    }
  ],
  "total": "数字",
  "page": "数字",
  "size": "数字"
}

PUT /admin/user/{user_id}/status

更新用户状态（仅管理员）。

请求体：

{
  "status": "数字 (1=激活, 2=禁止登录, 3=禁止发言)"
}

响应：

{
  "success": "布尔值",
  "message": "字符串"
}

GET /admin/chat_logs

获取聊天日志（仅管理员）。

查询参数：

  • user_id (可选): 按用户ID过滤
  • pet_id (可选): 按宠物ID过滤
  • start_date (可选): 按开始日期过滤
  • end_date (可选): 按结束日期过滤
  • page (可选): 页码 (默认: 1)
  • size (可选): 页面大小 (默认: 20)

响应：

{
  "data": [
    {
      "id": "数字",
      "user_id": "数字",
      "trace_id": "字符串",
      "pet_id": "数字",
      "bg_id": "数字",
      "user_msg": "字符串",
      "ai_msg": "字符串",
      "tokens_input": "数字",
      "tokens_output": "数字",
      "duration_ms": "数字",
      "conversation_id": "字符串",
      "created_at": "日期时间"
    }
  ],
  "total": "数字",
  "page": "数字",
  "size": "数字"
}

PUT /admin/quota/gift

向用户赠送配额（仅管理员）。

请求体：

{
  "user_id": "数字",
  "amount": "数字"
}

响应：

{
  "success": "布尔值",
  "message": "字符串"
}

WebSocket连接

音频流

端点：ws://localhost:8000/ws/audio/{user_id}

用于与ASR和TTS服务进行实时音频处理。该连接支持双向音频流，实现无缝语音对话。

速率限制

  • 未认证端点：每小时每个IP 100个请求
  • 已认证端点：每小时每个用户 1000个请求
  • 音频处理：每小时每个用户 50个请求

响应代码

  • 200: 成功
  • 400: 错误请求
  • 401: 未授权
  • 403: 禁止访问
  • 404: 未找到
  • 422: 验证错误
  • 429: 超出速率限制
  • 500: 内部服务器错误

附加资源