Skip to main content

Rate limits & idempotency

Rate limits​

Requests are rate limited per API key. Limits depend on your account and on any limits you set on the key; the developer platform shows the limits that apply to each key.

When you go over a limit the API returns 429 Too Many Requests with these headers:

HeaderDescription
Retry-AfterSeconds to wait before retrying.
X-RateLimit-LimitRequests allowed in the current window.
X-RateLimit-RemainingRequests left in the current window.
X-RateLimit-ResetUnix time when the window resets.

Wait for Retry-After, then retry with exponential backoff. To ask for higher limits, contact support.

Idempotency​

POST, PUT and PATCH requests to /generation/*, and POST /v1/images/generations and POST /v1/videos, accept an optional Idempotency-Key header: a unique string you create per logical request (a UUID works well). If you send the same request again with the same key within 24 hours, you get the stored answer back instead of a second run. This makes it safe to retry a generation after a network timeout without paying twice.

curl https://api.funai.art/generation/v1/generate \
-H "Authorization: Bearer $FUNAI_API_KEY" \
-H "Idempotency-Key: 3f29b6a2-6c31-4e0a-9d1b-6a1e2f6c9b41" \
-H "Content-Type: application/json" \
-d '{ "model_id": "flux-schnell", "workflow": "text_to_image", "prompt": "A red fox in snow" }'
  • Keys are scoped to your account and kept for 24 hours.
  • Use a new key for each new request. Reusing a key returns the first answer.
  • Reusing a key while the first request is still running, or with a different body, returns 409 with type idempotency_conflict.
  • If the first attempt got an error answer (not a timeout), the stored answer is that error. Retry with a new key.