Core concepts

Idempotency

The Idempotency-Key header lets you resend a POST request safely: after a network failure or a timeout, the same request resent with the same key neither creates nor charges a second generation.

Rule	Value
Routes	Every `POST` request of `/v1`: creations and cancellation. The header is ignored on other methods.
Format	1 to 255 characters. A UUID v4 is suitable.
Validity	24 hours after the first request.
Scope	Specific to the organization and the mode (test or live) of the API key.

Usage

Generate one idempotency key per operation, and build the request body once.
Send the request with the Idempotency-Key header.
After a network failure or a timeout, resend exactly the same request: same method, same path, same key and same body, byte for byte. A different space or field order is enough to make it another request.

Response to a resend

First request	Response
Succeeded	Its response, replayed as is, with the `idempotent-replayed: true` header. Nothing is run or charged.
Still in progress	`409 idempotency_key_in_use`: retry later with the same key.
Different from this one (method, path or body)	`409 idempotency_key_reused`: a new request requires a new key.
Refused (status other than `2xx`)	The resend is processed as a new request.
Accepted, but no response received (failure or interruption on our side)	The generation it created, in its current state (`200` if it has ended, `202` if it is in progress), with `idempotent-replayed: true`. Nothing more is created or charged.

Only a 2xx response is stored: a refusal releases the key. Fix the cause (or, after a 429 or a 503, wait for the delay given by Retry-After), then resend the request with the same key.
A creation request waits for the end of the generation, usually 1 to 3 minutes. Set your HTTP client timeout to 5 minutes: otherwise, the resend arrives during the first request and gets 409 idempotency_key_in_use.
If the first request was interrupted on our side without responding, the key stays reserved for up to 10 minutes (409 idempotency_key_in_use). After that, a resend returns the generation created by the first request, or is processed as a new request if no generation was created.
A replayed response reflects the state of the generation at the time of the first request: it can be in_progress in it, and its output[].url expire 15 minutes after that first response. Retrieve the generation to get its current state.
An empty header, a header longer than 255 characters or a repeated header gets 400 parameter_invalid, with param set to Idempotency-Key.

curl https://api.renderthink.com/v1/renders \
  -H "Authorization: Bearer $RENDERTHINK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2d9e-7b4a-4f0e-9c3d-2a8b5e1f7c40" \
  -d '{"image": "https://developers.renderthink.com/assets/scenes/sejour-charpente-export.webp", "quality": "2k"}'