Skip to Content

幂等与限流

使用 Idempotency-Key 安全重试,了解每分钟提交限流、进行中任务数上限与请求体大小限制。

幂等创建任务

POST /v1/tasks 支持可选请求头 Idempotency-Key(最长 255 个字符,推荐使用 UUID 或业务订单号):

  • 24 小时内相同 Key + 相同请求体:以 HTTP 200 返回原来的任务对象(新建任务是 201),不重复建任务、不重复冻结。
  • 24 小时内相同 Key + 不同请求体:返回 HTTP 409(idempotency_conflict)。
curl -X POST https://api.kerox.ai/v1/tasks \
  -H "Authorization: Bearer $KEROX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-a1001-shot-1" \
  -d '{
    "model": "bytedance/seedream-5.5",
    "input": { "prompt": "a quiet coastal lighthouse at dusk", "size": "2K" }
  }'

限流与并发上限

POST /v1/tasks 的每个响应都带限流头:

响应头含义
x-ratelimit-limit当前账户每分钟允许提交的任务数
x-ratelimit-remaining当前时间窗口内剩余可提交次数
x-ratelimit-reset距离窗口重置的秒数
retry-afterHTTP 429 rate_limited 时附带,建议等待的秒数

另一个上限管同时进行中的任务数(queued 或 running)。超过后 POST /v1/tasks 返回 HTTP 429 concurrency_limited:等有任务结束后再提交。

上传另有上限:POST /v1/files 每个账户每分钟最多 60 次上传,超过后返回 HTTP 429 rate_limited 并带 retry-after。同一个 IP 地址的提交和上传还有一个更高的每分钟上限。

GET /v1/account 会返回任务的这两个上限(limits.max_per_minute、limits.max_concurrent)和进行中的任务数(running_tasks)。

体积限制

  • JSON 请求体:≤ 4 MB
  • 内联 base64 data URI:单次请求合计 ≤ 3 MB(更大文件请改用 POST /v1/files)
  • 表单直传(multipart):≤ 4 MB
  • 预签名上传(/v1/files):≤ 200 MB
  • 任务 metadata JSON:≤ 4 KB