API 接口文档

后端 API 接口详细说明和使用示例

获取音乐列表
GET
/api/music/list

参数说明

参数名
类型
必填
说明
prefix
string
否
文件前缀（如: music/）
marker
string
否
分页标记
limit
number
否
返回数量限制（默认50）
getInfo
boolean
否
是否获取音频详细信息（默认true）

请求示例

/api/music/list?prefix=&marker=&limit=50
获取单个音乐信息
GET
/api/music/info

参数说明

参数名
类型
必填
说明
key
string
是
文件键名

请求示例

/api/music/info?key=music/song.mp3
批量获取音乐信息
POST
/api/music/batch

参数说明

参数名
类型
必填
说明
keys
string[]
是
文件键名数组

请求示例

POST /api/music/batch
Body:
{
  "keys": [
    "music/song1.mp3",
    "music/song2.mp3"
  ]
}
获取标题列表
GET
/api/titles/list

参数说明

参数名
类型
必填
说明
useRemoteTitles
boolean
否
是否使用远程标题（默认true）
v
string
否
版本号（ETag）用于缓存控制

请求示例

/api/titles/list?useRemoteTitles=true&v=FkMETNiQ
获取标题版本
GET
/api/titles/version

请求示例

/api/titles/version
生成标题
POST
/api/titles/generate

请求示例

POST /api/titles/generate
Body:
上传标题
POST
/api/titles/upload
参数说明
参数名
类型
必填
说明
titles
Record<string, string>
是
文件级标题映射
categories
Record<string, string>
是
目录级标题映射
请求示例
POST /api/titles/upload
Body:
{
  "titles": {
    "audio/song.mp3": "歌曲名称"
  },
  "categories": {
    "audio/": "音频目录"
  }
}
健康检查
GET
/api/health
请求示例
/api/health
使用说明
认证
所有 API 接口都需要在服务器端配置正确的七牛云凭证（QINIU_ACCESS_KEY 和 QINIU_SECRET_KEY）。
响应格式
所有 API 接口返回 JSON 格式数据，包含 success 字段表示请求是否成功。
错误处理
当请求失败时，响应中会包含 error 字段，描述错误信息。
缓存控制
标题相关的 API 支持通过 v 参数（ETag）进行缓存控制，确保获取最新数据。