周限剩余与预计用量 API

接口版本 1 · 更新于 2026-09-21 · 以下数值均为示例，不是实际账号数据。

1. 页面上的百分比代表什么

周限与 5H 是两个独立的限制窗口，不能将两者的百分比相加或相互替代。七天窗口由每个账号的上游重置时间决定，不是固定的周一到周日；五小时窗口也不保证所有账号同时重置。

这里的百分比反映额度，不是请求数、Token 数、美元金额、费用结算比例或“调用成功概率”。周限统计中的 ≥ 90% 属于业务统计与结算口径，额度剩余仍按 100% 计算。例如已用 95% 的剩余为 5%。

“偏少”“合适”等标签只是页面对预测值的分档提示。预计值低表示以当前速度可能有较多额度在重置时未被使用；预计值高表示消耗较快。它们不改变百分比含义，也不保证每个账号均能立即调用。

2. 接口调用与登录

GET https://lighthou.org/api/quota

无需查询参数。返回当前登录用户的汇总指标，不接受用于切换用户的 user_id 参数。使用网站现有的登录会话进行鉴权，其他用户的数据不会包含在返回值中。

浏览器已经登录时可直接访问接口。程序调用先通过 POST /api/login，JSON 请求体为 {"key":"dfk_你的密钥"}，保存响应中的 lh_session Cookie，然后携带 Cookie 请求本接口。会话有效期为 7 天，过期返回 401，需重新登录。登录响应正文不返回 Token。

如已有本站会话 Token，也支持 Authorization: Bearer <lh_session 的值>。Bearer 的值是本站会话 Token，不能直接填写 dfk_ 密钥。接口不支持匿名查询，也不支持跨域浏览器直接读取；外部网站可由自己的服务端调用。

cURL 示例

以下 Bash 示例通过隐藏输入读取密钥，不将真实密钥写进命令历史。Cookie 文件包含登录凭据，应保存在自己的私有目录。

umask 077
read -r -s -p '请输入 dfk_ 密钥: ' quota_login_key
printf '\n'
printf '%s' "$quota_login_key" |
  python3 -c 'import json,sys; print(json.dumps({"key":sys.stdin.read()}))' |
  curl --fail-with-body --silent --show-error \
    -c ./lighthouse-cookies.txt \
    -H 'Content-Type: application/json' \
    --data-binary @- https://lighthou.org/api/login
unset quota_login_key

curl --fail-with-body --silent --show-error \
  -b ./lighthouse-cookies.txt \
  https://lighthou.org/api/quota

首次登录会启动后台同步，第一次查询可能尚无数据。可等待约一个同步周期后重试；如需主动拉取，调用 POST /api/refresh 并携带同一个 Cookie，成功后再查询。GET /api/quota 本身只读取本地快照，不触发上游同步、不改变额度或结算记录。

Python 示例（仅使用标准库）

import getpass
import http.cookiejar
import json
import urllib.error
import urllib.request

base = 'https://lighthou.org'
client = urllib.request.build_opener(
    urllib.request.HTTPCookieProcessor(http.cookiejar.CookieJar()))
login = urllib.request.Request(
    base + '/api/login',
    data=json.dumps({'key': getpass.getpass('dfk_ 密钥: ')}).encode(),
    headers={'Content-Type': 'application/json'}, method='POST')
try:
    with client.open(login, timeout=30) as response:
        json.load(response)
    with client.open(base + '/api/quota', timeout=30) as response:
        data = json.load(response)
    print('周限当前已用:', data['weekly']['current_used_pct'])
    print('周限当前剩余:', data['weekly']['current_remaining_pct'])
    print('5H 重置前预计已用:', data['projection']['projected_used_pct'])
    print('5H 届时预计剩余:', data['projection']['projected_remaining_pct'])
    print('数据是否过期或同步异常:', data['freshness']['stale'])
except urllib.error.HTTPError as error:
    print('HTTP 状态:', error.code)
    print(error.read().decode())

业务程序必须分别处理 null（未知）、0（确实为零）和数据过期状态，不能用 value or 0 等方式把未知当作零。建议每 60 秒查询一次；频繁读取不会让上游数据更新更快。

3. 返回示例

HTTP 200，Content-Type: application/json; charset=utf-8，Cache-Control: no-store。所有 _pct 字段的 31 都表示 31%，不是 0.31。百分比和等效账号数保留至多一位小数；网页额度卡片与接口使用相同精度。

{
  "api_version": "1",
  "calculated_at": "2026-09-21T05:00:00Z",
  "scope": "serving_non_archived_accounts",
  "serving_accounts": 2,
  "weekly": {
    "window_seconds": 604800,
    "current_used_pct": 31.0,
    "current_remaining_pct": 69.0,
    "total_remaining_pct_points": 138.0,
    "equivalent_full_accounts": 1.4,
    "accounts_with_data": 2,
    "accounts_without_data": 0
  },
  "five_hour": {
    "window_seconds": 18000,
    "current_used_pct": 15.5,
    "current_remaining_pct": 84.5,
    "total_remaining_pct_points": 169.0,
    "equivalent_full_accounts": 1.7,
    "accounts_with_data": 2,
    "accounts_without_data": 0
  },
  "projection": {
    "window_seconds": 18000,
    "method": "average_used_pct / (average_elapsed_pct / 100)",
    "status": "available",
    "accounts_analyzed": 2,
    "accounts_excluded": 0,
    "current_used_pct": 15.5,
    "current_remaining_pct": 84.5,
    "elapsed_pct": 50.0,
    "projected_used_pct": 31.0,
    "projected_remaining_pct": 69.0,
    "projected_exceeds_quota": false
  },
  "freshness": {
    "snapshot_oldest_at": "2026-09-21T05:00:00Z",
    "snapshot_latest_at": "2026-09-21T05:00:00Z",
    "last_poll_at": "2026-09-21T05:00:00Z",
    "snapshot_age_seconds": 0,
    "poll_interval_seconds": 60,
    "stale_after_seconds": 120,
    "sync_failed": false,
    "stale": false
  },
  "documentation_url": "/docs/quota-api"
}

4. 字段说明

顶层字段

weekly 与 five_hour

projection：五小时窗口预测

freshness：数据是否够新

5. 计算口径与边界

所有指标与首页共用计算逻辑。仅统计当前用户 status = serving 且没有有效最终归档记录的账号；冷却、封禁等其他状态不参与。完成周限结算但仍服务中的账号继续计入。页面“周限统计 ≥ 50% / ≥ 90%”面向当前账号列表，其范围与这里的服务中额度汇总不同。

1. 周限当前已用 = 有周限数据账号的用量之和 ÷ 账号数。当前剩余 = 每个账号 max(0, 100 − 用量) 的平均值。没有数据返回 null。
2. 例如两个账号周限分别已用 20% 和 42%，平均已用为 31%，平均剩余为 69%，总剩余为 80 + 58 = 138 个百分比点，等效满额账号为 1.38（接口四舍五入到 1.4）。
3. 预测只选择有五小时用量、重置时间可解析，且距离重置大于 0 秒、不超过 18000 秒的账号。重置时间过期、缺失或超过五小时的账号不参与预测；仍可参与有用量数据的当前额度统计。
4. 每个账号的时间进度 = (18000 − 距离重置秒数) ÷ 18000 × 100。平均时间进度达到 2%（平均已过去 6 分钟）后，预计已用 = 平均当前已用 ÷ (平均时间进度 / 100)。这是“均值的比值”，不是各账号预测百分比的平均值。
5. 时间进度以本次请求时间计算，当前用量以最新同步快照为准。计算使用未舍入的时间进度，最终字段保留一位小数；用响应中已舍入字段反算可能有微小差异。
6. 预计剩余最低为 0。预计已用 120% 表示按当前速度可能在重置前耗尽，不表示已经实际用了 120%，也不会返回“剩余 −20%”。若上游实际用量超过 100%，该账号当前剩余也按 0 计算。

预测假设后续平均速度不变，不考虑未来流量变化、调度策略、单个账号额度大小差异或其他窗口的限制。它是整体参考值，不保证每个账号都能撑到重置。五小时窗口与周限任何一项耗尽都可能限制调用；封禁、暂停或服务故障也可能影响可用性。

6. 空数据、错误与更新

• 没有服务中账号：HTTP 200，serving_accounts 为 0；当前用量和剩余字段为 null；projection.status 为 no_valid_window；freshness.stale 为 true。
• 部分账号缺少周限数据：只统计有数据的账号，同时返回 accounts_without_data，不能根据平均值推断缺失账号的额度。
• 窗口刚开始：projection.status 为 insufficient_elapsed_time；projected_used_pct、projected_remaining_pct、projected_exceeds_quota 为 null，当前用量仍可返回。
• 零用量且时间进度足够：预计已用为 0、预计剩余为 100，是有效数值，不等于没有数据。
• 未登录、会话无效或过期：HTTP 401，正文为 {"error":"unauthenticated"}。
• 上游同步失败：本接口仍可返回 HTTP 200 和本地已有快照，同时 freshness.sync_failed 与 freshness.stale 为 true。HTTP 200 不表示数据刚刚从上游更新。

本地同步时间表示本站何时接收到上游返回的数据，不保证上游用量本身没有延迟。接口不会因本地时钟越过重置时间就把当前用量自动归零；要等上游新快照确认。首次登录或同步异常时，请结合时间、数据覆盖账号数和 stale 字段判断。

兼容性：原 GET /api/dashboard 保留现有字段，并新增 quota 对象；该对象与 GET /api/quota 使用相同计算逻辑。不同请求间若时间推进或发生同步，预测值可能略有变化。