标签管理

接口列表

方法	路径	说明
POST	/song-tags	创建标签
GET	/song-tags	列出所有标签
PUT	/song-tags/{id}	更新标签
DELETE	/song-tags/{id}	删除标签
GET	/song-tags/{id}	获取标签详情
POST	/song-tags/{id}/bind	批量绑定歌曲到标签
GET	/song-tags/{id}/song-ids	获取标签下所有歌曲 ID
GET	/song-tags/{id}/songs	获取标签下的歌曲列表
POST	/song-tags/{id}/unbind	批量解绑歌曲
PUT	/songs/{id}/song-tags	设置歌曲的标签
GET	/songs/{id}/song-tags	获取歌曲的自定义标签

POST /song-tags

创建标签

创建一个新的自定义标签。标签名不能为空、不能包含逗号、不能超过50个字符。标签名大小写不敏感去重。

需要认证

此接口需要 Bearer Token 认证

请求体

创建参数 {name: string, color?: string}

类型： object

响应

201 - 创建成功

类型： SongTag

字段	类型	必填	说明
color	string	否
cover_url	string	否
created_at	string	否
id	integer	否
name	string	否
song_count	integer	否

400 - 参数错误

类型： map[string]string

500 - 服务器错误

类型： map[string]string

内容类型

• 请求： application/json
• 响应： application/json

---

GET /song-tags

列出所有标签

返回标签列表，含每个标签下的歌曲数量和代表封面。支持关键词搜索、排序和分页。

需要认证

此接口需要 Bearer Token 认证

查询参数

参数	类型	必填	说明
keyword	string	否	搜索关键词（模糊匹配标签名）
sort	string	否	排序字段 可选值: song_count, name, created_at 默认: "song_count"
order	string	否	排序方向 可选值: asc, desc 默认: "desc"
limit	integer	否	每页数量 默认: 60
offset	integer	否	偏移量 默认: 0

响应

200 - 成功返回标签列表 {tags, total, limit, offset}

类型： map[string]any

500 - 服务器错误

类型： map[string]string

内容类型

• 响应： application/json

---

PUT /song-tags/{id}

更新标签

更新标签名称或颜色。

需要认证

此接口需要 Bearer Token 认证

路径参数

参数	类型	必填	说明
id	integer	是	标签 ID

请求体

更新参数 {name?: string, color?: string}

类型： object

响应

204 - 更新成功

400 - 参数错误

类型： map[string]string

404 - 标签不存在

类型： map[string]string

内容类型

• 请求： application/json
• 响应： application/json

---

DELETE /song-tags/{id}

删除标签

删除标签，自动解除所有歌曲关联（CASCADE）。歌曲本身不会被删除。

需要认证

此接口需要 Bearer Token 认证

路径参数

参数	类型	必填	说明
id	integer	是	标签 ID

响应

204 - 删除成功

400 - 参数错误

类型： map[string]string

内容类型

• 响应： application/json

---

GET /song-tags/{id}

获取标签详情

返回单个标签的详细信息，包含歌曲数量。

需要认证

此接口需要 Bearer Token 认证

路径参数

参数	类型	必填	说明
id	integer	是	标签 ID

响应

200 - 成功

类型： SongTag

字段	类型	必填	说明
color	string	否
cover_url	string	否
created_at	string	否
id	integer	否
name	string	否
song_count	integer	否

404 - 标签不存在

类型： map[string]string

内容类型

• 响应： application/json

---

POST /song-tags/{id}/bind

批量绑定歌曲到标签

将多首歌曲关联到指定标签。已存在的关联会被忽略。

需要认证

此接口需要 Bearer Token 认证

路径参数

参数	类型	必填	说明
id	integer	是	标签 ID

请求体

歌曲 ID 列表 {song_ids: [1,2,3]}

类型： object

响应

200 - 绑定结果 {bound: N}

类型： map[string]integer

400 - 参数错误

类型： map[string]string

500 - 服务器错误

类型： map[string]string

内容类型

• 请求： application/json
• 响应： application/json

---

GET /song-tags/{id}/song-ids

获取标签下所有歌曲 ID

返回某个标签关联的所有歌曲 ID 列表，不分页，用于播放全部场景。

需要认证

此接口需要 Bearer Token 认证

路径参数

参数	类型	必填	说明
id	integer	是	标签 ID

响应

200 - 歌曲 ID 列表

类型： integer[]

400 - 参数错误

类型： map[string]string

500 - 服务器错误

类型： map[string]string

内容类型

• 响应： application/json

---

GET /song-tags/{id}/songs

获取标签下的歌曲列表

返回某个标签关联的歌曲列表，支持分页。

需要认证

此接口需要 Bearer Token 认证

路径参数

参数	类型	必填	说明
id	integer	是	标签 ID

查询参数

参数	类型	必填	说明
limit	integer	否	每页数量 默认: 100
offset	integer	否	偏移量 默认: 0

响应

200 - 成功返回 {songs, total, limit, offset}

类型： map[string]any

400 - 参数错误

类型： map[string]string

500 - 服务器错误

类型： map[string]string

内容类型

• 响应： application/json

---

POST /song-tags/{id}/unbind

批量解绑歌曲

将多首歌曲从指定标签中移除关联。

需要认证

此接口需要 Bearer Token 认证

路径参数

参数	类型	必填	说明
id	integer	是	标签 ID

请求体

歌曲 ID 列表 {song_ids: [1,2,3]}

类型： object

响应

200 - 解绑结果 {unbound: N}

类型： map[string]integer

400 - 参数错误

类型： map[string]string

500 - 服务器错误

类型： map[string]string

内容类型

• 请求： application/json
• 响应： application/json

---

PUT /songs/{id}/song-tags

设置歌曲的标签

全量替换歌曲的自定义标签关联。传入 tag_ids 数组，替换当前所有关联。

需要认证

此接口需要 Bearer Token 认证

路径参数

参数	类型	必填	说明
id	integer	是	歌曲 ID

请求体

标签 ID 列表 {tag_ids: [1,2,3]}

类型： object

响应

204 - 设置成功

400 - 参数错误

类型： map[string]string

500 - 服务器错误

类型： map[string]string

内容类型

• 请求： application/json
• 响应： application/json

---

GET /songs/{id}/song-tags

获取歌曲的自定义标签

返回某首歌曲关联的所有自定义标签列表。

需要认证

此接口需要 Bearer Token 认证

路径参数

参数	类型	必填	说明
id	integer	是	歌曲 ID

响应

200 - 标签列表

类型： SongTag[]

字段	类型	必填	说明
color	string	否
cover_url	string	否
created_at	string	否
id	integer	否
name	string	否
song_count	integer	否

数组元素结构：

字段	类型	必填	说明
color	string	否
cover_url	string	否
created_at	string	否
id	integer	否
name	string	否
song_count	integer	否

400 - 参数错误

类型： map[string]string

500 - 服务器错误

类型： map[string]string

内容类型

• 响应： application/json

---