跳转到内容
Zelnum API

限流规则

请求受两层独立限流约束，更严的一层生效：

  1. 按 API Key —— 当前 Key 的额度，请以此规划调用量。
  2. 按 IP 地址 —— 同一网络出口下所有 Key 共享的粗粒度上限。

IP 层用于兜住滥用。除非你把大量流量集中在单一出口 IP，否则真正先触顶的一定是按 Key 的额度。

接口限额
GET /v1/products · GET /v1/balance · GET /v1/api-key · GET /v1/tasks/{token} · GET /v1/tasks/{token}/result · GET /v1/tasks/{token}/download每个 API Key 60 次 / 分钟（每 IP 120 次 / 分钟）
POST /v1/detect · POST /v1/detect/file每个 API Key 10 次 / 分钟（每 IP 30 次 / 分钟）
POST /v1/realtime/check/{series} · POST /v1/realtime/detect令牌桶 —— 按 API Key：容量 60，每秒回填 1 个（持续约 60 次 / 分钟）
按账号：容量 120，每秒回填 2 个 · IP 层：180 次 / 分钟

实时检测不是固定的每分钟计数器，而是令牌桶：可以一次打满 60 个令牌，随后每秒回填 1 个。因此稳定吞吐约为每 Key 60 次 / 分钟，短时突发由桶容量吸收。

响应头

Section titled “响应头”

每个被限流的响应，以及每个成功的实时检测响应，都会告诉你当前状态：

响应头含义
X-RateLimit-Limit本次生效的上限
X-RateLimit-Remaining当前窗口剩余次数（或令牌数）
Retry-After建议等待秒数，出现在 429 上
X-RateLimit-Reset窗口重置的 Unix 时间戳，出现在 429 上

触发 429 之后

Section titled “触发 429 之后”

按 Retry-After 给出的秒数停止请求，之后采用指数退避恢复。响应体能告诉你撞的是哪一层：

{ "message": "Too many requests. Limit: 60/min." }
触顶层状态码响应体
按 Key —— 通用429{"message":"Too many requests. Limit: 60/min."}
按 Key —— 检测429{"message":"Too many detection requests. Limit: 10/min."}
按 Key —— 实时429{"code":"realtime_rate_limited","message":"Realtime detection rate limit exceeded.","retry_after":12}
按 IP429{"message":"Too many requests from this network."}

只有实时检测的拒绝带机器可读的 code；其余是明文提示，文本里写明了生效的限额。请以 HTTP 状态码和 Retry-After 作为分支依据，把 message 用于排查。