歌单管理

接口列表

方法	路径	说明
POST	/playlists	创建歌单
GET	/playlists	获取歌单列表
PUT	/playlists/{id}	更新歌单
DELETE	/playlists/{id}	删除歌单
GET	/playlists/{id}	获取单个歌单详情
POST	/playlists/{id}/cover	上传歌单封面
GET	/playlists/{id}/cover	获取歌单封面
PUT	/playlists/{id}/pin	设置歌单置顶状态
GET	/playlists/{id}/song-ids	获取歌单歌曲 ID 列表
POST	/playlists/{id}/songs	批量添加歌曲到歌单
GET	/playlists/{id}/songs	获取歌单中的歌曲
DELETE	/playlists/{id}/songs/{songId}	从歌单移除歌曲
PUT	/playlists/{id}/songs/move	移动歌单内歌曲位置
PUT	/playlists/{id}/songs/reorder	重新排序歌单中的歌曲
POST	/playlists/{id}/songs/sort	服务端排序歌单内歌曲
PUT	/playlists/{id}/sort	更新歌单视图排序偏好
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	否	歌单名称 示例: "我的最爱"
pinned_at	string	否	置顶时间，nil 表示未置顶；多个置顶歌单按此字段倒序排列 示例: "2024-01-01T12:00:00Z"
remote_count	integer	否	歌单内网络歌曲（songs.type=remote）数量，>0 即为「网络歌单」；仅列表接口填充，详情接口恒为 0 示例: 3
song_count	integer	否	歌曲数量 示例: 10
sort_by	string	否	视图排序字段：position/added_at/file_modified_at/title/artist/duration 示例: "position"
sort_order	string	否	视图排序方向：asc/desc 示例: "asc"
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	否	歌单名称 示例: "我的最爱"
pinned_at	string	否	置顶时间，nil 表示未置顶；多个置顶歌单按此字段倒序排列 示例: "2024-01-01T12:00:00Z"
remote_count	integer	否	歌单内网络歌曲（songs.type=remote）数量，>0 即为「网络歌单」；仅列表接口填充，详情接口恒为 0 示例: 3
song_count	integer	否	歌曲数量 示例: 10
sort_by	string	否	视图排序字段：position/added_at/file_modified_at/title/artist/duration 示例: "position"
sort_order	string	否	视图排序方向：asc/desc 示例: "asc"
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 显示全部。 song_source 按歌单内歌曲的来源筛选（歌单本身没有来源字段，只能由歌曲反推）：remote=歌单内含网络歌曲（「网络歌单」），local=含本地歌曲（「本地歌单」）。 判定是 EXISTS 而非「全部是」，故本地+网络混合的歌单在两个取值下都会出现，空歌单两个取值下都不出现。电台歌曲的 type 是 radio 而非 remote，故电台歌单不会被 song_source=remote 命中。

需要认证

此接口需要 Bearer Token 认证

查询参数

参数	类型	必填	说明
type	string	否	歌单类型 可选值: normal, radio
song_source	string	否	按歌单内歌曲来源过滤: remote=含网络歌曲, local=含本地歌曲 可选值: remote, local
keyword	string	否	搜索关键词（模糊匹配歌单名称/描述）
exclude_labels	string	否	要排除的标签(逗号分隔), 默认排除 hidden; 传 none 显示全部 默认: "hidden"
limit	integer	否	每页数量 默认: 20
offset	integer	否	偏移量 默认: 0

响应

200 - 成功返回歌单列表

类型： map[string]any

400 - song_source 取值非法

类型： map[string]string

500 - 服务器错误

类型： map[string]string

内容类型

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

---

PUT /playlists/{id}

更新歌单

更新歌单信息。支持通过 cover_song_id 从指定歌曲复制封面，与 cover_path/cover_url 互斥且优先级更高

需要认证

此接口需要 Bearer Token 认证

路径参数

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

请求体

歌单信息

类型： UpdatePlaylistRequest

字段	类型	必填	说明
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	否	歌单名称 示例: "我的最爱"
pinned_at	string	否	置顶时间，nil 表示未置顶；多个置顶歌单按此字段倒序排列 示例: "2024-01-01T12:00:00Z"
remote_count	integer	否	歌单内网络歌曲（songs.type=remote）数量，>0 即为「网络歌单」；仅列表接口填充，详情接口恒为 0 示例: 3
song_count	integer	否	歌曲数量 示例: 10
sort_by	string	否	视图排序字段：position/added_at/file_modified_at/title/artist/duration 示例: "position"
sort_order	string	否	视图排序方向：asc/desc 示例: "asc"
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删除歌单。delete_songs=true 时，同时删除仅属于本歌单的孤儿歌曲（不属于任何其他歌单，含内置的收藏/电台收藏保护）——本地歌曲连同磁盘文件一并删除，网络/电台歌曲清理数据库记录与缓存。

需要认证

此接口需要 Bearer Token 认证

路径参数

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

查询参数

参数	类型	必填	说明
delete_songs	boolean	否	是否一并删除仅属于本歌单的孤儿歌曲（含本地文件），默认 false

响应

200 - 删除成功，含连带清理的歌曲数 deleted_songs

类型： map[string]any

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	否	歌单名称 示例: "我的最爱"
pinned_at	string	否	置顶时间，nil 表示未置顶；多个置顶歌单按此字段倒序排列 示例: "2024-01-01T12:00:00Z"
remote_count	integer	否	歌单内网络歌曲（songs.type=remote）数量，>0 即为「网络歌单」；仅列表接口填充，详情接口恒为 0 示例: 3
song_count	integer	否	歌曲数量 示例: 10
sort_by	string	否	视图排序字段：position/added_at/file_modified_at/title/artist/duration 示例: "position"
sort_order	string	否	视图排序方向：asc/desc 示例: "asc"
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	否	歌单名称 示例: "我的最爱"
pinned_at	string	否	置顶时间，nil 表示未置顶；多个置顶歌单按此字段倒序排列 示例: "2024-01-01T12:00:00Z"
remote_count	integer	否	歌单内网络歌曲（songs.type=remote）数量，>0 即为「网络歌单」；仅列表接口填充，详情接口恒为 0 示例: 3
song_count	integer	否	歌曲数量 示例: 10
sort_by	string	否	视图排序字段：position/added_at/file_modified_at/title/artist/duration 示例: "position"
sort_order	string	否	视图排序方向：asc/desc 示例: "asc"
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

---

PUT /playlists/{id}/pin

设置歌单置顶状态

置顶/取消置顶歌单。置顶歌单在歌单列表中始终排在最前，多个置顶歌单按置顶时间倒序（最近置顶的排最前）。内置歌单（收藏、电台收藏）同样允许置顶，不做特殊限制。

需要认证

此接口需要 Bearer Token 认证

路径参数

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

请求体

置顶设置

类型： SetPlaylistPinnedRequest

字段	类型	必填	说明
pinned	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	否	歌单名称 示例: "我的最爱"
pinned_at	string	否	置顶时间，nil 表示未置顶；多个置顶歌单按此字段倒序排列 示例: "2024-01-01T12:00:00Z"
remote_count	integer	否	歌单内网络歌曲（songs.type=remote）数量，>0 即为「网络歌单」；仅列表接口填充，详情接口恒为 0 示例: 3
song_count	integer	否	歌曲数量 示例: 10
sort_by	string	否	视图排序字段：position/added_at/file_modified_at/title/artist/duration 示例: "position"
sort_order	string	否	视图排序方向：asc/desc 示例: "asc"
type	string	否	歌单类型：normal/radio 可选值: normal, radio 示例: "normal"
updated_at	string	否	最后更新时间 示例: "2024-01-01T12:00:00Z"

400 - 无效的歌单ID或请求数据

类型： map[string]string

404 - 歌单不存在

类型： map[string]string

500 - 服务器错误

类型： map[string]string

内容类型

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

---

GET /playlists/{id}/song-ids

获取歌单歌曲 ID 列表

返回歌单内全部歌曲的 ID，不分页。sort/order 语义与 GET /playlists/{id}/songs 完全一致（同一套排序逻辑），省略时默认 position 升序。 用途：客户端需要知道「某首歌在歌单里排第几」时（如从播放历史里的某首歌接着往下播），用本端点拿到有序 ID 数组后取下标，即可直接作为 /playlists/{id}/songs 的 offset 使用（传相同的 sort/order），避免为此拉取全部歌曲对象。 形态与 GET /songs/ids 对齐。

需要认证

此接口需要 Bearer Token 认证

路径参数

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

查询参数

参数	类型	必填	说明
sort	string	否	排序字段: position(默认)/added_at/title/artist/album/duration/updated_at/file_modified_at/file_size
order	string	否	排序方向: asc(默认)/desc

响应

200 - 成功返回 {ids:[1,2,3], total:3}

类型： map[string]any

400 - 无效的歌单 ID

类型： map[string]string

500 - 服务器错误

类型： map[string]string

内容类型

• 响应： application/json

---

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/file_size
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/move

移动歌单内歌曲位置

将指定歌曲移到 after_song_id 之后（after_song_id 为 null 则移到第一位），不改变其余歌曲的相对顺序

需要认证

此接口需要 Bearer Token 认证

路径参数

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

请求体

移动参数（after_song_id 为 null 或省略表示置顶）

类型： object

字段	类型	必填	说明
after_song_id	int64	否
song_id	int64	否

响应

200 - 移动成功

类型： map[string]string

400 - 请求数据错误

类型： map[string]string

403 - 内置歌单不可操作

类型： 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}/songs/sort

服务端排序歌单内歌曲

根据 action 参数对歌单内歌曲进行永久排序（更新 position）。 action 取值：name_asc（按名称 A→Z）、name_desc（按名称 Z→A）、number_prefix（按标题数字前缀）、shuffle（随机打乱）。 与 /playlists/{id}/songs/reorder 不同，本端点无需客户端传入完整歌曲 ID 列表，排序由服务端完成。

需要认证

此接口需要 Bearer Token 认证

路径参数

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

请求体

排序动作: name_asc / name_desc / number_prefix / shuffle

类型： object

字段	类型	必填	说明
action	string	否

响应

200 - 排序成功

类型： map[string]string

400 - 请求数据错误

类型： map[string]string

403 - 内置歌单不可操作

类型： map[string]string

500 - 排序失败

类型： map[string]string

内容类型

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

---

PUT /playlists/{id}/sort

更新歌单视图排序偏好

保存歌单的视图排序设置（非破坏性排序），下次打开歌单时恢复该排序

需要认证

此接口需要 Bearer Token 认证

路径参数

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

请求体

排序设置 {sort_by, sort_order}

类型： object

响应

200 - 更新成功

类型： map[string]string

400 - 无效参数

类型： map[string]string

500 - 更新失败

类型： map[string]string

内容类型

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

---

POST /playlists/{id}/touch

更新歌单最后播放时间

仅更新歌单的 updated_at 字段，作为歌单级的粗粒度「最后播放时间」，也会被改名/换封面等更新操作刷新。 歌曲级的精确播放历史见 GET /play-history?context_type=playlist&context_key={id}。

需要认证

此接口需要 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	否	歌单名称 示例: "我的最爱"
pinned_at	string	否	置顶时间，nil 表示未置顶；多个置顶歌单按此字段倒序排列 示例: "2024-01-01T12:00:00Z"
remote_count	integer	否	歌单内网络歌曲（songs.type=remote）数量，>0 即为「网络歌单」；仅列表接口填充，详情接口恒为 0 示例: 3
song_count	integer	否	歌曲数量 示例: 10
sort_by	string	否	视图排序字段：position/added_at/file_modified_at/title/artist/duration 示例: "position"
sort_order	string	否	视图排序方向：asc/desc 示例: "asc"
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 列表批量删除歌单，内置歌单会被跳过。请求体 delete_songs=true 时，同时删除仅属于这些歌单的孤儿歌曲（不属于任何其他歌单）——本地歌曲连同磁盘文件一并删除。

需要认证

此接口需要 Bearer Token 认证

请求体

批量删除请求

类型： BatchDeletePlaylistsRequest

字段	类型	必填	说明
delete_songs	boolean	否	为 true 时，一并删除仅属于被删歌单的孤儿歌曲（含本地歌曲及其磁盘文件） 示例: false
ids	integer[]	否	要删除的歌单 ID 列表 示例: [1]

响应

200 - 删除成功

类型： BatchDeletePlaylistsResponse

字段	类型	必填	说明
deleted	integer	否	实际删除的歌单数量 示例: 3
deleted_songs	integer	否	连带清理的孤儿歌曲数量 示例: 12

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

---