启用密码锁时（本部署默认开启），除 /、/assets/*、/api/login、/api-docs/* 外，其余接口需鉴权。
方式 A（推荐，浏览器/脚本会话）：先登录拿 Cookie，后续请求带 Cookie。
curl -c cookie.txt -X POST "$BASE/api/login" \
-H 'Content-Type: application/json' \
-d '{"password":"你的密码"}'
curl -b cookie.txt "$BASE/api/status"
方式 B（脚本）：每次请求带请求头 x-tomato-password。
curl -H "x-tomato-password: 你的密码" "$BASE/api/status"
密码见部署方提供的密钥（本仓库 docs/ops/k8s/app.env），请勿写进公开仓库或前端代码。
# 1) 登录
curl -c cookie.txt -X POST "$BASE/api/login" \
-H 'Content-Type: application/json' \
-d '{"password":"你的密码"}'
# 2) 创建下载任务（一次只能有一个进行中的任务）
curl -b cookie.txt -X POST "$BASE/api/jobs" \
-H 'Content-Type: application/json' \
-d '{"book_id":"7625904970805546009"}'
# 3) 轮询任务状态
curl -b cookie.txt "$BASE/api/jobs"
# 4) 下载完成后从下载库取文件
curl -b cookie.txt "$BASE/api/library"
# 文件直链示例：
# curl -b cookie.txt -LO "$BASE/download/相对路径/xxx.txt"
服务状态、版本、是否锁定、保存目录等。
{
"version": "2.4.13",
"locked": true,
"save_dir": "/data",
"bind_addr": "0.0.0.0:18423",
"config": { "use_official_api": true, "novel_format": "..." }
}
| 参数 | 说明 |
|---|---|
q | 书名关键词（必填） |
{ "items": [ { "book_id": "...", "title": "...", "author": "..." } ] }
预览书籍元数据与章节数，创建任务前可调用。
清理预览产生的临时封面目录。
| 参数 | 说明 |
|---|---|
id | 按任务 ID 过滤 |
name | 按书名/Book ID 模糊过滤 |
all=true | 返回全部（默认会隐藏约 2 小时前已完成任务） |
{ "items": [ { "id": 1, "book_id": "...", "title": "...", "state": "running|done|failed|...", "progress": {...} } ] }
{
"book_id": "7625904970805546009",
"range_start": 1,
"range_end": 50
}
range_start/range_end 可选，必须成对出现，章节号从 1 开始。同时只允许 1 个活跃任务，否则 429。
取消任务。
删除任务记录。
{ "choice": "书名选项值" }
{ "choice": "txt" }
当配置要求下载后选择书名/格式时使用。
浏览已下载文件目录。
下载单个文件。
打包目录为 zip 下载。
下载历史记录。
扫描本地书是否有远端新章节。
快捷配置（格式、有声书等）。
完整配置字段。
原始 YAML。
本部署默认输出格式为 txt。
429）。