Idempotency

The Idempotency-Key header lets you safely retry the same POST /v1/generations after network errors or timeouts. The replayed request returns the exact same response without creating a second task or charging twice.

How to use

Generate a unique key on the client (UUID or your own business identifier) and pass it in the Idempotency-Key header. Tie the key to the entity you're protecting from duplicate processing (e.g. order ID + attempt number).

POST /v1/generations
Idempotency-Key: order-42-attempt-1
Content-Type: application/json
Authorization: Bearer sk_live_...

{ "provider": "google_banana",
  "model": "gemini-3.1-flash-image-preview",
  "method": "text_to_image",
  "params": { "prompt": "a cat" } }

Key format

• Allowed characters: A–Z, a–z, 0–9, and _ : -
• Length: 1 to 255 characters.
• Scope: public_api.generations. The same key cannot be reused across different endpoints with different bodies.

Outcomes

• Same key + same body + previous request finished → cached response is returned (same task_id, same HTTP status).
• Same key + same body + previous request still in flight → idempotency_key_in_use error. Wait 1–2 seconds and retry.
• Same key + different body → idempotency_key_mismatch. Use a new key.

Time to live

Cached responses live for 24 hours after completion; the in-flight guard is 30 seconds. After 24h the key can be reused, but you should generate a new one.

Recommendations

• Use UUIDv4 or a tuple (entity_id × attempt_number). Don't put secrets in the key — it gets logged.
• Persist the key in your own DB at task creation time so retries can reuse the right key.
• Never send two requests with the same key but different parameters — you'll get 409 mismatch and waste time debugging.