🔌 开发接口
RESTful API 接口文档，方便开发者集成使用
📋 基础信息
Base URL
/api/v1
字符编码
UTF-8
请求格式
JSON
响应格式
JSON
📦 通用响应结构
{ "code": 200, "message": "success", "data": {}, "timestamp": 1713427200000 }
返回参数说明
| 参数名 | 类型 | 示例值 | 说明 |
|---|---|---|---|
| code | int | 200 | HTTP 状态码 |
| message | string | "success" | 状态消息 |
| data | object/array | {} | 返回数据主体 |
| timestamp | number | 1713427200000 | 响应时间戳（毫秒） |
🎵 数据模型 - Cover 作品
| 参数名 | 类型 | 示例值 | 说明 |
|---|---|---|---|
| id | number | 1 | 作品唯一ID |
| title | string | "湘女多情" | 作品标题 |
| description | string | "歌曲描述" | 作品描述 |
| category | string | "流行" | 分类 |
| tags | array | ["翻唱"] | 标签数组 |
| bilibili_url | string | "https://..." | B站视频链接 |
| audio_url | string | "/uploads/..." | 音频文件路径 |
| thumbnail_url | string | "http://..." | 封面缩略图 |
| created_at | string | "2026-04-11T..." | 创建时间 ISO 8601 |
🔢 状态码说明
200
请求成功
400
请求参数错误
404
资源不存在
500
服务器内部错误
🚀 接口详情
GET
/covers
获取翻唱作品列表
支持分页、分类筛选、标签筛选和排序
请求参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| page | int | 否 | 1 | 页码 |
| page_size | int | 否 | 10 | 每页数量（最大50） |
| category | string | 否 | - | 分类筛选 |
| tag | string | 否 | - | 标签筛选 |
| sort | string | 否 | newest | newest/oldest/title/title-desc |
| keyword | string | 否 | - | 标题/描述关键词搜索 |
返回参数
| 参数 | 类型 | 说明 |
|---|---|---|
| total | number | 符合条件的总记录数 |
| page | number | 当前页码 |
| page_size | number | 每页数量 |
| total_pages | number | 总页数 |
| list | Cover[] | 作品列表数组（见 Cover 数据模型） |
返回示例
{ "code": 200, "message": "success", "data": { "total": 10, "page": 1, "page_size": 3, "total_pages": 4, "list": [ // Cover 作品对象 ] }, "timestamp": 1776460832465 }
GET
/covers/{id}
获取单个作品详情
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | number | 是 | 作品ID |
返回参数
返回单个 Cover 作品对象（见上方数据模型）
错误响应 - 作品不存在
{ "code": 404, "message": "作品不存在", "data": null, "timestamp": 1776460832465 }
GET
/covers/categories
获取分类列表及统计
返回参数
| 参数 | 类型 | 说明 |
|---|---|---|
| categories | array | 分类统计数组 |
| categories[].name | string | 分类名称 |
| categories[].count | number | 该分类作品数量 |
返回示例
{ "code": 200, "message": "success", "data": { "categories": [ { "name": "流行", "count": 9 }, { "name": "古风", "count": 1 } ] }, "timestamp": 1776460832465 }
GET
/covers/tags
获取标签列表及统计
返回参数
| 参数 | 类型 | 说明 |
|---|---|---|
| tags | array | 标签统计数组（按次数倒序排列） |
| tags[].name | string | 标签名称 |
| tags[].count | number | 该标签作品数量 |
返回示例
{ "code": 200, "message": "success", "data": { "tags": [ { "name": "翻唱", "count": 9 }, { "name": "经典", "count": 1 } ] }, "timestamp": 1776460832465 }
GET
/bilibili-fans
获取B站实时粉丝数
调用B站开放API获取咻咻满（UID: 37754047）的实时粉丝关注数据
返回参数
| 参数 | 类型 | 说明 |
|---|---|---|
| code | number | 状态码 200 |
| follower | number | 粉丝数（精确值） |
| following | number | 关注数 |
返回示例
{ "code": 200, "message": "success", "data": { "follower": 1234567, "following": 123 }, "timestamp": 1776460832465 }
GET
/covers/search
搜索作品（标题、描述、标签）
请求参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| q | string | 是 | - | 搜索关键词 |
| page | int | 否 | 1 | 页码 |
| page_size | int | 否 | 10 | 每页数量（最大50） |
返回参数
| 参数 | 类型 | 说明 |
|---|---|---|
| total | number | 搜索结果总数 |
| page | number | 当前页码 |
| page_size | number | 每页数量 |
| list | Cover[] | 匹配的作品列表 |
错误响应 - 缺少搜索词
{ "code": 400, "message": "请提供搜索关键词", "data": null, "timestamp": 1776460832465 }
⚡ 接口速查表
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/v1/covers |
获取作品列表（分页+筛选+排序+搜索） |
| GET | /api/v1/covers/{id} |
获取单个作品详情 |
| GET | /api/v1/covers/categories |
获取所有分类及统计数 |
| GET | /api/v1/covers/tags |
获取所有标签及统计数 |
| GET | /api/v1/covers/search |
搜索标题、描述、标签 |
| GET | /api/v1/download/single/{id} |
下载单个音频文件 |
| GET | /api/v1/download/all |
打包下载所有音频 |
| GET | /api/download-batch |
批量下载选中的音频 |
GET
/download/single/{id}
下载单个音频文件
根据作品ID下载单个音频文件，文件名即为歌曲标题
路径参数
| 参数 | 类型 | 说明 |
|---|---|---|
| id | number | 作品ID（必填） |
成功响应
返回音频文件流，Content-Type为音频类型（如 audio/mpeg）
失败响应
{ "code": 404, "message": "音频不存在", "data": null, "timestamp": 1776460832465 }
GET
/download/all
打包下载所有音频
将所有有音频的作品打包为ZIP文件下载，每个文件名即为对应歌曲标题
成功响应
返回ZIP文件流，Content-Type为 application/zip
失败响应
{ "code": 400, "message": "没有可用的音频", "data": null, "timestamp": 1776460832465 }
GET
/download-batch
批量下载选中音频
根据选中的作品ID列表，打包下载多个音频文件（配合下载页面复选框使用）
查询参数
| 参数 | 类型 | 说明 |
|---|---|---|
| ids | string | 作品ID列表，逗号分隔（必填），如 `1,3,5` |
成功响应
返回ZIP文件流，Content-Type为 application/zip
失败响应
{ "code": 400, "message": "请选择要下载的音频", "data": null, "timestamp": 1776460832465 }