快速开始

快速开始

API

MCP 服务
API 概览认证可用模型

指南

快速开始任务与轮询错误处理

计费与限制

定价与积分速率限制

集成

OpenAPI 规范与 SDK
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-Remaining429 时恒为 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');
}

两条比重试次数更重要的规则:

  1. POST /3d/generations 不要无脑重试。 429 表示请求在创建任务前就被挡下,重试安全;但 5xx 不是同一回事——见 错误处理。
  2. 退避,而不是收紧循环。 翻倍通常就够;被限流后缩短间隔只会让你一直卡在限流里。

额度规划

工作负载单任务请求数每分钟可跑任务数(60 rpm 上限)
异步 + 5 秒轮询,生成约 60 秒约 13 次约 4 个
异步 + 10 秒轮询,生成约 60 秒约 7 次约 8 个
同步模式(单请求)1 次约 60 个

批量作业时,若生成能稳定压在 55 秒内,优先用 mode: "sync";否则用队列驱动异步任务,把并发 worker 数量压小,而不是把所有任务一起轮询。

定价与积分

积分如何扣、何时退,以及怎么读余额

OpenAPI 规范与 SDK

导入 Postman / Insomnia / Swagger UI,或直接生成带类型的客户端

目录

速率限制
超限时
退避写法
额度规划