> ## Documentation Index
> Fetch the complete documentation index at: https://testweb2-docs-openapi.test765.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Five API is a video generation REST API. Base URL: https://api.fiveapi.ai. Authenticate with the header Authorization: Bearer <API key>; read the key from the FIVEAPI_API_KEY environment variable and never hard-code it.
> Every generation is an asynchronous task: POST /v1/{brand}/{version}/{task} returns a queued task, then poll GET /v1/tasks/{task_id} or receive a signed webhook, and download output.video.url before expires_at (7 days).
> The OpenAPI spec is at https://docs.fiveapi.ai/api-reference/openapi.yaml. An installable agent skill: npx skills add https://docs.fiveapi.ai

# Idempotency

> Retry task creation safely with the Idempotency-Key header, so a retry never creates or charges a second task.

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:

```bash theme={null}
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 |

> [!NOTE]
>
> 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:

```javascript theme={null}
// 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](https://testweb2-docs-openapi.test765.com/concepts/errors.md#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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.