API
速率限制
请求额度、429 响应,以及正确的退避方式
速率限制
所有 /api/v1/* 请求共用一个按账号计算的额度:
| 范围 | 限制 |
|---|---|
全部 /api/v1/* 端点 | 60 次 / 分钟 |
窗口是固定的 60 秒桶,按账号计数——不是按端点,也不是按 API Key。同一账号下的两个 Key 共享额度,而且轮询一次和创建一次生成等价。
这个数字是刻意压低的:2 秒一次的轮询循环会吃掉 60 次里的 30 次。 同时跑多个任务就得把轮询放慢或批量读取——见 任务与轮询。
超限时
HTTP/2 429
retry-after: 12
x-ratelimit-remaining: 0
x-ratelimit-reset: 1723000060{
"error": {
"message": "Rate limit exceeded",
"type": "rate_limit_error",
"code": null,
"param": null
}
}| 响应头 | 含义 |
|---|---|
Retry-After | 还需等待多少秒才会被接受 |
X-RateLimit-Remaining | 429 时恒为 0 |
X-RateLimit-Reset | 窗口重置的 Unix 时间戳(秒) |
请按 Retry-After 等待,不要自己估。被 429 拒绝的请求不扣积分,也没有创建任务。
退避写法
async function requestWithRetry(url: string, init: RequestInit) {
for (let attempt = 0; attempt < 4; attempt++) {
const res = await fetch(url, init);
if (res.status !== 429) return res;
const retryAfter = Number(res.headers.get('retry-after') ?? '5');
// 加抖动,避免并发 worker 同一瞬间集体醒来
const wait = retryAfter * 1000 + Math.random() * 500;
await new Promise((r) => setTimeout(r, wait));
}
throw new Error('Still rate limited after 4 attempts');
}两条比重试次数更重要的规则:
POST /3d/generations不要无脑重试。 429 表示请求在创建任务前就被挡下,重试安全;但 5xx 不是同一回事——见 错误处理。- 退避,而不是收紧循环。 翻倍通常就够;被限流后缩短间隔只会让你一直卡在限流里。
额度规划
| 工作负载 | 单任务请求数 | 每分钟可跑任务数(60 rpm 上限) |
|---|---|---|
| 异步 + 5 秒轮询,生成约 60 秒 | 约 13 次 | 约 4 个 |
| 异步 + 10 秒轮询,生成约 60 秒 | 约 7 次 | 约 8 个 |
| 同步模式(单请求) | 1 次 | 约 60 个 |
批量作业时,若生成能稳定压在 55 秒内,优先用 mode: "sync";否则用队列驱动异步任务,把并发 worker 数量压小,而不是把所有任务一起轮询。