FastAPI · REST + WebSocket
接口测试

给给窝
后端 API 接口文档

本文档指向Congreat233,提供不完整的后端 API 接口定义、请求/响应格式、参数说明和错误码参考。随时维护,建议使用。

基础地址
https://onlygay.cn/api
认证方式
JWT Token + Cookie
WebSocket
wss://onlygay.cn/ws/chat/{room_id}?token={access_token}
内容类型
application/json

认证与通用约定

统一响应格式:所有接口返回统一的三段式 JSON 结构,包含 code(状态码)、message(提示信息)、data(数据)。
成功响应
{
  "code": 200,
  "message": "success",
  "data": { ... }
}
错误响应
{
  "code": 401,
  "message": "未登录或 Token 已过期",
  "data": null
}
请求头规范
Content-Type: application/json
Authorization: Bearer {access_token}
Cookie 写入规则
Set-Cookie: access_token=xxx; HttpOnly; Secure; SameSite=Strict; Path=/
Set-Cookie: remember_token=xxx; HttpOnly; Secure; SameSite=Strict; Path=/; Max-Age=2592000
Token 机制
Token 类型有效期用途
access_token2 小时API 请求认证
refresh_token7 天刷新 access_token
remember_token30 天"记住密码" 自动登录
用户等级说明
等级标识说明
普通用户normal基础功能权限
VIP 用户vip高级功能权限
管理员admin全部功能 + 管理后台
账号状态说明
状态标识说明
待审核pending注册后等待管理员审核
已激活active正常使用
已拒绝rejected注册被拒绝
已禁用disabled账号被管理员禁用
在线状态说明
状态标识说明
在线online登录后默认状态
离线offline退出登录后自动切换
忙碌busy用户手动选择
🔒

认证模块

用户注册、登录、退出及个人信息管理。注册需管理员审核后方可登录。

POST /api/auth/register 提交注册申请
用户提交注册申请,创建后账号状态为 pending,需管理员审核激活。
请求参数 (Body)
字段类型必填说明
usernamestring必填用户名,唯一
emailstring必填邮箱地址,唯一
passwordstring必填密码
请求示例
{
  "username": "zhangsan",
  "email": "zhangsan@example.com",
  "password": "SecurePass123"
}
成功响应 200
{
  "code": 200,
  "message": "注册申请已提交,请等待管理员审核",
  "data": {
    "username": "zhangsan",
    "email": "zhangsan@example.com"
  }
}
POST /api/auth/login 用户登录
账号状态必须为 active 才能登录。登录成功后自动将 online_status 设为 online。
请求参数 (Body)
字段类型必填说明
usernamestring必填用户名
passwordstring必填密码
remember_meboolean可选是否记住登录(30天免密),默认 false
请求示例
{
  "username": "zhangsan",
  "password": "SecurePass123",
  "remember_me": true
}
成功响应 200
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": 1,
      "username": "zhangsan",
      "email": "zhangsan@example.com",
      "level": "normal"
    }
  }
}
注意:remember_me = true 时,服务端额外写入 remember_token Cookie(有效期30天)。前端应存储 token 用于后续请求。
POST /api/auth/refresh 刷新Token
用 refreshToken 换取新的 accessToken,用于延长登录状态。
请求参数 (Body)
字段类型必填说明
refreshTokenstring必填刷新令牌
请求示例
{
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}
成功响应 200
{
  "code": 200,
  "message": "Token已刷新",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
  }
}
POST /api/auth/logout 退出登录
退出登录,同时将 online_status 自动设为 offline,清除相关 Cookie。
需要认证
成功响应 200
{ "code": 200, "message": "已退出登录", "data": null }
GET /api/auth/me 获取当前用户信息
需要认证
成功响应 200
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "username": "zhangsan",
    "email": "zhangsan@example.com",
    "level": "normal",
    "status": "active",
    "online_status": "online",
    "theme": "light",
    "layout_config": { ... },
    "created_at": "2025-01-01T00:00:00"
  }
}
PUT /api/auth/profile 修改个人信息
需要认证
请求参数 (Body)
字段类型必填说明
usernamestring可选新用户名
emailstring可选新邮箱
PUT /api/auth/password 修改密码
需要认证
请求参数 (Body)
字段类型必填说明
old_passwordstring必填原密码
new_passwordstring必填新密码
🟢

在线状态

登录后可手动选择在线状态(在线/忙碌),退出登录后自动设为离线。可查看所有成员的在线状态。

PUT /api/users/status 设置在线状态
需要认证
请求参数 (Body)
字段类型必填说明
statusstring必填可选值:online / offline / busy
GET /api/users/status 获取所有成员在线状态
需要认证
成功响应 200
{
  "code": 200,
  "message": "success",
  "data": [
    { "user_id": 1, "username": "zhangsan", "online_status": "online" },
    { "user_id": 2, "username": "lisi", "online_status": "busy" }
  ]
}

个性化设置

主题(深色/浅色)和页面布局配置均后端持久化存储,支持跨设备同步。

GET /api/settings 获取当前用户设置
需要认证
成功响应 200
{
  "code": 200,
  "message": "success",
  "data": {
    "theme": "dark",
    "layout_config": {
      "sidebar_position": "left",
      "modules": ["todo", "chat", "files"]
    }
  }
}
PUT /api/settings 更新用户设置
需要认证
请求参数 (Body)
字段类型必填说明
themestring可选可选值:dark / light
layout_configobject可选页面布局配置 JSON 对象
👑

管理员模块

仅限 admin 等级用户访问。用于审核注册申请、管理用户等级和账号状态。

权限要求:所有管理员接口均需要 level = admin,否则返回 403 无权限。
GET /api/admin/users 获取用户列表
仅管理员
Query 参数
参数类型必填说明
statusstring可选按状态筛选:pending / active / rejected / disabled
levelstring可选按等级筛选:normal / vip / admin
keywordstring可选按用户名或邮箱模糊搜索
pageint可选页码,默认 1
page_sizeint可选每页条数,默认 20
成功响应 200
{
  "code": 200,
  "message": "success",
  "data": {
    "total": 100,
    "page": 1,
    "page_size": 20,
    "items": [
      {
        "id": 1,
        "username": "zhangsan",
        "email": "zhangsan@example.com",
        "level": "normal",
        "status": "pending",
        "online_status": "offline",
        "created_at": "2025-01-01T00:00:00"
      }
    ]
  }
}
PUT /api/admin/users/{user_id}/approve 审核通过注册申请
仅管理员
将用户状态从 pending 设为 active,激活该账号。
成功响应 200
{ "code": 200, "message": "已激活该账号", "data": null }
PUT /api/admin/users/{user_id}/reject 拒绝注册申请
仅管理员
将用户状态从 pending 设为 rejected。
PUT /api/admin/users/{user_id}/level 修改用户等级
仅管理员
等级由管理员固定分配,用户不可自行修改。
请求参数 (Body)
字段类型必填说明
levelstring必填可选值:normal / vip / admin
PUT /api/admin/users/{user_id}/disable 禁用用户账号
仅管理员
将用户状态设为 disabled,该用户将无法登录。
PUT /api/admin/users/{user_id}/enable 重新启用用户账号
仅管理员
将用户状态恢复为 active。

待办任务

扁平化待办列表,支持截止日期、优先级、标签、备注。可通过用户名分享给指定人员,权限可选只读或编辑。

POST /api/todos 创建待办事项
需要认证
请求参数 (Body)
字段类型必填说明
titlestring必填待办标题
contentstring可选备注内容
deadlinedatetime可选截止日期,ISO 8601 格式
prioritystring可选优先级:low / medium / high / urgent
tagsarray可选标签数组,如 ["工作","紧急"]
请求示例
{
  "title": "完成项目文档",
  "content": "需要包含API接口说明",
  "deadline": "2025-02-01T18:00:00",
  "priority": "high",
  "tags": ["工作", "紧急"]
}
GET /api/todos 获取待办列表
需要认证
返回本人创建的 + 被分享给本人的所有待办。
Query 参数
参数类型必填说明
is_completedboolean可选按完成状态筛选
prioritystring可选按优先级筛选
tagstring可选按标签筛选
keywordstring可选按标题模糊搜索
pageint可选页码,默认 1
page_sizeint可选每页条数,默认 20
GET /api/todos/{todo_id} 获取待办详情
需要认证
返回完整的待办信息,包含分享列表。
PUT /api/todos/{todo_id} 修改待办事项
需要认证
权限:仅创建者或被授予 edit 权限的用户可修改。
请求参数 (Body,部分更新)
字段类型必填说明
titlestring可选新标题
contentstring可选新备注
deadlinedatetime可选新截止日期,设为 null 可清除
prioritystring可选新优先级
tagsarray可选新标签数组
is_completedboolean可选完成状态
DELETE /api/todos/{todo_id} 删除待办事项
需要认证
权限:仅创建者可删除。
POST /api/todos/{todo_id}/share 分享待办给指定用户
需要认证
请求参数 (Body)
字段类型必填说明
usernamestring必填目标用户名
permissionstring必填权限:read(只读)/ edit(可编辑)
GET /api/todos/{todo_id}/shares 查看待办的分享列表
需要认证
成功响应 200
{
  "code": 200,
  "message": "success",
  "data": [
    { "user_id": 2, "username": "lisi", "permission": "read" },
    { "user_id": 3, "username": "wangwu", "permission": "edit" }
  ]
}
PUT /api/todos/{todo_id}/shares/{user_id} 修改分享权限
需要认证
请求参数 (Body)
字段类型必填说明
permissionstring必填新权限:read / edit
DELETE /api/todos/{todo_id}/shares/{user_id} 取消分享
需要认证
移除指定用户对该待办的访问权限。
💬

聊天系统

支持公共群聊房间和一对一私聊双模式。消息支持撤回(5分钟内)、点赞、表情包。实时通信通过 WebSocket 实现。

POST /api/chat/rooms 创建聊天房间
需要认证
创建群聊房间,创建者自动加入。
请求参数 (Body)
字段类型必填说明
namestring必填房间名称
descriptionstring可选房间描述
GET /api/chat/rooms 获取当前用户所在的房间列表
需要认证
Query 参数
参数类型必填说明
room_typestring可选按类型筛选:group / private
keywordstring可选按房间名搜索
GET /api/chat/rooms/{room_id} 获取房间详情
需要认证
返回房间详情,包含成员列表及各成员在线状态。
成功响应 200
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "name": "项目讨论组",
    "description": "日常沟通",
    "room_type": "group",
    "creator_id": 1,
    "members": [
      { "user_id": 1, "username": "zhangsan", "online_status": "online" },
      { "user_id": 2, "username": "lisi", "online_status": "busy" }
    ],
    "created_at": "2025-01-01T00:00:00"
  }
}
PUT /api/chat/rooms/{room_id} 修改房间信息
需要认证
权限:仅房间创建者或管理员可操作。
请求参数 (Body)
字段类型必填说明
namestring可选新房间名
descriptionstring可选新描述
DELETE /api/chat/rooms/{room_id} 解散/删除房间
需要认证
权限:仅房间创建者或管理员可操作。
POST /api/chat/rooms/{room_id}/join 加入房间
需要认证
当前用户加入指定群聊房间。
POST /api/chat/rooms/{room_id}/leave 退出房间
需要认证
当前用户退出指定群聊房间。
POST /api/chat/rooms/{room_id}/members 邀请用户加入房间
需要认证
请求参数 (Body)
字段类型必填说明
usernamestring必填目标用户名
GET /api/chat/rooms/{room_id}/messages 获取历史消息
需要认证
Query 参数
参数类型必填说明
pageint可选页码
page_sizeint可选每页条数,默认 50
before_idint可选获取此 ID 之前的消息(向上翻页)
成功响应 200
{
  "code": 200,
  "message": "success",
  "data": {
    "total": 500,
    "items": [
      {
        "id": 101,
        "room_id": 1,
        "sender": { "id": 1, "username": "zhangsan" },
        "content": "大家好",
        "message_type": "text",
        "is_recalled": false,
        "like_count": 3,
        "liked_by_me": true,
        "created_at": "2025-01-15T10:30:00"
      }
    ]
  }
}
前端提示:使用 before_id 进行向上翻页加载,比基于 page 的分页更高效。当用户滚动到顶部时,传入当前最早消息的 id 即可加载更早的消息。
POST /api/chat/rooms/{room_id}/messages 发送消息(REST)
需要认证
通过 REST 发送消息。实际场景中推荐使用 WebSocket 实时发送,此接口可作为备选方案。
请求参数 (Body)
字段类型必填说明
contentstring必填消息内容
message_typestring必填消息类型:text / emoji / image
DELETE /api/chat/messages/{message_id}/recall 撤回消息
需要认证
权限:仅消息发送者可撤回,且发送时间需在 5 分钟以内。撤回后通过 WebSocket 广播撤回事件。
成功响应 200
{ "code": 200, "message": "消息已撤回", "data": null }
前端处理:收到 WebSocket 的 message_recalled 事件后,将对应消息显示为"该消息已撤回"。
POST /api/chat/messages/{message_id}/like 给消息点赞
需要认证
对单条消息点赞。点赞后通过 WebSocket 广播点赞事件。
DELETE /api/chat/messages/{message_id}/like 取消点赞
需要认证
GET /api/chat/private/{user_id} 获取或创建一对一私聊
需要认证
若与目标用户已存在私聊房间则直接返回,否则自动创建。
成功响应 200
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 5,
    "room_type": "private",
    "members": [
      { "user_id": 1, "username": "zhangsan" },
      { "user_id": 2, "username": "lisi" }
    ]
  }
}
POST /api/chat/emojis 上传自定义表情包
需要认证
请求参数 (multipart/form-data)
字段类型必填说明
namestring必填表情名称
filefile必填图片文件
GET /api/chat/emojis 获取自定义表情包列表
需要认证
返回当前用户上传的所有自定义表情包。
DELETE /api/chat/emojis/{emoji_id} 删除自定义表情包
需要认证
权限:仅表情包上传者可删除。

WebSocket 实时通信

聊天、放映、一起听三个模块的实时通道。连接时需传 token 参数进行认证。

WS /ws/chat/{room_id}?token={access_token} 聊天实时通信
连接地址
wss://onlygay.cn/ws/chat/{room_id}?token={access_token}
通过 URL 参数传递 access_token 进行认证。连接失败时返回 401。
客户端发送格式
发送消息
{
  "type": "send_message",
  "data": {
    "content": "消息内容",
    "message_type": "text"
  }
}
服务器推送事件
type说明data 字段
new_message新消息完整消息对象(同历史消息格式)
message_recalled消息被撤回{ message_id, room_id }
message_liked消息被点赞{ message_id, user_id, like_count }
message_unliked取消点赞{ message_id, user_id, like_count }
user_joined用户加入房间{ user_id, username }
user_left用户离开房间{ user_id, username }
status_changed用户在线状态变更{ user_id, online_status }
推送示例 — new_message
{
  "type": "new_message",
  "data": {
    "id": 102,
    "room_id": 1,
    "sender": { "id": 2, "username": "lisi" },
    "content": "收到,马上处理",
    "message_type": "text",
    "is_recalled": false,
    "like_count": 0,
    "liked_by_me": false,
    "created_at": "2025-01-15T10:31:00"
  }
}
推送示例 — message_recalled
{
  "type": "message_recalled",
  "data": { "message_id": 102, "room_id": 1 }
}
前端建议:进入房间页面时建立 WebSocket 连接,离开时断开。监听所有事件类型并实时更新 UI。连接断开时应实现自动重连机制。
WS /ws/screen/{room_id}?token={access_token} 放映实时同步
连接地址
wss://onlygay.cn/ws/screen/{room_id}?token={access_token}
服务器推送事件
type说明
sync_state同步当前播放状态(加入时推送)
play播放
pause暂停
seek跳转进度
change_video切换视频
new_message放映房间新消息
user_joined用户加入
user_left用户离开
WS /ws/listen/{room_id}?token={access_token} 一起听实时同步
连接地址
wss://onlygay.cn/ws/listen/{room_id}?token={access_token}
服务器推送事件
type说明
sync_state同步当前播放状态(加入时推送)
play播放
pause暂停
seek跳转进度
change_music切换歌曲
change_mode切换播放模式
new_message一起听房间新消息
user_joined用户加入
user_left用户离开
📂

文件共享

支持文件夹目录结构管理,文件上传/下载/在线预览。文件权限独立设置,按用户粒度控制访问。无文件大小限制。

POST /api/folders 创建文件夹
需要认证
请求参数 (Body)
字段类型必填说明
namestring必填文件夹名称
parent_idint可选父文件夹 ID,为 null 时创建顶层文件夹
GET /api/folders 获取目录内容
需要认证
返回指定目录下的子文件夹和当前用户有权限访问的文件。
Query 参数
参数类型必填说明
parent_idint可选父文件夹 ID,不传则返回顶层
成功响应 200
{
  "code": 200,
  "message": "success",
  "data": {
    "folders": [
      { "id": 1, "name": "项目文档", "parent_id": null, "created_at": "..." }
    ],
    "files": [
      {
        "id": 1,
        "filename": "报告.pdf",
        "file_size": 1048576,
        "file_type": "application/pdf",
        "uploader": { "id": 1, "username": "zhangsan" },
        "created_at": "..."
      }
    ]
  }
}
PUT /api/folders/{folder_id} 重命名文件夹
需要认证
请求参数 (Body)
字段类型必填说明
namestring必填新文件夹名称
DELETE /api/folders/{folder_id} 删除文件夹
需要认证
注意:需确认文件夹内是否还有内容。若非空,可选择级联删除或返回错误提示。
POST /api/files/upload 上传文件
需要认证
请求参数 (multipart/form-data)
字段类型必填说明
filefile必填文件
folder_idint可选目标文件夹 ID,为空则上传到根目录
成功响应 200
{
  "code": 200,
  "message": "上传成功",
  "data": {
    "id": 1,
    "filename": "报告.pdf",
    "file_size": 1048576,
    "file_type": "application/pdf",
    "folder_id": 1
  }
}
说明:无文件大小限制。
GET /api/files/{file_id} 获取文件信息
需要认证
返回文件的元数据信息(名称、大小、类型、上传者、上传时间等)。
GET /api/files/{file_id}/download 下载文件
需要认证
权限:仅上传者或被授权用户可下载。
返回文件流,Content-Disposition 为 attachment。
GET /api/files/{file_id}/preview 在线预览文件
需要认证
支持图片、PDF、文档等常见格式的在线预览。返回对应内容流,Content-Disposition 为 inline。
DELETE /api/files/{file_id} 删除文件
需要认证
权限:仅上传者可删除。
PUT /api/files/{file_id}/move 移动文件到其他文件夹
需要认证
请求参数 (Body)
字段类型必填说明
folder_idint必填目标文件夹 ID
POST /api/files/{file_id}/permissions 添加文件访问权限
需要认证
为指定用户授予文件访问权限。
请求参数 (Body)
字段类型必填说明
usernamestring必填目标用户名
permissionstring必填权限:read(只读)/ read_write(读写)
GET /api/files/{file_id}/permissions 查看文件权限列表
需要认证
成功响应 200
{
  "code": 200,
  "message": "success",
  "data": [
    { "user_id": 2, "username": "lisi", "permission": "read" },
    { "user_id": 3, "username": "wangwu", "permission": "read_write" }
  ]
}
PUT /api/files/{file_id}/permissions/{user_id} 修改文件权限
需要认证
请求参数 (Body)
字段类型必填说明
permissionstring必填新权限:read / read_write
DELETE /api/files/{file_id}/permissions/{user_id} 移除文件权限
需要认证
移除指定用户对该文件的访问权限。
🎬

给给小窝(影音放映)

支持视频链接播放和 SRS 直播推流,所有人可控制播放/暂停/进度。放映房间内置实时聊天。支持外链解析(B站、YouTube等)。

POST /api/screen/rooms 创建放映房间
需要认证
请求参数 (Body)
字段类型必填说明
namestring必填房间名称
descriptionstring可选房间描述
GET /api/screen/rooms 放映房间列表
需要认证
GET /api/screen/rooms/{room_id} 放映房间详情
需要认证
DELETE /api/screen/rooms/{room_id} 删除放映房间
需要认证
权限:仅创建者或管理员可删除。
POST /api/screen/rooms/{room_id}/join 加入放映房间
需要认证
POST /api/screen/rooms/{room_id}/leave 退出放映房间
需要认证
POST /api/screen/rooms/{room_id}/video 设置视频
需要认证
请求参数 (Body)
字段类型必填说明
urlstring必填视频链接,支持直链和B站/YouTube等平台链接
说明:设置后通过 WebSocket 广播 change_video 事件。
GET /api/screen/parse 解析视频链接
需要认证
Query 参数
参数类型必填说明
urlstring必填要解析的视频链接
GET /api/screen/rooms/{room_id}/stream 视频流式代理
需要认证
Query 参数
参数类型必填说明
tokenstring必填JWT Token(通过 URL 参数传递,用于 <video src> 场景)
说明:实时转封装代理,支持 B站等 m4s 分段视频。直链直接转发,非直链走 yt-dlp + ffmpeg。返回 mp4 流,可直接赋给 <video src>。
用法:/api/screen/rooms/{room_id}/stream?token=你的token
POST /api/screen/rooms/{room_id}/play 播放
需要认证
POST /api/screen/rooms/{room_id}/pause 暂停
需要认证
POST /api/screen/rooms/{room_id}/seek 跳转进度
需要认证
请求参数 (Body)
字段类型必填说明
current_timeinteger必填目标时间点(秒)
POST /api/screen/rooms/{room_id}/live/start 开启直播
需要认证
返回 OBS 推流地址和浏览器播放地址。
响应示例
{
  "code": 0,
  "data": {
    "push_url": "rtmp://47.96.115.46:1935/live/room_1_xxx",
    "play_flv": "http://47.96.115.46:8080/live/room_1_xxx.flv",
    "play_hls": "http://47.96.115.46:8080/live/room_1_xxx.m3u8"
  }
}
POST /api/screen/rooms/{room_id}/live/stop 结束直播
需要认证
GET /api/screen/rooms/{room_id}/live/status 直播状态
需要认证
返回 is_live、is_streaming(SRS是否正在推流)。
GET /api/screen/rooms/{room_id}/messages 放映聊天历史
需要认证
POST /api/screen/rooms/{room_id}/messages 发送放映聊天
需要认证
请求参数 (Body)
字段类型必填说明
contentstring必填消息内容
🔗

网站导航

多级分类导航系统,支持分类管理、链接管理、搜索、点击统计和批量导入。前端只需调用 /api/nav/tree 一个接口即可获取全部数据。

🎵

音乐播放器

支持本地上传音乐(自动解析元数据/歌词/封面/颜色/BPM)和 GD API 在线搜索(网易/酷我/JOOX)。返回 Apple Music 风格的颜色数据和波形数据,前端可用于动态背景、频谱动画和进度条波形。

POST /api/music/upload 上传音乐
需要认证
上传音乐文件,自动解析 ID3 标签、内嵌歌词、内嵌封面,并进行音频分析(BPM/情绪/频谱/波形/颜色提取)。
请求参数 (multipart/form-data)
字段类型必填说明
filefile必填音频文件 mp3/flac/wav/ogg/m4a
titlestring可选歌曲名
artiststring可选歌手
albumstring可选专辑
lyricsstring可选LRC 歌词
响应示例
{
  "code": 0,
  "data": {
    "id": 1,
    "title": "晴天",
    "bpm": 76,
    "energy": 0.45,
    "mood": "melancholy",
    "spectrum": { "bass": 0.3, "mid": 0.6, "treble": 0.3 },
    "colors": { "primary": "#3a5f8a", "accent": "#ff8c42" },
    "waveform": [0.1, 0.3, 0.5, ...]
  }
}
前端提示:可用 colors 做 Apple Music 风格背景渐变,用 waveform 做进度条波形,用 mood 切换动画风格,用 bpm 控制动画速度。
GET /api/music/stream/{source}/{track_id} 获取在线播放链接
需要认证
一次性获取播放链接、封面 URL、LRC 歌词(含翻译)和颜色数据。缓存 10 分钟。
路径参数
参数类型必填说明
sourcestring必填netease/kuwo/joox
track_idstring必填曲目 ID
Query 参数
参数类型必填说明
brinteger可选音质:128/192/320/740/999,默认 320
pic_idstring可选封面图 ID
lyric_idstring可选歌词 ID
titlestring可选歌曲名(透传)
artiststring可选歌手名(透传)
响应示例
{
  "code": 0,
  "data": {
    "url": "https://...mp3",
    "cover_url": "https://...",
    "lyrics": [
      { "time": 0.0, "text": "故事的小黄花" },
      { "time": 3.5, "text": "从出生那年就飘着", "translation": "Since the year of birth" }
    ],
    "colors": { "primary": "#3a5f8a" }
  }
}
GET /api/music/cover/{source}/{pic_id} 获取封面图
需要认证
Query 参数
参数类型必填说明
sizeinteger可选300(默认小图)/ 500(大图)
GET /api/music/lyrics/{source}/{lyric_id} 获取歌词
需要认证
获取 LRC 歌词(含中文翻译),已解析为逐行结构。永久缓存。
GET /api/music/cache/stats 缓存统计
需要认证
查看 GD API 缓存命中情况。
GET /api/music/list 本地音乐列表
需要认证
Query 参数
参数类型必填说明
keywordstring可选按歌名或歌手搜索
moodstring可选按情绪筛选:cheerful/melancholy/calm/passionate/neutral
pageinteger可选页码
page_sizeinteger可选每页条数,默认 50
GET /api/music/{music_id} 音乐详情
需要认证
含解析后的歌词、颜色方案、波形数据、是否已心动。
GET /api/music/{music_id}/file 播放本地音乐
需要认证
直接返回音频文件流,供 audio 标签播放。Content-Type: audio/mpeg。
GET /api/music/{music_id}/cover 获取本地封面
需要认证
返回上传音乐时提取的内嵌封面。Content-Type: image/jpeg。
POST /api/music/{music_id}/play 记录播放
需要认证
播放时调用,累计播放次数并写入播放历史。
POST /api/music/play/online 记录在线播放
需要认证
请求参数 (Body)
字段类型必填说明
sourcestring必填音乐源
track_idstring必填曲目 ID
titlestring可选歌曲名
artiststring可选歌手
POST /api/music/{music_id}/like 心动
需要认证
标记为心动歌曲,重复心动返回 409。
DELETE /api/music/{music_id}/like 取消心动
需要认证
GET /api/music/heart/list 心动列表
需要认证
按心动时间倒序,每首歌含颜色和分析数据。
PUT /api/music/{music_id}/lyrics 更新歌词
需要认证
请求参数 (Body)
字段类型必填说明
lyricsstring必填LRC 格式歌词
GET /api/music/history/recent 最近播放
需要认证
最近 100 首播放记录,包含本地和在线音乐。
DELETE /api/music/{music_id} 删除音乐
需要认证
删除音乐文件、封面、心动记录和播放列表关联。
注意:不可恢复。
📋

播放列表

支持创建多个播放列表,可添加本地音乐。播放列表可公开或私有。播放模式:顺序/随机/心动/单曲循环/列表循环。

POST /api/playlists 创建播放列表
需要认证
请求参数 (Body)
字段类型必填说明
namestring必填播放列表名称
descriptionstring可选描述
is_publicboolean可选是否公开,默认 true
GET /api/playlists 播放列表列表
需要认证
返回自己创建的 + 所有公开的播放列表。
GET /api/playlists/{playlist_id} 播放列表详情
需要认证
含完整歌曲列表。
PUT /api/playlists/{playlist_id} 修改播放列表
需要认证
权限:仅创建者可修改。
DELETE /api/playlists/{playlist_id} 删除播放列表
需要认证
POST /api/playlists/{playlist_id}/add 添加歌曲到播放列表
需要认证
请求参数 (Body)
字段类型必填说明
music_idinteger必填本地音乐 ID
注意:重复添加返回 409。
DELETE /api/playlists/{playlist_id}/remove/{music_id} 从播放列表移除
需要认证
🎧

一起听

多人同步听歌房间。房主控制播放/暂停/切歌/进度,所有成员实时同步。房间内置实时聊天。支持 5 种播放模式。

POST /api/listen/rooms 创建一起听房间
需要认证
请求参数 (Body)
字段类型必填说明
namestring必填房间名称
descriptionstring可选房间描述
GET /api/listen/rooms 一起听房间列表
需要认证
当前用户所在的房间,含成员、当前播放歌曲和状态。
GET /api/listen/rooms/{room_id} 一起听房间详情
需要认证
POST /api/listen/rooms/{room_id}/join 加入一起听房间
需要认证
POST /api/listen/rooms/{room_id}/leave 退出一起听房间
需要认证
DELETE /api/listen/rooms/{room_id} 删除一起听房间
需要认证
权限:仅创建者或管理员可删除。
POST /api/listen/rooms/{room_id}/mode 设置播放模式
需要认证
请求参数 (Body)
字段类型必填说明
modestring必填sequential(顺序)/ random(随机)/ heart(心动)/ repeat_one(单曲循环)/ repeat_all(列表循环)
GET /api/listen/rooms/{room_id}/messages 一起听聊天历史
需要认证
🤖

给给助手(AI)

AI 智能助手,支持 7 种通用技能 + 5 种预留场景技能。支持普通返回和 SSE 流式返回(打字机效果)。使用小米 MiMo API(mimo-v2-flash),兼容 OpenAI 格式。所有对话记录持久化存储。

GET /api/ai/skills AI 技能列表
需要认证
获取所有可用的 AI 技能。通用技能可直接使用,场景技能标记为 disabled 预留后续开放。
响应示例
{
  "code": 0,
  "data": [
    { "key": "general", "name": "通用助手", "icon": "🤖", "disabled": false },
    { "key": "music", "name": "音乐助手", "icon": "🎵", "disabled": true }
  ]
}
POST /api/ai/conversations 创建 AI 对话
需要认证
请求参数 (Body)
字段类型必填说明
titlestring可选对话标题,默认"新对话"
skillstring可选技能标识,默认 general
响应示例
{ "code": 0, "data": { "id": 1, "title": "新对话", "skill": "general" } }
GET /api/ai/conversations 对话列表
需要认证
按更新时间倒序,含最后一条消息预览。
GET /api/ai/conversations/{conv_id} 对话详情
需要认证
含完整消息历史。
DELETE /api/ai/conversations/{conv_id} 删除对话
需要认证
注意:删除对话及所有消息,不可恢复。
POST /api/ai/conversations/{conv_id}/send 发送消息
需要认证
等待完整回复后返回。自动保留最近 20 条消息作为上下文。
请求参数 (Body)
字段类型必填说明
contentstring必填用户消息
skillstring可选切换技能
响应示例
{
  "code": 0,
  "data": {
    "user_message": { "id": 1, "role": "user", "content": "你好" },
    "ai_message": { "id": 2, "role": "assistant", "content": "你好!我是给给小助手🤖" }
  }
}
说明:发送第一条消息后,对话标题会自动更新。
POST /api/ai/conversations/{conv_id}/stream 发送消息(流式)
需要认证
SSE 流式返回回复(打字机效果)。
请求参数 (Body)
字段类型必填说明
contentstring必填用户消息
skillstring可选切换技能
SSE 响应示例
data: {"content": "你", "done": false}
data: {"content": "好", "done": false}
data: {"content": "", "done": true}
前端实现:通过 fetch + ReadableStream 接收。后端在流结束后自动保存完整回复。
POST /api/ai/quick 快速问答
需要认证
不创建对话,直接问 AI。适合场景内嵌使用。
请求参数 (Body)
字段类型必填说明
contentstring必填问题内容
skillstring可选技能标识,默认 general
POST /api/ai/quick/stream 快速问答(流式)
需要认证
快速问答的 SSE 流式版本,不保存对话记录。
GET /api/ai/config AI 配置信息
需要认证(仅管理员)
查看当前 AI 配置,不显示 API Key。
响应示例
{
  "code": 0,
  "data": {
    "api_base": "https://api.xiaomimimo.com/v1",
    "model": "mimo-v2-flash",
    "has_key": true,
    "skills_count": 12,
    "active_skills": 7
  }
}
📋

附录:权限矩阵

功能模块普通用户VIP管理员
注册 / 登录
设置在线状态
个性化设置
待办任务
聊天(群聊 / 私聊)
文件共享
影音放映
网站导航
音乐播放器
播放列表
一起听
给给助手(AI)
审核注册 / 用户管理
管理用户等级
解散聊天房间
删除放映房间
AI 配置信息
说明:模块级权限控制,管理员可按需通过调整用户等级来开关各模块的访问权限。
🚨

附录:错误码表

所有接口 HTTP 状态码始终返回 200,通过 body.code 区分结果:

body.code含义说明前端处理
0成功操作成功,data 返回业务数据正常处理 data
401未登录无 Token / Token 过期 / Token 无效跳转登录页
403无权限认证通过但无权限执行此操作弹出无权限提示
500业务错误参数错误、资源不存在、冲突等弹出 message 提示
前端判断示例
const { code, message, data } = response.data
if (code === 0)   return data        // 成功
if (code === 401) 跳转登录页         // 未登录
if (code === 403) 弹出无权限提示     // 无权限
if (code === 500) 弹出 message       // 业务错误