Skip to main content
A create request that times out leaves you guessing: the project may or may not exist, and may or may not have been charged. Send an Idempotency-Key header and you can simply send the request again. The first request runs; for the next 24 hours the same key with the same body gets that first answer back, and nothing is created or charged a second time.

Which endpoints accept it

Every POST that creates or charges something:
  • all POST /v1/project/create/* endpoints, including ugc-studio/{format}, clone-video, article-to-video, pdf-to-video, pdf-to-brainrot and cinematic
  • POST /v1/render
  • POST /v1/image/remove-background and POST /v1/image/expand
  • POST /v1/media/import and POST /v1/media/upload
  • POST /v1/schedule/create
  • POST /v1/social/account/analyze
The header is optional. Without it, these endpoints behave as before: every request runs.

Choosing a key

  • 1 to 255 printable ASCII characters. Anything else answers 400 with a message starting Idempotency-Key:.
  • One key per operation you want to happen once, for example your own job or order id (order-1042-video) or a UUID you store before sending. Generate it once and reuse it on every retry of that operation; a new random key per attempt protects nothing.
  • Keys belong to your team and to the endpoint: the same key on another endpoint, or from another team, is a different request.

What you get back

The body is compared as JSON, so key order and whitespace do not matter. Answers that do not settle the request are not kept, so a retry with the same key runs again:
  • a 5xx: the request failed on our side, retrying is safe;
  • 401, 402, 403, 409 and 429: refused before anything ran (bad API key, no credits or missing provider keys, no access to the product, the key still in use, the rate limit). Fix the cause (or wait Retry-After seconds) and retry with the same key.
Other 4xx answers (a validation error, for example) are kept like a success: fix the request and send it with a new key. After 24 hours a key is forgotten and the same key runs the request again.

Retrying a create

The MCP server tools do not send an Idempotency-Key. When an MCP create call times out, check list_projects before calling it again.