幂等与限流
使用 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-after | HTTP 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 - 任务
metadataJSON:≤ 4 KB