Idempotency
A network error can leave you not knowing whether a request reached the API. Retrying is the right move, but for expensive work — a video job, a long generation — you don't want it to run twice. Send an Idempotency-Key header and a retry with the same key is recognised as the same request.
curl https://api.cloakray.com/v1/videos \
-H "Authorization: Bearer $CLOAKRAY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 7d3c2e1a-onboarding-video-42" \
-d '{"model": "veo-3.1-fast-generate-preview", "prompt": "A paper boat on a pond", "seconds": 8}'
The key is any string up to 256 characters. A random UUID per logical request works well; generate it once, before the first attempt, and reuse it for every retry.
What a repeat does
| You send | You get |
|---|---|
| The same key and the same body, for a video or a stored response | The job or response the first request created. Nothing runs or is charged again. |
| The same key and the same body, for any other request | A 409 saying the request was already submitted. It was not run again. |
| The same key with a different body or model | A 409. A key belongs to the first request it was used with. |
| A new key | A new request. |
A key is remembered for a day for ordinary requests, seven days for video jobs and thirty days for stored responses.
When to use it
- Always for video generation, which is slow and priced per second.
- For any request your code retries automatically after timeouts or connection errors.
- In job queues that may deliver the same task more than once.
Without the header every request is treated as new, which is what interactive use usually wants.