接口参考
Leelaa Reader 提供一组面向第三方客户端的稳定 API，用于登录、授权状态检查、书库浏览、分类浏览、播放、进度、收藏和书签。
OpenAPI
稳定接口只覆盖普通客户端需要的能力。图书导入、删除、扫描、系统配置、日志清理、AI 维护等管理能力不作为第三方稳定契约。
接入前准备
第三方客户端需要让用户提供：
- Leelaa Reader 服务地址；
- 服务端用户名；
- 服务端密码。
密码只用于登录换取 token，不应长期保存。服务地址必须支持用户编辑，不能把域名、端口或飞牛网关前缀写死。
Base URL
本地或直连服务默认使用：
text
http://{host}:8686/api/v1同源反向代理部署通常使用：
text
/api/v1飞牛 fnOS 统一网关场景可能使用：
text
/app/leelaa-reader/api/v1最小接入流程
- 登录获取 token：
POST /auth/login - 检查授权状态：
GET /license/status - 获取书库或搜索：
GET /books、GET /books/search - 获取书籍详情与章节：
GET /books/{bookId}、GET /books/{bookId}/chapters - 获取播放清单：
GET /books/{bookId}/download-manifest - 播放章节：
GET /chapters/{chapterId}/play?raw=1 - 同步进度：
GET /auth/reading-progress/{bookId}、POST /auth/reading-progress/{bookId}
认证方式
登录成功后，后续 JSON API 推荐使用标准 Bearer Token：
http
Authorization: Bearer {token}如果播放器无法为音频请求设置请求头，可以在播放 URL 中携带 token：
text
/api/v1/chapters/{chapterId}/play?raw=1&access_token={token}不要持久化用户密码。收到 401 后重新登录；收到 403 license_required 后停止后台同步和播放请求，并提示用户处理授权。
播放规则
播放必须基于后端返回的全量播放队列：
http
GET /api/v1/books/{bookId}/download-manifest第三方客户端必须遵守：
- 使用
items[].chapterId作为章节唯一标识； - 不使用列表下标保存进度、历史或书签；
- 不只保留当前章节附近的局部列表；
- 队列顺序以后端返回为准，客户端不得私自重排；
- 进度由客户端上报，最终合并与裁决由服务端处理；
- 恢复进度期间不能用
0位置覆盖已有有效进度。
常见错误
| 状态 | 含义 | 建议处理 |
|---|---|---|
400 | 参数缺失或格式错误 | 检查请求字段与类型 |
401 | 未登录或 token 失效 | 重新登录 |
403 | 无权限、授权失效或越权 | 停止当前操作并提示用户 |
404 | 资源不存在 | 刷新书库或回到列表 |
500 | 服务端内部错误 | 保留本地稳定状态，稍后重试 |
对接检查清单
- 能配置服务地址，兼容直连、同源代理和飞牛网关前缀；
- 能登录并保存 token，不保存密码；
- 能读取授权状态，并在授权失效时停止后台请求；
- 能拉取书库、书籍详情、章节列表和播放清单；
- 播放定位使用
chapterId，不使用下标； - 断网或服务不可用时，不用
0位置覆盖已有有效进度； - 恢复联网后，以服务端返回状态为准同步显示。