OpenAPI

可用接口

方法和路径	用途	是否需要系统 Token
GET /health	检查 QPlay API 是否可以连接	否
POST /api/external/organize	启动一次自动整理	是
POST /api/webhooks/emby	接收 Emby 或 Strm Assistant 的删除通知	是

健康检查

第三方软件检查连接时，应请求 QPlay 管理地址，默认端口为 7735。不要使用 Emby 的 8099 播放入口。

curl --fail --max-time 5 'http://服务器IP:7735/health'

正常时返回 HTTP 200：

{
  "status": "ok",
  "version": "1.2.3",
  "sync_running": false
}

第三方软件应同时确认 HTTP 状态码为 200 且 status 为 ok。sync_running 为 true 只表示同步任务正在运行，不表示 API 不可用。

健康检查不需要管理员登录或系统 Token，也不会修改数据。它只确认 QPlay API 能够响应，不检查 115、TMDB、Emby、授权服务或系统 Token。不要用自动整理接口代替健康检查，否则会实际启动任务。

系统 Token

两个 POST 接口使用系统 Token。进入“设置 → 系统与安全”，填写或生成 Token，然后保存设置。

第三方软件可以使用以下任一请求头：

Authorization: Bearer <系统Token>
X-QPlay-Token: <系统Token>

系统 Token 未配置时，接口返回 HTTP 503；Token 无效时返回 HTTP 401。不要公开系统 Token 或包含 Token 的完整回调链接。

启动自动整理

curl -X POST 'http://服务器IP:7735/api/external/organize' \
  -H 'Authorization: Bearer <系统Token>'

成功排队时返回 HTTP 200：

{
  "accepted": true,
  "message": "同步任务已启动"
}

调用前必须连接并启用 115 主账号、完成首次全量同步，并配置待整理、媒体库和未识别目录。任务未启动时接口仍可能返回 HTTP 200，但 accepted 为 false，message 会说明原因。因此，第三方软件必须检查 accepted，不能只判断 HTTP 状态码。

此接口只接受请求头中的 Token，不接受 URL 查询参数 Token。

Emby 删除联动

启用后，当 Emby 或 Strm Assistant 删除媒体库中的 STRM 时，QPlay 可以同步删除 115 中对应的媒体。这项功能会修改 115 文件，启用前请先备份并用测试文件确认结果。

配置前提

• 已连接并启用 115 主账号；
• 已完成首次全量同步；
• 已配置媒体库网盘绝对路径；
• 已保存系统 Token；
• 已配置 Emby STRM 路径映射。

配置步骤

进入“设置 → 媒体服务”，找到“Emby STRM 路径映射”，每行填写：

Emby 中看到的 STRM 目录 => 115 媒体库目录

例如：

/media => /qplay/媒体库

左侧填写 Emby 中的 STRM 目录，右侧填写对应的 115 媒体库目录。不要填写根目录或包含 .. 的路径。该映射也用于刷新 Emby 中对应的媒体库目录。

在“设置 → 媒体服务”的 Emby Webhook 卡片复制完整链接，粘贴到 Emby 或 Strm Assistant 的删除通知设置中。链接使用“STRM 播放入口”的站点地址，并附带已保存的系统 Token；请确认 Emby 能访问该地址。只启用媒体删除通知，保存后先删除一个测试 STRM，再检查 QPlay 记录和 115 文件。

完整链接包含 Token，不要公开分享。如果发送方支持自定义请求头，可改用不带 ?token=... 的 /api/webhooks/emby 地址，并通过 Authorization 或 X-QPlay-Token 传递 Token。

Webhook 接受请求后返回 HTTP 202：

{
  "accepted": true,
  "queued": 1
}

queued 是本次加入后台队列的删除任务数；为 0 时没有可处理的删除目标。收到 202 只表示通知已接收，实际删除结果应在 QPlay 记录和 115 中确认。

排查

删除通知没有生效时，检查：

1. 系统 Token 是否已经保存；
2. 路径映射左侧是否与 Emby 看到的路径一致；
3. 右侧是否为 115 媒体库目录；
4. 测试文件是否已经出现在 QPlay 的 STRM 记录中；
5. 115 主账号是否仍然可用。

路径没有匹配时，QPlay 不会删除 115 文件。请在确认映射正确后再测试正式媒体。