Idempotency

A network error or a timeout can leave you unsure whether a create request reached Five API. Without protection, retrying it can create a second task and hold its credits a second time. The Idempotency-Key header removes that risk.

How it works

Send a key of your choice with the create request:

curl https://api.fiveapi.ai/v1/video-fast/v1.0/text-to-video \
  -H "Authorization: Bearer $FIVEAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8812-attempt-1" \
  -d '{"prompt": "a paper boat floating down a rain gutter", "duration": 5, "resolution": "480p"}'

The key is any string up to 128 characters, unique within your account.
A successful response is stored with the key for 24 hours.
If you send the same key with the same body again, Five API returns the stored response with the header Idempotent-Replayed: true. No second task is created and nothing is charged twice.

Situation	Result
No `Idempotency-Key`	Every request creates a new task
First request with a key	Processed normally; a successful response is stored for 24 hours
Same key and same body within 24 hours	The stored response is replayed with `Idempotent-Replayed: true`
Same key, different body	`400 idempotency_key_reused`
Same key while the first request is still running	`409 idempotency_in_progress`: retry in a moment
The first request failed (`4xx` or `5xx`)	Nothing was stored; retry with the same key

A replay matches the method, the path and the exact raw body. When you retry, send the byte-identical body, not a re-serialized copy whose key order or spacing could differ.

Choose good keys

Derive the key from your own record, so every retry of the same job sends the same key:

// Good: stable across retries of the same job
const idempotencyKey = `order-${order.id}-render-${order.renderAttempt}`;

// Bad: random per call. A retry creates a second task and a second charge
// const idempotencyKey = crypto.randomUUID();

Use a new key when you really want a new task, for example to resubmit after a task failed.

When to send it

The header is optional, but send it whenever your client retries automatically: on timeouts, network errors, 429, 500 and 503. See the retry strategy. Without a key, a timed-out create request is ambiguous: the task may or may not exist. If that happens, check GET /v1/tasks?created_after=... for a task with your metadata before you submit again. The header applies to the create endpoints. Reads are naturally safe to repeat, and cancelling an already cancelled task answers 200 again.

Get started

Core concepts

Guides

Build with AI

Resources

How it works

Choose good keys

When to send it

​How it works

​Choose good keys

​When to send it

How it works

Choose good keys

When to send it