在 Folia 设置中开启 Stage Mode，并复制 Bearer token。
Reference + Console
Stage API
Quickstart
Connection
左侧目录按接口分组，适合先看文档再发请求。
所有请求都能先看到最终 method、headers 和 body，再真正发送。
Overview
Endpoint Surface
/stage/health
Public health check.
/stage/status
Read active stage state.
/stage/lyrics
Push parser-compatible lyric source.
/stage/session
Push media session by URL or file.
/stage/player/search
Search Netease songs.
/stage/player/play
Trigger Folia playback.
/stage/player/status
Read player playback state.
/stage/player/time
Read precise playback clock.
/stage/player/control
Send transport controls.
/stage/player/queue
Read player queue.
/stage/player/queue
Edit player queue.
/stage/player/ws
Subscribe to player events.
/stage/state
Clear current stage input.
Endpoint
GET/stage/health
无需鉴权。用于探活，并确认本地 Stage 入口是否可达。
cURL example
Request preview
No request sent yet.
Endpoint
GET/stage/status
读取当前 active entry、lyrics session 和 media session，需要 Bearer token。
cURL example
Request preview
No request sent yet.
Endpoint
POST/stage/lyrics
推送 parser-compatible 完整歌词对象，相当于进行一次仅有歌词的无音频播放。适合外部歌词工具、爬虫或自定义同步器对接。
Body fields
- title
- 可选，歌曲标题。
- artist
- 可选，歌手名。
- album
- 可选，专辑名。
- lyricSource
- 必填，完整歌词来源对象，`type` 需为 `embedded`、`local`、`navidrome` 或 `netease`。
cURL example
Interactive request
No request sent yet.
Endpoint
POST/stage/session
推送媒体会话。支持 `JSON` 和 `multipart/form-data` 两种形式，适合 URL 拉流或本地文件注入。
Body fields
- audioUrl / audioFile
- 二选一，必须提供其一。
- lyricsText / lyricsFile
- 可选，二选一。
- lyricsFormat
- 可选，`lrc`、`enhanced-lrc`、`vtt`、`yrc` 或自动识别。
- coverUrl / coverFile
- 可选，封面来源。
- title / artist / album
- 可选，补充 metadata。
JSON example
Multipart example
Interactive request
上传音频文件时，Folia 会尝试读取内嵌歌词、封面和 metadata。
No request sent yet.
Endpoint
POST/stage/player/search
搜索网易云结果，返回歌曲列表。结果可直接触发 `/stage/player/play` 或追加到主播放器队列。
Body fields
- query
- 必填，歌曲 / 歌手 / 专辑关键词。
- limit
- 可选，结果数量上限。
cURL example
Interactive request
No request sent yet.
Endpoint
POST/stage/player/play
从外部触发 Folia 主播放器点歌。在 /stage/player/search 返回的搜索结果中进行调试
Body fields
- songId
- 必填，正整数歌曲 ID。
- appendToQueue
- 可选，`true` 时只追加到主播放队列，不打断当前播放。（注：Folia 存在自动去重机制，同一歌曲不会在队列中出现两次，若已在队列中则会被移动到目标位置，并通过返回值的 `deduplicated` 字段体现。）
cURL example
Live request preview
点击搜索结果中的 `Play In Folia` 或 `Add To Queue` 后，这里会显示实际发送的 `/stage/player/play` 请求。
Search results can be played directly back into Folia.
No request sent yet.
Endpoint
GET/stage/player/status
读取 Folia 播放器域状态，包含当前曲目、播放上下文、控制能力和队列摘要。不会返回完整队列 items。
cURL example
Request preview
No request sent yet.
Endpoint
GET/stage/player/time
主动校准播放时间。播放中会按主进程收到的快照采样时间推算当前 `positionMs`。
cURL example
Request preview
No request sent yet.
Endpoint
POST/stage/player/control
发送播放器控制指令。当前上下文不支持时返回 `409 STAGE_PLAYER_CONTROL_UNSUPPORTED`。
Body fields
- action
- `next`、`prev`、`pause`、`resume` 或 `seek`。
- positionMs
- `seek` 时必填，非负整数，无效值会返回 `400`。
cURL example
Interactive request
No request sent yet.
Endpoint
GETPOST/stage/player/queue
读取或编辑正常播放器队列。GET 默认返回 100 条队列窗口，支持 offset、limit 和 around=current。
POST action
- append / insert-next
- 需要 `songId` 或 `songIds`。（注：Folia 会对歌曲自动去重，若歌曲已在队列中则会被直接移动到目标位置，不会重复添加；请求本身如果有重复歌曲也会被合并。响应的 `deduplicated` 字段会体现去重状态。）
- remove / select
- 需要 `queueItemId` 或 `index`，`select` 会切到该队列项播放。使用 `queueItemId` 时会严格校验项匹配度。
- move
- 需要 `fromQueueItemId` 或 `fromIndex`，并提供 `toIndex`。使用 `queueItemId` 时会严格校验项匹配度。
- clear
- 清空队列中非当前播放项。
cURL example
Interactive request
No request sent yet.
Endpoint
WS/stage/player/ws
订阅播放器事件。TRACK_CHANGED 不携带 positionMs / durationMs；PLAYBACK_UPDATED 只推送播放时间和状态。
URL preview
Event log
Disconnected.
No events yet.
Endpoint
DELETE/stage/state
清空当前 Stage 输入，不区分 lyrics 或 media，会把当前注入态整体移除。
cURL example
Request preview
No request sent yet.