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
EveryPOST that creates or charges something:
- all
POST /v1/project/create/*endpoints, includingugc-studio/{format},clone-video,article-to-video,pdf-to-video,pdf-to-brainrotandcinematic POST /v1/renderPOST /v1/image/remove-backgroundandPOST /v1/image/expandPOST /v1/media/importandPOST /v1/media/uploadPOST /v1/schedule/createPOST /v1/social/account/analyze
Choosing a key
- 1 to 255 printable ASCII characters. Anything else answers
400with a message startingIdempotency-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,409and429: 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 waitRetry-Afterseconds) and retry with the same key.
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.