Developer · 插件开发

API 文档

LyraNest 通过固定的 HTTP 接口开放音乐下载与歌单导入能力。以下文档只描述接口契约，供外接插件与客户端集成使用。

Overview

运行原理

了解插件中心如何工作，再开始对接。

认证方式

登录接口返回 token 与token_type: Bearer。之后的每个请求在请求头携带：

# 请求头
Authorization: Bearer <会话令牌>
Content-Type: application/json

管理员接口返回 403（非管理员）、401（未登录或令牌失效）。

Auth

认证

所有业务接口都需要登录后的会话令牌。以下两个接口用于初始化和登录。

GET/api/v1/auth/setup无需认证

查询服务端是否已初始化（是否存在管理员）。

响应示例

{"initialized": true}

POST/api/v1/auth/login无需认证

使用账号密码登录，换取 Bearer 会话令牌。

请求体

{"username":"admin","password":"..."}

响应示例

{"token":"<会话令牌>","token_type":"Bearer","expires_at":"2026-...","user":{...}}

Admin

插件管理（仅管理员）

管理员配置音乐提供方插件实例。LyraNest 只内置固定插件类型，不执行客户端上传的任意代码。

GET/api/v1/admin/providers管理员

列出所有已配置的音乐提供方插件。

响应示例

{"providers":[{"id":"...","kind":"sqmusic","display_name":"...","base_url":"...","enabled":true,"settings":{...},"health_status":"healthy","credential_configured":true,"created_at":"..."}]}

POST/api/v1/admin/providers管理员

创建一个新的音乐提供方插件实例。

请求体

{"kind":"sqmusic","display_name":"我的 SQMusic","base_url":"http://...","enabled":true,"settings":{"sources":"kw,netease,qq"},"credentials":{"token":"..."}}

响应示例

{"id":"...","kind":"sqmusic",...}

PATCH/api/v1/admin/providers/{id}管理员

更新插件实例（字段均可选，只更新传入的字段）。

请求体

{"enabled":false}

响应示例

{"id":"...","kind":"sqmusic",...}

DELETE/api/v1/admin/providers/{id}管理员

删除插件实例。

响应示例

204 No Content

POST/api/v1/admin/providers/{id}/test管理员

测试插件连通性：地址、鉴权与搜索能力。

响应示例

{"provider":{...},"checks":{"address":true,"authentication":true,"search":true,"downloads_root":true}}

GET/api/v1/admin/providers/{id}/sources管理员

列出该插件类型支持的音源与当前已选音源。

响应示例

{"sources":[{"id":"kw","name":"酷我音乐"},...],"selected":["kw","netease"]}

POST/api/v1/admin/providers/{id}/sources/{source}/test管理员

对单个音源做搜索与解析下载的连通性测试。

响应示例

{"source":"kw","healthy":true}

Download

音乐下载（登录用户，需音乐下载能力）

已启用插件会向具备音乐下载能力的用户开放搜索与下载任务。搜索失败时错误信息会做脱敏处理。

GET/api/v1/download/providers登录 · music_download

列出当前启用的下载提供方（只返回 enabled=true 的插件）。

响应示例

{"providers":[...]}

GET/api/v1/download/search?q={关键词}&provider={插件ID可选}&page=1&page_size=20登录 · music_download

跨已启用插件搜索音源，返回候选曲目与可用音质。

响应示例

{"tracks":[{"id":"...","title":"...","artist":"...","album":"...","cover_url":"...","source":"kw","duration":234000000000,"qualities":[{"id":"flac","label":"FLAC"},{"id":"320","label":"320kbps"}],"payload":{"provider_plugin_id":"..."}}],"page":1,"page_size":20}

POST/api/v1/download/jobs登录 · music_download

创建下载任务。plugin_id 可省略（从 track.payload.provider_plugin_id 自动取）。

请求体

{"plugin_id":"...","quality":"flac","track":{"id":"...","title":"...","payload":{"provider_plugin_id":"..."}}}

响应示例

{"id":"...","user_id":"...","plugin_id":"...","track":{...},"requested_quality":"flac","status":"queued","progress_bytes":0,"total_bytes":0,"created_at":"..."}

GET/api/v1/download/jobs登录 · music_download

列出当前用户的下载任务（按创建时间倒序）。

响应示例

{"jobs":[{"id":"...","status":"downloading","progress_bytes":1024,"total_bytes":4096,...}]}

POST/api/v1/download/jobs/{id}/cancel登录 · music_download

取消指定下载任务。

响应示例

{"id":"...","status":"cancelled",...}

POST/api/v1/download/jobs/{id}/retry登录 · music_download

重试失败的下载任务。

响应示例

{"id":"...","status":"queued",...}

DELETE/api/v1/download/jobs/{id}登录 · music_download

删除下载任务记录。

响应示例

204 No Content

Import

歌单导入

支持两类来源：分享链接（GoMusic / TuneMySong 插件）与本地文件（JSON / M3U / 纯文本）。服务端会把歌曲与当前用户可读的曲库做匹配。

GET/api/v1/playlist-import/providers登录

列出已启用且已配置地址的歌单导入插件（GoMusic / TuneMySong）。

响应示例

{"plugins":[{"id":"...","kind":"gomusic","display_name":"...","base_url":"...","enabled":true,...}]}

POST/api/v1/playlist-import/fetch登录

通过插件解析分享链接，并把歌曲与用户可读曲库匹配。

请求体

{"plugin_id":"...","url":"https://...","detailed":false}

响应示例

{"plugin_id":"...","playlist":{"name":"...","songs":[{"title":"...","artist":"...","matched":true,"track_id":"...","match_quality":"exact"}],"songs_count":10,"matched_count":8}}

POST/api/v1/playlist-import/parse登录

解析本地歌单内容（JSON / M3U / 纯文本 / auto 自动识别），并做曲库匹配。无需插件。

请求体

{"name":"我的歌单","format":"m3u","content":"#EXTM3U\n..."}

响应示例

{"playlist":{"name":"我的歌单","songs":[...],"songs_count":10,"matched_count":8}}

POST/api/v1/playlist-import/commit登录

把匹配好的歌曲一次性写入歌单。playlist_id 为空时由服务端新建歌单并返回其 ID。

请求体

{"playlist_id":"","name":"导入的歌单","track_ids":["sha1-xxx","sha1-yyy"]}

响应示例

{"playlist_id":"imported-playlist-...","playlist_name":"导入的歌单","collections":{...}}

POST/api/v1/me/playlists/{playlistId}/tracks/bulk登录

批量把曲目加入已有歌单（导入流程的底层接口）。

请求体

{"track_ids":["sha1-xxx","sha1-yyy"]}

响应示例

{"collections":{...}}

Kinds

插件类型与音源

LyraNest 内置固定的插件类型，插件实例只需提供该类型的服务地址与凭据，无需上传代码。

—solara—

音源下载提供方，支持音源：netease（网易云音乐）、kuwo（酷我音乐）、joox（JOOX 音乐）、bilibili（哔哩哔哩）。

—sqmusic—

音源下载提供方，支持音源：kw（酷我）、netease（网易云）、qq（QQ 音乐）、qqvip（QQ VIP）、kg（酷狗）、mg（咪咕）、apple（Apple Music）、tidal、qobuz、musicbrainz。

—gomusic—

歌单导入插件，通过分享链接拉取歌单。

—tunemysong—

歌单导入插件，通过分享链接拉取歌单。

数据模型

Track（搜索到的曲目）

id · title · artist · album
cover_url · source · duration
qualities: [{id, label}]
payload: [{provider_plugin_id, ...}]

DownloadJob（下载任务）

id · user_id · plugin_id · track
requested_quality · status
progress_bytes · total_bytes
target_path · error_message
status: queued / downloading / completed / failed / cancelled / retryable

Plugin（插件实例）

id · kind · display_name · base_url
enabled · settings · health_status
credential_configured · created_by

Playlist 匹配结果

songs: title · artist · matched · track_id · match_quality
match_quality: exact / artist / title

常见错误

状态码	含义
400	请求体或参数不合法（缺少关键词、格式错误等）
401	未登录或会话令牌无效
403	无权限（非管理员访问管理接口，或无 music_download 能力）
404	插件、下载任务或音源不存在
502	上游音源/歌单插件请求失败（错误信息已脱敏）
503	插件能力未启用（如提供方插件未配置）

统一错误体：{ "error": "描述信息" }

需要把 LyraNest 接进你的工具或写自己的插件？加入交流 QQ 群700454910一起讨论。

阅读 —点赞 —

把音乐，
放回你自己家里

现在开始建立属于自己的音乐库。

立即下载 Docker 一键部署

Android APKWindows x64Android TV飞牛 fnOS FPK群晖 Synology SPK威联通 QNAP QPKG绿联 UGREEN UPK铁威马 TerraMaster DEBDocker

API 文档

运行原理

认证方式

认证

插件管理（仅管理员）

音乐下载（登录用户，需音乐下载能力）

歌单导入

插件类型与音源

数据模型

常见错误

把音乐，放回你自己家里

把音乐，
放回你自己家里