Idempotency & limits
Safe retries with Idempotency-Key, per-minute rate limits, the cap on tasks in progress, and payload limits.
Idempotent task creation
POST /v1/tasks supports an optional Idempotency-Key header (up to 255 characters, such as a UUID or your order ID).
- Same key, same body within 24 hours: Returns the original task object with HTTP
200(a new task is201), without creating a duplicate task or holding balance twice. - Same key, different body within 24 hours: Returns 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" }
}'Rate limits & concurrency
POST /v1/tasks returns rate-limit headers on every response:
| Header | Meaning |
|---|---|
x-ratelimit-limit | Allowed submissions per minute for your account |
x-ratelimit-remaining | Remaining submissions in the current window |
x-ratelimit-reset | Seconds until the current window resets |
retry-after | Seconds to wait, on HTTP 429 rate_limited |
A second limit caps the tasks you can have in progress at once (queued or running). Over it, POST /v1/tasks returns HTTP 429 concurrency_limited: wait for a task to finish, then submit again.
Uploads have their own limit: POST /v1/files accepts 60 uploads per minute per account. Over it, the response is HTTP 429 rate_limited with retry-after. A higher per-minute ceiling per IP address also applies to submissions and uploads.
GET /v1/account shows both task limits (limits.max_per_minute, limits.max_concurrent) and the number of tasks in progress (running_tasks).
Size limits
- JSON request body: ≤ 4 MB
- Inline base64 data URIs: ≤ 3 MB combined per request (use
POST /v1/filesfor larger inputs) - Direct multipart file upload: ≤ 4 MB
- Presigned file upload (
/v1/files): ≤ 200 MB - Task
metadataJSON: ≤ 4 KB