Skip to content

api_reference.md

Latest commit

 

History

History
886 lines (748 loc) · 17.4 KB

api_reference.md

File metadata and controls

886 lines (748 loc) · 17.4 KB
Raw

AvatarChat API 参考文档

基础信息

  • 基础URL: http://localhost:8000/api
  • 认证方式: Bearer Token (Authorization: Bearer {token})
  • 默认分页: skip=0, limit=10
  • 错误响应格式:
{
    "detail": "错误信息描述"
}

目录

认证模块

用户注册

POST /register
Content-Type: application/json

Request Body:
{
    "username": string,    // 用户名
    "password": string,    // 密码
    "gender": number,      // 性别(0:保密,1:男,2:女)
    "bio": string         // 个人简介(可选)
}

用户登录

POST /token
Content-Type: application/x-www-form-urlencoded

Request Body:
- username: string    // 用户名
- password: string    // 密码

Response:
{
    "access_token": string,
    "token_type": "bearer",
    "user": {
        "id": string,
        "username": string,
        "gender": number,
        "bio": string,
        "avatar_url": string
    }
}

用户模块

获取当前用户信息

GET /users/me
Authorization: Bearer {token}

更新当前用户资料

PUT /users/me
Authorization: Bearer {token}

Request Body:
{
    "gender": number,      // 性别(可选)
    "bio": string         // 个人简介(可选)
}

获取指定用户信息

GET /users/{user_id}

化身模块

获取化身列表

GET /avatars/list

Query Parameters:
- skip: number     // 跳过记录数(默认0)
- limit: number    // 返回记录数限制(默认10)

Response:
[
    {
        "id": string,
        "prompt_settings": {
            "personality": string,
            "interests": string,
            "values": string,
            "speaking_style": string,
            "sample_dialogue": string
        },
        "appearance_image": string,
        "voice_sample": string,
        "video_sample": string,
        "avatar_likes_count": number,
        "user_id": string,
        "user": {
            "id": string,
            "username": string,
            "gender": number,
            "bio": string,
            "profile_image": string
        }
    }
]

与Starter助手对话

POST /avatars/starter/chat
Authorization: Bearer {token}

Request Body:
{
    "message": string    // 用户消息
}

Response:
{
    "message": string    // 助手回复
}

创建化身

POST /avatars/create
Authorization: Bearer {token}
Content-Type: multipart/form-data

Request Body:
- prompt_settings: string (JSON格式)
  {
    "personality": string,      // 性格特征
    "interests": string,        // 兴趣爱好
    "values": string,          // 价值观
    "speaking_style": string,   // 说话风格
    "sample_dialogue": string   // 示例对话
  }
- appearance: File    // 外观图片文件
- voice: File        // 声音样本文件

获取当前用户的化身

GET /avatars/me
Authorization: Bearer {token}

更新当前用户的化身

PUT /avatars/me
Authorization: Bearer {token}
Content-Type: multipart/form-data

Request Body:
- prompt_settings: object (JSON格式)
  {
    "personality": string,      // 性格特征
    "interests": string,        // 兴趣爱好
    "values": string,          // 价值观
    "speaking_style": string,   // 说话风格
    "sample_dialogue": string   // 示例对话
  }
- appearance: File    // 外观图片文件(可选)
- voice: File        // 声音样本文件(可选)

Response:
{
    "id": string,
    "prompt_settings": object,
    "appearance_image": string,
    "voice_sample": string,
    "video_sample": string,
    "user_id": string,
    "message": "Avatar updated successfully"
}

获取化身详情

GET /avatars/{avatar_id}

Response:
{
  "id": "a_123456",
  "prompt_settings": {
    "personality": "开朗外向",
    "interests": "旅行",
    "values": "诚实正直"
  },
  "appearance_image": "uploads/appearances/20230101_123456.jpg",
  "voice_sample": "uploads/voice_samples/20230101_123456.wav",
  "voice_id": "voice_123456",
  "video_sample": null,
  "avatar_likes_count": 10,
  "user_id": "u_123456",
  "user": {
    "id": "u_123456",
    "username": "user123",
    "email": "user@example.com",
    "profile_image": "uploads/profile_images/default.jpg",
    "is_active": true,
    "created_at": "2023-01-01T12:34:56"
  }
}

给化身点赞或取消点赞

POST /avatars/{avatar_id}/like
Authorization: Bearer {token}

Response:
{
  "is_liked": true  // true表示已点赞，false表示未点赞
}

检查用户是否给化身点过赞

GET /avatars/{avatar_id}/like/check
Authorization: Bearer {token}

Response:
{
  "is_liked": true  // true表示已点赞，false表示未点赞
}

好友模块

发送好友请求

POST /friends/requests
Authorization: Bearer {token}

Request Body:
{
    "to_user_id": string    // 接收请求的用户ID
}

获取收到的好友请求

GET /friends/requests/received
Authorization: Bearer {token}

获取发送的好友请求

GET /friends/requests/sent
Authorization: Bearer {token}

获取好友列表

GET /friends/list
Authorization: Bearer {token}

帖子模块

创建帖子

POST /posts
Authorization: Bearer {token}

Request Body:
{
    "title": string,      // 帖子标题
    "content": string     // 帖子内容
}

获取帖子列表

GET /posts

Query Parameters:
- skip: number    // 跳过条数(分页)
- limit: number   // 每页条数

获取帖子详情

GET /posts/{post_id}

更新帖子

PUT /posts/{post_id}
Authorization: Bearer {token}

Request Body:
{
    "title": string,      // 帖子标题(可选)
    "content": string     // 帖子内容(可选)
}

删除帖子

DELETE /posts/{post_id}
Authorization: Bearer {token}

点赞帖子

POST /posts/{post_id}/like
Authorization: Bearer {token}

取消点赞帖子

DELETE /posts/{post_id}/like
Authorization: Bearer {token}

检查是否已点赞

GET /posts/{post_id}/like/check
Authorization: Bearer {token}

Response:
{
    "is_liked": boolean    // 是否已点赞
}

评论帖子

POST /posts/{post_id}/comments
Authorization: Bearer {token}

Request Body:
{
    "content": string,      // 评论内容
    "parent_id": string     // 父评论ID(可选,用于回复评论)
}

获取帖子评论

GET /posts/{post_id}/comments

Query Parameters:
- skip: number    // 跳过条数(分页)
- limit: number   // 每页条数

回复评论

POST /posts/{post_id}/comments/{comment_id}/replies
Authorization: Bearer {token}

Request Body:
{
    "content": string      // 回复内容
}

获取评论回复

GET /posts/comments/{comment_id}/replies

Query Parameters:
- skip: number    // 跳过条数(分页)
- limit: number   // 每页条数

获取当前用户的帖子

GET /posts/user/me
Authorization: Bearer {token}

Query Parameters:
- skip: number    // 跳过条数(分页)
- limit: number   // 每页条数

获取指定用户的帖子

GET /posts/user/{user_id}

Query Parameters:
- skip: number    // 跳过条数(分页)
- limit: number   // 每页条数

上传帖子图片

POST /posts/upload-image
Authorization: Bearer {token}
Content-Type: multipart/form-data

Request Body:
- file: File    // 图片文件(jpg, jpeg, png, gif, webp格式, <5MB)

Response:
{
    "image_url": string    // 图片URL
}

获取帖子总数

GET /posts/count

Response:
{
    "count": number    // 帖子总数
}

获取指定用户的帖子总数

GET /posts/user/{user_id}/count

Response:
{
    "count": number    // 用户帖子总数
}

搜索帖子

GET /posts/search

Query Parameters:
- q: string    // 搜索关键词

Response:
[
    {帖子对象},
    ...
]

聊天模块

发送消息

POST /chat/messages/send
Authorization: Bearer {token}

Request Body:
{
    "type": string,        // "friend_message" 或 "avatar_message"
    "content": string,     // 消息内容
    "to_user_id": string,  // 好友消息时必需
    "avatar_id": string    // 化身消息时必需
}

Response:
{
    "id": string,
    "content": string,
    "created_at": string,
    // 其他字段根据消息类型不同而不同
}

发送好友消息

POST /friends/{friend_id}/messages
Authorization: Bearer {token}

Request Body:
{
    "type": "friend_message",  // 消息类型，必须为 "friend_message"
    "content": string           // 消息内容
}

Response:
{
    "id": string,               // 消息ID
    "content": string,          // 消息内容
    "created_at": string,       // 消息创建时间
    // 其他字段根据实现可能会有所不同
}

获取聊天会话列表

GET /chat/sessions
Authorization: Bearer {token}

Response:
[
    {
        "id": string,
        "session_type": string,  // "friend_session" 或 "avatar_session"
        "created_at": string,
        "updated_at": string,
        // 其他字段根据会话类型不同而不同
    }
]

获取好友聊天历史

GET /chat/friends/{friend_id}/history
Authorization: Bearer {token}

Query Parameters:
- skip: number     // 跳过消息数(默认0)
- limit: number    // 返回消息数(默认50)

Response:
[
    {
        "id": string,
        "content": string,
        "from_user_id": string,
        "to_user_id": string,
        "created_at": string,
        "is_read": boolean
    }
]

获取化身聊天历史

GET /chat/avatars/{avatar_id}/history
Authorization: Bearer {token}

Query Parameters:
- skip: number     // 跳过消息数(默认0)
- limit: number    // 返回消息数(默认50)

Response:
[
    {
        "id": string,
        "content": string,
        "user_id": string,
        "avatar_id": string,
        "created_at": string,
        "is_from_user": boolean
    }
]

标记好友消息为已读

POST /chat/friends/{friend_id}/mark-read
Authorization: Bearer {token}

Response:
{
    "message": "success"
}

获取未读消息数量

GET /chat/friends/{friend_id}/unread-count
Authorization: Bearer {token}

Response:
{
    "unread_count": number
}

获取所有未读消息

GET /chat/unread
Authorization: Bearer {token}

Response:
[
    {
        "id": string,
        "content": string,
        "from_user_id": string,
        "to_user_id": string,
        "created_at": string,
        "is_read": boolean
    }
]

获取与化身的聊天历史

GET /chat/avatar/{avatar_id}/messages
Authorization: Bearer {token}

Query Parameters:
- skip: number     // 跳过消息数(默认0)
- limit: number    // 返回消息数(默认50)

Response:
[
    {
        "id": string,
        "content": string,
        "user_id": string,
        "avatar_id": string,
        "created_at": string,
        "is_from_user": boolean,
        "user": {
            // 用户信息
        },
        "avatar": {
            // 化身信息
        }
    }
]

获取与化身的所有会话

GET /chat/avatar/{avatar_id}/sessions
Authorization: Bearer {token}

Response:
[
    {
        "id": string,
        "user_id": string,
        "avatar_id": string,
        "created_at": string,
        "updated_at": string,
        "user": {
            // 用户信息
        },
        "avatar": {
            // 化身信息
        }
    }
]

获取指定会话的消息历史

GET /chat/sessions/{session_id}/messages
Authorization: Bearer {token}

Query Parameters:
- skip: number     // 跳过消息数(默认0)
- limit: number    // 返回消息数(默认50)

Response:
[
    {
        "id": string,
        "content": string,
        "user_id": string,
        "avatar_id": string,
        "created_at": string,
        "is_from_user": boolean,
        "user": {
            // 用户信息
        },
        "avatar": {
            // 化身信息
        }
    }
]

语音合成模块

文本转语音

POST /voice/synthesis/synthesize
Authorization: Bearer {token}

Request Body:
- text: string           // 要合成的文本
- avatar_id: string      // 化身ID
- volume: float          // 音量，范围0.5-2.0，默认1.0(可选)
- speech_rate: float     // 语速，范围0.5-2.0，默认1.0(可选)
- pitch_rate: float      // 音调，范围0.5-2.0，默认1.0(可选)

Response:
{
    "audio_url": string,     // 合成的音频URL
    "text": string,          // 原始文本
    "avatar_id": string,     // 化身ID
    "volume": float,         // 音量
    "speech_rate": float,    // 语速
    "pitch_rate": float      // 音调
}

上传声音样本

POST /voice/synthesis/upload-sample
Authorization: Bearer {token}
Content-Type: multipart/form-data

Request Body:
- file: File    // 声音样本文件

Response:
{
    "file_path": string,     // 文件保存路径
    "message": string        // 成功消息
}

克隆声音

POST /voice/synthesis/clone
Authorization: Bearer {token}

Request Body:
- file_path: string      // 声音样本文件路径
- prefix: string         // 音色前缀，仅允许数字和小写字母，小于十个字符

Response:
{
    "voice_id": string,      // 克隆的音色ID
    "message": string        // 成功消息
}

更新音色

POST /voice/synthesis/update/{voice_id}
Authorization: Bearer {token}
Content-Type: multipart/form-data

Path Parameters:
- voice_id: string       // 音色ID

Request Body:
- file_path: string      // 新的声音样本文件路径

Response:
{
    "voice_id": string,      // 音色ID
    "message": string        // 成功消息
}

列出所有音色

GET /voice/synthesis/list
Authorization: Bearer {token}

Query Parameters:
- prefix: string         // 音色前缀过滤(可选)
- page_index: number     // 页码索引(默认0)
- page_size: number      // 每页大小(默认10)

Response:
{
    "voices": [
        {
            // 音色信息
        }
    ],
    "total": number,         // 总数
    "page_index": number,    // 页码索引
    "page_size": number      // 每页大小
}

获取音色信息

GET /voice/synthesis/info/{voice_id}
Authorization: Bearer {token}

Path Parameters:
- voice_id: string       // 音色ID

Response:
{
    // 音色详细信息
}

更新化身的声音

POST /voice/synthesis/avatar/{avatar_id}/update-voice
Authorization: Bearer {token}
Content-Type: multipart/form-data

Path Parameters:
- avatar_id: string      // 化身ID

Request Body:
- file: File             // 新的声音样本文件

Response:
{
    "avatar_id": string,     // 化身ID
    "voice_id": string,      // 音色ID
    "voice_sample": string,  // 声音样本路径
    "message": string        // 成功消息
}

视频生成模块

人脸检测

POST /api/video/face-detect
Authorization: Bearer {token}
Content-Type: multipart/form-data

Request Body:
- file: 图片文件 (jpg, jpeg, png, bmp, webp格式, <10MB)

Response:
{
    "pass_check": boolean,    // 是否通过检测
    "message": string         // 结果描述
}

生成视频

POST /api/video/generate
Authorization: Bearer {token}

Request Body:
{
    "avatar_id": string,        // 化身ID(avatar_id和image_url二选一)
    "image_url": string,        // 图片URL(avatar_id和image_url二选一)
    "audio_url": string,        // 音频URL(必需)
    "template_id": string,      // 动作模板ID("normal"、"calm"或"active")(可选，默认"normal")
    "eye_move_freq": float,     // 眨眼频率(0-1)(可选，默认0.5)
    "video_fps": integer,       // 视频帧率(15-30)(可选，默认24)
    "mouth_move_strength": float, // 嘴部动作幅度(0-1.5)(可选，默认1.0)
    "paste_back": boolean,      // 是否贴回原图(可选，默认true)
    "head_move_strength": float, // 头部动作幅度(0-1)(可选，默认0.7)
    "wait_for_result": boolean  // 是否等待结果(可选，默认true)
}

Response:
{
    "task_id": string,          // 任务ID
    "status": string,           // 状态("processing"或"completed")
    "video_url": string,        // 视频URL(仅当wait_for_result为true且生成成功时返回)
    "image_url": string,        // 使用的图片URL
    "audio_url": string         // 使用的音频URL
}

获取任务状态

GET /api/video/tasks/{task_id}
Authorization: Bearer {token}

Response:
{
    "task_id": string,          // 任务ID
    "status": string,           // 状态("PENDING"、"RUNNING"、"SUCCEEDED"或"FAILED")
    "video_url": string,        // 视频URL(仅当status为"SUCCEEDED"时返回)
    "error": string             // 错误信息(仅当status为"FAILED"时返回)
}

注意事项

  1. 所有需要认证的接口必须在请求头中携带有效的token
  2. 文件上传接口需要使用multipart/form-data格式
  3. 返回的时间格式均为ISO 8601标准
  4. 图片文件支持格式: jpg, jpeg, png
  5. 音频文件支持格式: mp3, wav, m4a
  6. 单个文件大小限制: 10MB
  7. 聊天消息按时间倒序排列，最新的消息在前
  8. 分页参数 skip 和 limit 为可选参数，默认值分别为 0 和 50
  9. 音频样本要求: 时长10-60秒，大小不超过10MB