歌单管理
接口列表
| 方法 | 路径 | 说明 |
|---|---|---|
POST | /playlists | 创建歌单 |
GET | /playlists | 获取歌单列表 |
PUT | /playlists/{id} | 更新歌单 |
DELETE | /playlists/{id} | 删除歌单 |
GET | /playlists/{id} | 获取单个歌单详情 |
POST | /playlists/{id}/cover | 上传歌单封面 |
GET | /playlists/{id}/cover | 获取歌单封面 |
POST | /playlists/{id}/songs | 批量添加歌曲到歌单 |
GET | /playlists/{id}/songs | 获取歌单中的歌曲 |
DELETE | /playlists/{id}/songs/{songId} | 从歌单移除歌曲 |
PUT | /playlists/{id}/songs/reorder | 重新排序歌单中的歌曲 |
POST | /playlists/{id}/touch | 更新歌单最后播放时间 |
PUT | /playlists/{id}/visibility | 设置歌单可见性 |
POST | /playlists/batch-delete | 批量删除歌单 |
PUT | /playlists/reorder | 重新排序歌单列表 |
POST /playlists
创建歌单
创建一个新的歌单
需要认证
此接口需要 Bearer Token 认证
请求体
歌单信息
类型： Playlist
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
cover_url | string | 否 | 封面图片 URL 示例: "https://example.com/playlist.jpg" |
created_at | string | 否 | 创建时间 示例: "2024-01-01T12:00:00Z" |
description | string | 否 | 歌单描述 示例: "收藏的经典歌曲" |
id | integer | 否 | 歌单 ID 示例: 1 |
labels | string[] | 否 | 歌单标签，如 ["built_in"] 示例: ["[\"built_in\"]"] |
name | string | 否 | 歌单名称 示例: "我的最爱" |
song_count | integer | 否 | 歌曲数量 示例: 10 |
type | string | 否 | 歌单类型：normal/radio 可选值: normal, radio 示例: "normal" |
updated_at | string | 否 | 最后更新时间 示例: "2024-01-01T12:00:00Z" |
响应
201 - 创建成功
类型： Playlist
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
cover_url | string | 否 | 封面图片 URL 示例: "https://example.com/playlist.jpg" |
created_at | string | 否 | 创建时间 示例: "2024-01-01T12:00:00Z" |
description | string | 否 | 歌单描述 示例: "收藏的经典歌曲" |
id | integer | 否 | 歌单 ID 示例: 1 |
labels | string[] | 否 | 歌单标签，如 ["built_in"] 示例: ["[\"built_in\"]"] |
name | string | 否 | 歌单名称 示例: "我的最爱" |
song_count | integer | 否 | 歌曲数量 示例: 10 |
type | string | 否 | 歌单类型：normal/radio 可选值: normal, radio 示例: "normal" |
updated_at | string | 否 | 最后更新时间 示例: "2024-01-01T12:00:00Z" |
400 - 请求数据错误
类型： map[string]string
500 - 创建失败
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json
GET /playlists
获取歌单列表
获取歌单列表，支持按类型过滤、关键词搜索和分页。默认排除隐藏歌单，传 exclude_labels=none 显示全部
需要认证
此接口需要 Bearer Token 认证
查询参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
type | string | 否 | 歌单类型 可选值: normal, radio |
keyword | string | 否 | 搜索关键词（模糊匹配歌单名称/描述） |
exclude_labels | string | 否 | 要排除的标签(逗号分隔), 默认排除 hidden; 传 none 显示全部 默认: "hidden" |
limit | integer | 否 | 每页数量 默认: 20 |
offset | integer | 否 | 偏移量 默认: 0 |
响应
200 - 成功返回歌单列表
类型： map[string]any
500 - 服务器错误
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json
PUT /playlists/{id}
更新歌单
更新歌单信息。支持通过 cover_song_id 从指定歌曲复制封面，与 cover_path/cover_url 互斥且优先级更高
需要认证
此接口需要 Bearer Token 认证
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 是 | 歌单ID |
请求体
歌单信息
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
cover_path | string | 否 | 封面图片本地路径（传空字符串清除） 示例: "" |
cover_song_id | integer | 否 | 从指定歌曲复制封面（与 cover_path/cover_url 互斥，优先级更高） 示例: 42 |
cover_url | string | 否 | 封面图片 URL（传空字符串清除） 示例: "" |
description | string | 否 | 歌单描述 示例: "收藏的经典歌曲" |
name | string | 否 | 歌单名称 示例: "我的最爱" |
响应
200 - 更新成功
类型： Playlist
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
cover_url | string | 否 | 封面图片 URL 示例: "https://example.com/playlist.jpg" |
created_at | string | 否 | 创建时间 示例: "2024-01-01T12:00:00Z" |
description | string | 否 | 歌单描述 示例: "收藏的经典歌曲" |
id | integer | 否 | 歌单 ID 示例: 1 |
labels | string[] | 否 | 歌单标签，如 ["built_in"] 示例: ["[\"built_in\"]"] |
name | string | 否 | 歌单名称 示例: "我的最爱" |
song_count | integer | 否 | 歌曲数量 示例: 10 |
type | string | 否 | 歌单类型：normal/radio 可选值: normal, radio 示例: "normal" |
updated_at | string | 否 | 最后更新时间 示例: "2024-01-01T12:00:00Z" |
400 - 请求数据错误
类型： map[string]string
500 - 更新失败
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json
DELETE /playlists/{id}
删除歌单
根据歌单ID删除歌单
需要认证
此接口需要 Bearer Token 认证
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 是 | 歌单ID |
响应
200 - 删除成功
类型： map[string]string
400 - 无效的歌单ID
类型： map[string]string
500 - 删除失败
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json
GET /playlists/{id}
获取单个歌单详情
根据歌单ID获取详细信息
需要认证
此接口需要 Bearer Token 认证
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 是 | 歌单ID |
响应
200 - 成功返回歌单详情
类型： Playlist
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
cover_url | string | 否 | 封面图片 URL 示例: "https://example.com/playlist.jpg" |
created_at | string | 否 | 创建时间 示例: "2024-01-01T12:00:00Z" |
description | string | 否 | 歌单描述 示例: "收藏的经典歌曲" |
id | integer | 否 | 歌单 ID 示例: 1 |
labels | string[] | 否 | 歌单标签，如 ["built_in"] 示例: ["[\"built_in\"]"] |
name | string | 否 | 歌单名称 示例: "我的最爱" |
song_count | integer | 否 | 歌曲数量 示例: 10 |
type | string | 否 | 歌单类型：normal/radio 可选值: normal, radio 示例: "normal" |
updated_at | string | 否 | 最后更新时间 示例: "2024-01-01T12:00:00Z" |
400 - 无效的歌单ID
类型： map[string]string
404 - 歌单不存在
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json
POST /playlists/{id}/cover
上传歌单封面
上传本地图片作为歌单封面
需要认证
此接口需要 Bearer Token 认证
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 是 | 歌单ID |
表单参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
file | file | 是 | 封面图片文件 |
响应
200 - 上传成功
类型： Playlist
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
cover_url | string | 否 | 封面图片 URL 示例: "https://example.com/playlist.jpg" |
created_at | string | 否 | 创建时间 示例: "2024-01-01T12:00:00Z" |
description | string | 否 | 歌单描述 示例: "收藏的经典歌曲" |
id | integer | 否 | 歌单 ID 示例: 1 |
labels | string[] | 否 | 歌单标签，如 ["built_in"] 示例: ["[\"built_in\"]"] |
name | string | 否 | 歌单名称 示例: "我的最爱" |
song_count | integer | 否 | 歌曲数量 示例: 10 |
type | string | 否 | 歌单类型：normal/radio 可选值: normal, radio 示例: "normal" |
updated_at | string | 否 | 最后更新时间 示例: "2024-01-01T12:00:00Z" |
400 - 请求数据错误
类型： map[string]string
500 - 上传失败
类型： map[string]string
内容类型
- 请求：
multipart/form-data - 响应：
application/json
GET /playlists/{id}/cover
获取歌单封面
返回歌单封面图片文件。可选 query 参数 w：把本地封面等比缩放到该宽度（物理像素，绝不放大、上限 1024）后以 JPEG 返回，用于 Web 端降低 GPU 纹理体积（songloft-org/songloft#309）；缺省或非法时返回原图。缩略仅作用于本地封面，远程代理封面忽略 w。
需要认证
此接口需要 Bearer Token 认证
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 是 | 歌单ID |
查询参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
w | integer | 否 | 本地封面缩略目标宽度（物理像素，绝不放大，上限 1024） |
响应
200 - 封面图片
类型： file
404 - 封面不存在
类型： map[string]string
500 - 读取失败
类型： map[string]string
内容类型
- 响应：
image/jpeg
POST /playlists/{id}/songs
批量添加歌曲到歌单
将多首歌曲添加到指定歌单，跳过已存在的歌曲
需要认证
此接口需要 Bearer Token 认证
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 是 | 歌单 ID |
请求体
歌曲 ID 列表
类型： object
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
song_ids | int64[] | 否 |
响应
200 - 添加成功
类型： map[string]any
400 - 请求数据错误
类型： map[string]string
500 - 添加失败
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json
GET /playlists/{id}/songs
获取歌单中的歌曲
获取指定歌单中的歌曲，支持分页、排序和搜索
需要认证
此接口需要 Bearer Token 认证
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 是 | 歌单 ID |
查询参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
limit | integer | 否 | 每页数量 默认: 20 |
offset | integer | 否 | 偏移量 默认: 0 |
sort | string | 否 | 排序字段: position(默认)/added_at/title/artist/album/duration/updated_at/file_modified_at |
order | string | 否 | 排序方向: asc(默认)/desc |
keyword | string | 否 | 搜索关键词（匹配标题/艺术家/专辑） |
响应
200 - 成功返回歌曲列表
类型： map[string]any
400 - 无效的歌单 ID
类型： map[string]string
500 - 获取失败
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json
DELETE /playlists/{id}/songs/{songId}
从歌单移除歌曲
从指定歌单移除歌曲
需要认证
此接口需要 Bearer Token 认证
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 是 | 歌单 ID |
songId | integer | 是 | 歌曲 ID |
响应
200 - 移除成功
类型： map[string]string
400 - 请求数据错误
类型： map[string]string
500 - 移除失败
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json
PUT /playlists/{id}/songs/reorder
重新排序歌单中的歌曲
需要认证
此接口需要 Bearer Token 认证
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 是 | 歌单 ID |
请求体
歌曲 ID 列表
类型： object
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
song_ids | int64[] | 否 |
响应
200 - 排序成功
类型： map[string]string
400 - 请求数据错误
类型： map[string]string
500 - 排序失败
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json
POST /playlists/{id}/touch
更新歌单最后播放时间
仅更新歌单的 updated_at 字段，用于记录最后播放时间
需要认证
此接口需要 Bearer Token 认证
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 是 | 歌单ID |
响应
200 - 更新成功
类型： map[string]string
400 - 无效的歌单ID
类型： map[string]string
500 - 更新失败
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json
PUT /playlists/{id}/visibility
设置歌单可见性
切换歌单的隐藏状态。内置歌单（收藏、电台收藏）不允许隐藏
需要认证
此接口需要 Bearer Token 认证
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 是 | 歌单ID |
请求体
可见性设置
类型： SetPlaylistVisibilityRequest
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
hidden | boolean | 否 | 是否隐藏歌单 示例: true |
响应
200 - 更新后的歌单
类型： Playlist
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
cover_url | string | 否 | 封面图片 URL 示例: "https://example.com/playlist.jpg" |
created_at | string | 否 | 创建时间 示例: "2024-01-01T12:00:00Z" |
description | string | 否 | 歌单描述 示例: "收藏的经典歌曲" |
id | integer | 否 | 歌单 ID 示例: 1 |
labels | string[] | 否 | 歌单标签，如 ["built_in"] 示例: ["[\"built_in\"]"] |
name | string | 否 | 歌单名称 示例: "我的最爱" |
song_count | integer | 否 | 歌曲数量 示例: 10 |
type | string | 否 | 歌单类型：normal/radio 可选值: normal, radio 示例: "normal" |
updated_at | string | 否 | 最后更新时间 示例: "2024-01-01T12:00:00Z" |
400 - 请求错误或内置歌单不可隐藏
类型： map[string]string
404 - 歌单不存在
类型： map[string]string
500 - 服务器错误
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json
POST /playlists/batch-delete
批量删除歌单
根据歌单 ID 列表批量删除歌单，内置歌单会被跳过
需要认证
此接口需要 Bearer Token 认证
请求体
批量删除请求
类型： BatchDeletePlaylistsRequest
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
ids | integer[] | 否 | 要删除的歌单 ID 列表 示例: [1] |
响应
200 - 删除成功
类型： BatchDeletePlaylistsResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
deleted | integer | 否 | 实际删除的数量 示例: 3 |
400 - 请求数据错误
类型： map[string]string
500 - 删除失败
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json
PUT /playlists/reorder
重新排序歌单列表
需要认证
此接口需要 Bearer Token 认证
请求体
歌单 ID 列表
类型： object
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
playlist_ids | int64[] | 否 |
响应
200 - 排序成功
类型： map[string]string
400 - 请求数据错误
类型： map[string]string
500 - 排序失败
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json