API 文档

面向普通用户的开放接口。Base URL：https://api.archive-at-home.org，CORS 不限来源。示例中的 sk-… 替换为你的 API Key。

认证与凭证

所有业务接口通过 Authorization 头携带 API Key：

HTTP

Authorization: Bearer sk-xxxxxxxxxxxx

API Key 通过 Telegram 登录获取（首次登录自动注册）：在使用页点「Telegram 登录」，或直接访问登录中转页 GET /auth/telegram/login（见下文集成说明）。 Key 泄露时调用重置接口换新，旧 Key 立即失效。

来源标记 X-Client（可选）

请求头 X-Client: 大类/应用标识 用于标记调用来源并写入任务日志，例如 bot/tg-official、tampermonkey/aah-download-helper、app/jhentai。仅接受小写字母、数字、-、_、. 和单个 /，最长 64 字符；不传或非法时服务端按 User-Agent 自动识别。

接口一览

POST /api/v1/parse

核心接口：请求解析画廊的归档下载链接。

请求体

字段	类型	必填	说明
`gallery_id`	string	是	画廊 ID，即链接 `/g/{id}/{key}/` 中的数字
`gallery_key`	string	是	画廊密钥，链接中的第二段
`force`	boolean	否	为 `true` 时忽略 7 天缓存强制重新解析（仍会消耗 GP）

响应

字段	类型	说明
`cached`	boolean	是否命中缓存。命中时不产生 GP 消耗
`gp_cost`	number	本次新解析实际消耗的 GP（缓存命中时无此字段）
`archive_url`	string	归档下载链接

curl

curl -X POST https://api.archive-at-home.org/api/v1/parse \
  -H "Authorization: Bearer sk-xxxxxxxxxxxx" \
  -H "X-Client: bot/my-app" \
  -H "Content-Type: application/json" \
  -d '{"gallery_id":"3858751","gallery_key":"d3de60e849"}'

试一试

强制重新解析（忽略缓存）

GET /api/v1/me

获取当前用户信息、等级与令牌余额。

响应示例

{
  "user": {
    "id": "abc123",
    "nickname": "用户昵称",
    "provider": "telegram",
    "telegram_id": 1234567890,
    "api_key": "sk-xxxxxxxxxxxx",
    "status": "active",
    "level": 0,
    "created_at": "2026-02-11T00:00:00Z"
  },
  "balance": 604800
}

试一试

GET /api/v1/me/balance

只取当前令牌余额。令牌以固定速率自动补充，上限由用户等级决定。

响应示例

{ "balance": 500000 }

试一试

POST /api/v1/me/reset-key

重置 API Key，旧 Key 立即失效。怀疑泄露时使用。

⚠

重置后所有使用旧 Key 的客户端（油猴脚本、JHenTai、Bot 绑定等）都需要更新为新 Key。

试一试

GET /auth/telegram/login

Telegram 登录中转页：第三方应用引导用户登录并回收 API Key。

URL 参数

参数	必填	说明
`redirect_url`	否	登录成功后跳转地址，API Key 以查询参数形式附加
`param_name`	否	附加 API Key 的参数名，默认 `start`
`botId`	否	Telegram Bot ID，用于 Mini App 内免跳转登录

示例：

登录跳转

https://api.archive-at-home.org/auth/telegram/login?redirect_url=https://your-app.example/callback&param_name=key

用户授权后跳转到 https://your-app.example/callback?key=sk-…。不传 redirect_url 时页面直接展示 Key 供用户复制。

运行规则

令牌桶限流

解析消耗令牌（与 GP 等价）。普通用户令牌以 1 GP/秒 自动补充，容量上限 604,800（约 7 天积累量）；等级 ≥1 用户为 5 GP/秒、3,024,000。令牌不足时接口返回 rate limited, try again later。

私有化缓存与请求合并

解析结果按「用户 × 画廊」缓存 7 天，期间重复请求直接命中，不重复消耗 GP；同一用户对同一画廊的并发请求自动合并为一次解析。需要最新链接时用 force 参数显式绕过缓存。

成本追踪

每次新解析返回 gp_cost 并写入任务日志，即节点账号实际消耗的 GP。