Idempotency
Networks fail. If a submit times out you cannot know whether the job was made. The Idempotency-Key header makes it safe to try again.
POST /v1/jobs requires an Idempotency-Key header: any string you choose of up to 200 characters. Use a UUID, or an id of your own that identifies the thing you are generating (for example catalogue-sku-1234-hero-v2).
| You send | You get |
|---|---|
| A new key | A new job, 201. Its credits are reserved and it is queued. |
| The same key and the same request | The job that was already made. No second job, no second reservation. |
| The same key and a different request (another model or other settings) | 409 idempotency_key_reused. Nothing changes. |
| No key | 422 idempotency_key_required. |
Rules:
- Keys are scoped to your API key. Two API keys can use the same string without clashing, and a key never clashes with the web app's.
- "Same request" means the same model and the same
input. - A request that is refused (not enough credits, a spending limit, invalid settings) makes no job and reserves nothing. Fix it and resend; you can reuse the key.
- Generate the key before the first attempt and keep it for every retry of that same job.
Retrying
Retry with the same key after a timeout, a connection error, a 5xx, or a 429 (wait for Retry-After). Do not retry 4xx errors other than 429 without changing the request.
curl -sS -X POST "$VOAO_API/v1/jobs" \
-H "Authorization: Bearer $VOAO_API_KEY" \
-H "Idempotency-Key: catalogue-sku-1234-hero-v2" \
-H "Content-Type: application/json" \
-d '{"model":"fake-image","input":{"prompt":"a red bicycle"}}'Running it twice returns the same job id both times.