给给窝
后端 API 接口文档
本文档指向Congreat233,提供不完整的后端 API 接口定义、请求/响应格式、参数说明和错误码参考。随时维护,建议使用。
基础地址
https://onlygay.cn/api
WebSocket
wss://onlygay.cn/ws/chat/{room_id}?token={access_token}
统一响应格式:所有接口返回统一的三段式 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_token | 2 小时 | API 请求认证 |
| refresh_token | 7 天 | 刷新 access_token |
| remember_token | 30 天 | "记住密码" 自动登录 |
用户等级说明
| 等级 | 标识 | 说明 |
| 普通用户 | normal | 基础功能权限 |
| VIP 用户 | vip | 高级功能权限 |
| 管理员 | admin | 全部功能 + 管理后台 |
账号状态说明
| 状态 | 标识 | 说明 |
| 待审核 | pending | 注册后等待管理员审核 |
| 已激活 | active | 正常使用 |
| 已拒绝 | rejected | 注册被拒绝 |
| 已禁用 | disabled | 账号被管理员禁用 |
在线状态说明
| 状态 | 标识 | 说明 |
| 在线 | online | 登录后默认状态 |
| 离线 | offline | 退出登录后自动切换 |
| 忙碌 | busy | 用户手动选择 |
用户注册、登录、退出及个人信息管理。注册需管理员审核后方可登录。
用户提交注册申请,创建后账号状态为 pending,需管理员审核激活。
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| username | string | 必填 | 用户名,唯一 |
| email | string | 必填 | 邮箱地址,唯一 |
| password | string | 必填 | 密码 |
请求示例
{
"username": "zhangsan",
"email": "zhangsan@example.com",
"password": "SecurePass123"
}
成功响应 200
{
"code": 200,
"message": "注册申请已提交,请等待管理员审核",
"data": {
"username": "zhangsan",
"email": "zhangsan@example.com"
}
}
账号状态必须为 active 才能登录。登录成功后自动将 online_status 设为 online。
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| username | string | 必填 | 用户名 |
| password | string | 必填 | 密码 |
| remember_me | boolean | 可选 | 是否记住登录(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 用于后续请求。
用 refreshToken 换取新的 accessToken,用于延长登录状态。
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| refreshToken | string | 必填 | 刷新令牌 |
请求示例
{
"refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}
成功响应 200
{
"code": 200,
"message": "Token已刷新",
"data": {
"accessToken": "eyJhbGciOiJIUzI1NiIs...",
"refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}
}
退出登录,同时将 online_status 自动设为 offline,清除相关 Cookie。
需要认证
成功响应 200
{ "code": 200, "message": "已退出登录", "data": null }
需要认证
成功响应 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"
}
}
需要认证
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| username | string | 可选 | 新用户名 |
| email | string | 可选 | 新邮箱 |
需要认证
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| old_password | string | 必填 | 原密码 |
| new_password | string | 必填 | 新密码 |
登录后可手动选择在线状态(在线/忙碌),退出登录后自动设为离线。可查看所有成员的在线状态。
需要认证
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| status | string | 必填 | 可选值:online / offline / busy |
需要认证
成功响应 200
{
"code": 200,
"message": "success",
"data": [
{ "user_id": 1, "username": "zhangsan", "online_status": "online" },
{ "user_id": 2, "username": "lisi", "online_status": "busy" }
]
}
主题(深色/浅色)和页面布局配置均后端持久化存储,支持跨设备同步。
需要认证
成功响应 200
{
"code": 200,
"message": "success",
"data": {
"theme": "dark",
"layout_config": {
"sidebar_position": "left",
"modules": ["todo", "chat", "files"]
}
}
}
需要认证
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| theme | string | 可选 | 可选值:dark / light |
| layout_config | object | 可选 | 页面布局配置 JSON 对象 |
仅限 admin 等级用户访问。用于审核注册申请、管理用户等级和账号状态。
权限要求:所有管理员接口均需要 level = admin,否则返回 403 无权限。
仅管理员
Query 参数
| 参数 | 类型 | 必填 | 说明 |
| status | string | 可选 | 按状态筛选:pending / active / rejected / disabled |
| level | string | 可选 | 按等级筛选:normal / vip / admin |
| keyword | string | 可选 | 按用户名或邮箱模糊搜索 |
| page | int | 可选 | 页码,默认 1 |
| page_size | int | 可选 | 每页条数,默认 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"
}
]
}
}
仅管理员
将用户状态从 pending 设为 active,激活该账号。
成功响应 200
{ "code": 200, "message": "已激活该账号", "data": null }
仅管理员
将用户状态从 pending 设为 rejected。
仅管理员
等级由管理员固定分配,用户不可自行修改。
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| level | string | 必填 | 可选值:normal / vip / admin |
仅管理员
将用户状态设为 disabled,该用户将无法登录。
扁平化待办列表,支持截止日期、优先级、标签、备注。可通过用户名分享给指定人员,权限可选只读或编辑。
需要认证
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| title | string | 必填 | 待办标题 |
| content | string | 可选 | 备注内容 |
| deadline | datetime | 可选 | 截止日期,ISO 8601 格式 |
| priority | string | 可选 | 优先级:low / medium / high / urgent |
| tags | array | 可选 | 标签数组,如 ["工作","紧急"] |
请求示例
{
"title": "完成项目文档",
"content": "需要包含API接口说明",
"deadline": "2025-02-01T18:00:00",
"priority": "high",
"tags": ["工作", "紧急"]
}
需要认证
返回本人创建的 + 被分享给本人的所有待办。
Query 参数
| 参数 | 类型 | 必填 | 说明 |
| is_completed | boolean | 可选 | 按完成状态筛选 |
| priority | string | 可选 | 按优先级筛选 |
| tag | string | 可选 | 按标签筛选 |
| keyword | string | 可选 | 按标题模糊搜索 |
| page | int | 可选 | 页码,默认 1 |
| page_size | int | 可选 | 每页条数,默认 20 |
需要认证
权限:仅创建者或被授予 edit 权限的用户可修改。
请求参数 (Body,部分更新)
| 字段 | 类型 | 必填 | 说明 |
| title | string | 可选 | 新标题 |
| content | string | 可选 | 新备注 |
| deadline | datetime | 可选 | 新截止日期,设为 null 可清除 |
| priority | string | 可选 | 新优先级 |
| tags | array | 可选 | 新标签数组 |
| is_completed | boolean | 可选 | 完成状态 |
需要认证
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| username | string | 必填 | 目标用户名 |
| permission | string | 必填 | 权限:read(只读)/ edit(可编辑) |
需要认证
成功响应 200
{
"code": 200,
"message": "success",
"data": [
{ "user_id": 2, "username": "lisi", "permission": "read" },
{ "user_id": 3, "username": "wangwu", "permission": "edit" }
]
}
需要认证
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| permission | string | 必填 | 新权限:read / edit |
支持公共群聊房间和一对一私聊双模式。消息支持撤回(5分钟内)、点赞、表情包。实时通信通过 WebSocket 实现。
需要认证
创建群聊房间,创建者自动加入。
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| name | string | 必填 | 房间名称 |
| description | string | 可选 | 房间描述 |
需要认证
Query 参数
| 参数 | 类型 | 必填 | 说明 |
| room_type | string | 可选 | 按类型筛选:group / private |
| keyword | string | 可选 | 按房间名搜索 |
需要认证
返回房间详情,包含成员列表及各成员在线状态。
成功响应 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"
}
}
需要认证
权限:仅房间创建者或管理员可操作。
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| name | string | 可选 | 新房间名 |
| description | string | 可选 | 新描述 |
需要认证
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| username | string | 必填 | 目标用户名 |
需要认证
Query 参数
| 参数 | 类型 | 必填 | 说明 |
| page | int | 可选 | 页码 |
| page_size | int | 可选 | 每页条数,默认 50 |
| before_id | int | 可选 | 获取此 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 即可加载更早的消息。
需要认证
通过 REST 发送消息。实际场景中推荐使用 WebSocket 实时发送,此接口可作为备选方案。
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| content | string | 必填 | 消息内容 |
| message_type | string | 必填 | 消息类型:text / emoji / image |
需要认证
权限:仅消息发送者可撤回,且发送时间需在 5 分钟以内。撤回后通过 WebSocket 广播撤回事件。
成功响应 200
{ "code": 200, "message": "消息已撤回", "data": null }
前端处理:收到 WebSocket 的 message_recalled 事件后,将对应消息显示为"该消息已撤回"。
需要认证
对单条消息点赞。点赞后通过 WebSocket 广播点赞事件。
需要认证
若与目标用户已存在私聊房间则直接返回,否则自动创建。
成功响应 200
{
"code": 200,
"message": "success",
"data": {
"id": 5,
"room_type": "private",
"members": [
{ "user_id": 1, "username": "zhangsan" },
{ "user_id": 2, "username": "lisi" }
]
}
}
需要认证
请求参数 (multipart/form-data)
| 字段 | 类型 | 必填 | 说明 |
| name | string | 必填 | 表情名称 |
| file | file | 必填 | 图片文件 |
聊天、放映、一起听三个模块的实时通道。连接时需传 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。连接断开时应实现自动重连机制。
连接地址
wss://onlygay.cn/ws/screen/{room_id}?token={access_token}
服务器推送事件
| type | 说明 |
| sync_state | 同步当前播放状态(加入时推送) |
| play | 播放 |
| pause | 暂停 |
| seek | 跳转进度 |
| change_video | 切换视频 |
| new_message | 放映房间新消息 |
| user_joined | 用户加入 |
| user_left | 用户离开 |
连接地址
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 | 用户离开 |
支持文件夹目录结构管理,文件上传/下载/在线预览。文件权限独立设置,按用户粒度控制访问。无文件大小限制。
需要认证
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| name | string | 必填 | 文件夹名称 |
| parent_id | int | 可选 | 父文件夹 ID,为 null 时创建顶层文件夹 |
需要认证
返回指定目录下的子文件夹和当前用户有权限访问的文件。
Query 参数
| 参数 | 类型 | 必填 | 说明 |
| parent_id | int | 可选 | 父文件夹 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": "..."
}
]
}
}
需要认证
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| name | string | 必填 | 新文件夹名称 |
需要认证
注意:需确认文件夹内是否还有内容。若非空,可选择级联删除或返回错误提示。
需要认证
请求参数 (multipart/form-data)
| 字段 | 类型 | 必填 | 说明 |
| file | file | 必填 | 文件 |
| folder_id | int | 可选 | 目标文件夹 ID,为空则上传到根目录 |
成功响应 200
{
"code": 200,
"message": "上传成功",
"data": {
"id": 1,
"filename": "报告.pdf",
"file_size": 1048576,
"file_type": "application/pdf",
"folder_id": 1
}
}
说明:无文件大小限制。
需要认证
返回文件的元数据信息(名称、大小、类型、上传者、上传时间等)。
需要认证
权限:仅上传者或被授权用户可下载。
返回文件流,Content-Disposition 为 attachment。
需要认证
支持图片、PDF、文档等常见格式的在线预览。返回对应内容流,Content-Disposition 为 inline。
需要认证
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| folder_id | int | 必填 | 目标文件夹 ID |
需要认证
为指定用户授予文件访问权限。
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| username | string | 必填 | 目标用户名 |
| permission | string | 必填 | 权限:read(只读)/ read_write(读写) |
需要认证
成功响应 200
{
"code": 200,
"message": "success",
"data": [
{ "user_id": 2, "username": "lisi", "permission": "read" },
{ "user_id": 3, "username": "wangwu", "permission": "read_write" }
]
}
需要认证
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| permission | string | 必填 | 新权限:read / read_write |
支持视频链接播放和 SRS 直播推流,所有人可控制播放/暂停/进度。放映房间内置实时聊天。支持外链解析(B站、YouTube等)。
需要认证
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| name | string | 必填 | 房间名称 |
| description | string | 可选 | 房间描述 |
需要认证
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| url | string | 必填 | 视频链接,支持直链和B站/YouTube等平台链接 |
说明:设置后通过 WebSocket 广播 change_video 事件。
需要认证
Query 参数
| 参数 | 类型 | 必填 | 说明 |
| url | string | 必填 | 要解析的视频链接 |
需要认证
Query 参数
| 参数 | 类型 | 必填 | 说明 |
| token | string | 必填 | JWT Token(通过 URL 参数传递,用于 <video src> 场景) |
说明:实时转封装代理,支持 B站等 m4s 分段视频。直链直接转发,非直链走 yt-dlp + ffmpeg。返回 mp4 流,可直接赋给 <video src>。
用法:/api/screen/rooms/{room_id}/stream?token=你的token
需要认证
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| current_time | integer | 必填 | 目标时间点(秒) |
需要认证
返回 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"
}
}
需要认证
返回 is_live、is_streaming(SRS是否正在推流)。
需要认证
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| content | string | 必填 | 消息内容 |
多级分类导航系统,支持分类管理、链接管理、搜索、点击统计和批量导入。前端只需调用 /api/nav/tree 一个接口即可获取全部数据。
需要认证
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| name | string | 必填 | 分类名称 |
| icon | string | 可选 | 图标 emoji |
| parent_id | integer | 可选 | 父分类 ID |
需要认证
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| category_id | integer | 必填 | 所属分类 ID |
| title | string | 必填 | 网站名称 |
| url | string | 必填 | 网站链接 |
| description | string | 可选 | 描述 |
| icon | string | 可选 | 图标 |
需要认证
Query 参数
| 参数 | 类型 | 必填 | 说明 |
| category_id | integer | 可选 | 按分类筛选 |
| keyword | string | 可选 | 按标题搜索 |
需要认证
一次返回所有分类和链接的树形结构。前端渲染导航页面只需这一个接口。
响应示例
[{
"id": 1,
"name": "影视",
"icon": "🎬",
"children": [...],
"links": [...]
}]
需要认证
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| links | array | 必填 | [{"category_id":5,"title":"网站名","url":"https://..."}] |
支持本地上传音乐(自动解析元数据/歌词/封面/颜色/BPM)和 GD API 在线搜索(网易/酷我/JOOX)。返回 Apple Music 风格的颜色数据和波形数据,前端可用于动态背景、频谱动画和进度条波形。
需要认证
上传音乐文件,自动解析 ID3 标签、内嵌歌词、内嵌封面,并进行音频分析(BPM/情绪/频谱/波形/颜色提取)。
请求参数 (multipart/form-data)
| 字段 | 类型 | 必填 | 说明 |
| file | file | 必填 | 音频文件 mp3/flac/wav/ogg/m4a |
| title | string | 可选 | 歌曲名 |
| artist | string | 可选 | 歌手 |
| album | string | 可选 | 专辑 |
| lyrics | string | 可选 | 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 控制动画速度。
需要认证
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| title | string | 必填 | 歌曲名 |
| url | string | 必填 | 在线播放链接 |
| artist | string | 可选 | 歌手 |
| cover_url | string | 可选 | 封面 URL |
需要认证
通过 GD Music API 搜索在线音乐,结果缓存 30 分钟。
Query 参数
| 参数 | 类型 | 必填 | 说明 |
| keyword | string | 必填 | 搜索关键词 |
| source | string | 可选 | 音乐源:netease/kuwo/joox,默认 netease |
| count | integer | 可选 | 每页条数,默认 20 |
| pages | integer | 可选 | 页码,默认 1 |
响应示例
{
"code": 0,
"data": {
"total": 20,
"source": "netease",
"items": [{
"id": "12345",
"name": "晴天",
"artist": "周杰伦",
"album": "叶惠美",
"cover_url": "https://..."
}]
}
}
说明:搜索到的 id 即 track_id,可用于获取播放链接。GD API 限制 5 分钟内不超 50 次请求,后端已做缓存。
需要认证
一次性获取播放链接、封面 URL、LRC 歌词(含翻译)和颜色数据。缓存 10 分钟。
路径参数
| 参数 | 类型 | 必填 | 说明 |
| source | string | 必填 | netease/kuwo/joox |
| track_id | string | 必填 | 曲目 ID |
Query 参数
| 参数 | 类型 | 必填 | 说明 |
| br | integer | 可选 | 音质:128/192/320/740/999,默认 320 |
| pic_id | string | 可选 | 封面图 ID |
| lyric_id | string | 可选 | 歌词 ID |
| title | string | 可选 | 歌曲名(透传) |
| artist | string | 可选 | 歌手名(透传) |
响应示例
{
"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" }
}
}
需要认证
Query 参数
| 参数 | 类型 | 必填 | 说明 |
| size | integer | 可选 | 300(默认小图)/ 500(大图) |
需要认证
获取 LRC 歌词(含中文翻译),已解析为逐行结构。永久缓存。
需要认证
Query 参数
| 参数 | 类型 | 必填 | 说明 |
| keyword | string | 可选 | 按歌名或歌手搜索 |
| mood | string | 可选 | 按情绪筛选:cheerful/melancholy/calm/passionate/neutral |
| page | integer | 可选 | 页码 |
| page_size | integer | 可选 | 每页条数,默认 50 |
需要认证
含解析后的歌词、颜色方案、波形数据、是否已心动。
需要认证
直接返回音频文件流,供 audio 标签播放。Content-Type: audio/mpeg。
需要认证
返回上传音乐时提取的内嵌封面。Content-Type: image/jpeg。
需要认证
播放时调用,累计播放次数并写入播放历史。
需要认证
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| source | string | 必填 | 音乐源 |
| track_id | string | 必填 | 曲目 ID |
| title | string | 可选 | 歌曲名 |
| artist | string | 可选 | 歌手 |
需要认证
按心动时间倒序,每首歌含颜色和分析数据。
需要认证
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| lyrics | string | 必填 | LRC 格式歌词 |
需要认证
最近 100 首播放记录,包含本地和在线音乐。
需要认证
删除音乐文件、封面、心动记录和播放列表关联。
注意:不可恢复。
支持创建多个播放列表,可添加本地音乐。播放列表可公开或私有。播放模式:顺序/随机/心动/单曲循环/列表循环。
需要认证
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| name | string | 必填 | 播放列表名称 |
| description | string | 可选 | 描述 |
| is_public | boolean | 可选 | 是否公开,默认 true |
需要认证
返回自己创建的 + 所有公开的播放列表。
需要认证
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| music_id | integer | 必填 | 本地音乐 ID |
注意:重复添加返回 409。
多人同步听歌房间。房主控制播放/暂停/切歌/进度,所有成员实时同步。房间内置实时聊天。支持 5 种播放模式。
需要认证
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| name | string | 必填 | 房间名称 |
| description | string | 可选 | 房间描述 |
需要认证
当前用户所在的房间,含成员、当前播放歌曲和状态。
需要认证
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| mode | string | 必填 | sequential(顺序)/ random(随机)/ heart(心动)/ repeat_one(单曲循环)/ repeat_all(列表循环) |
AI 智能助手,支持 7 种通用技能 + 5 种预留场景技能。支持普通返回和 SSE 流式返回(打字机效果)。使用小米 MiMo API(mimo-v2-flash),兼容 OpenAI 格式。所有对话记录持久化存储。
需要认证
获取所有可用的 AI 技能。通用技能可直接使用,场景技能标记为 disabled 预留后续开放。
响应示例
{
"code": 0,
"data": [
{ "key": "general", "name": "通用助手", "icon": "🤖", "disabled": false },
{ "key": "music", "name": "音乐助手", "icon": "🎵", "disabled": true }
]
}
需要认证
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| title | string | 可选 | 对话标题,默认"新对话" |
| skill | string | 可选 | 技能标识,默认 general |
响应示例
{ "code": 0, "data": { "id": 1, "title": "新对话", "skill": "general" } }
需要认证
等待完整回复后返回。自动保留最近 20 条消息作为上下文。
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| content | string | 必填 | 用户消息 |
| skill | string | 可选 | 切换技能 |
响应示例
{
"code": 0,
"data": {
"user_message": { "id": 1, "role": "user", "content": "你好" },
"ai_message": { "id": 2, "role": "assistant", "content": "你好!我是给给小助手🤖" }
}
}
说明:发送第一条消息后,对话标题会自动更新。
需要认证
SSE 流式返回回复(打字机效果)。
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| content | string | 必填 | 用户消息 |
| skill | string | 可选 | 切换技能 |
SSE 响应示例
data: {"content": "你", "done": false}
data: {"content": "好", "done": false}
data: {"content": "", "done": true}
前端实现:通过 fetch + ReadableStream 接收。后端在流结束后自动保存完整回复。
需要认证
不创建对话,直接问 AI。适合场景内嵌使用。
请求参数 (Body)
| 字段 | 类型 | 必填 | 说明 |
| content | string | 必填 | 问题内容 |
| skill | string | 可选 | 技能标识,默认 general |
需要认证
快速问答的 SSE 流式版本,不保存对话记录。
需要认证(仅管理员)
查看当前 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 // 业务错误