Which text-to-video API supports idempotency keys?
Reviral's API does. Send an Idempotency-Key header of 1 to 128 characters with POST /api/v1/generate-media, /api/v1/image-ads or /api/v1/ugc-ad. A retry with the same key and body returns the original job and charges nothing new, so an 8-second Veo 3.1 Fast clip at 24 credits (about $0.30) is paid once. A changed body gets HTTP 409.
- 3
- endpoints take the key
- 1–128
- characters per key
- 409
- same key, different body
- Required
- on POST /api/v1/ugc-ad
Which Reviral endpoints accept an Idempotency-Key?
| Endpoint | Idempotency-Key | If the request times out |
|---|---|---|
| POST /api/v1/generate-media | Optional | Resend the same body with the same key: you get the original job back |
| POST /api/v1/ugc-ad | Required (400 idempotency_key_required without it) | Resend the same body with the same key |
| POST /api/v1/image-ads | Optional | Resend the same body with the same key |
| POST /api/v1/render | Not supported | Don't resend blindly: a resend can start and charge a second job. Use generate-media with a key when you need safe retries |
| POST /api/v1/stitch | Not supported | Don't resend blindly: a resend can start a second job |
Checked against the live API on 26 September 2026.
What the API does
How does a safe retry work?
The key is matched per account. Before it starts anything, the API looks for an earlier job from your account with the same key.
Same key, same body: you get that job back with its current status (queued, running, ready or failed). No new job starts and nothing is charged again.
Same key, different body: HTTP 409 idempotency_key_reuse. Pick a new key only when the order is really different.
Two copies sent at the same moment still make one job: the database allows one job per key per account.
On generate-media and image-ads, a retry does not use up your rate limit: a replay is answered before the limit is counted. On ugc-ad the limit is checked first, so a retry counts toward it.
We set no time window on keys. The lookup has no expiry, so a key stays linked to the job it started.
How do you retry a timed-out request safely?
- 01
Make a key from your order
Use a stable value such as your order ID, 1 to 128 characters.
- 02
Send it with the request
Add the header Idempotency-Key: <your order ID> to POST /api/v1/generate-media.
- 03
On a timeout, resend
Send the exact same body with the same key. A 504 from generate-media says: "The generation request timed out. Retry with the same Idempotency-Key."
- 04
Poll the job
Check GET /api/v1/jobs/{id} until it is ready or failed.
- 05
If it failed, use a new key
A replay of a failed job returns that same failed job, so a fresh attempt needs a new key. The failed job's credits come back automatically.
What else do developers ask about idempotency?
Is the header required?+
Only on POST /api/v1/ugc-ad. It is optional on generate-media and image-ads, and worth sending on any paid request you may retry.
How long can a key be?+
1 to 128 characters. An empty or longer key gets a validation error.
Does a retry cost credits?+
No. A retry with the same key and body returns the original job and charges nothing new.
How long is a key remembered?+
We set no time window: the lookup has no expiry.
Can I retry /api/v1/render safely?+
Not with a key: that endpoint does not take one. Check your jobs before resending, or use /api/v1/generate-media with a key.
What happens to credits if the job fails?+
They come back automatically, and the job status shows failed.
API · pay per job
Build with safe retries
The models in our public model list run through /api/v1/generate-media, each with its price in that list. Packs from $4.99 for 400 credits, checked 26 September 2026. Pay by card, or in ringgit (RM) with Touch 'n Go eWallet for credit packs or Visa/Mastercard for monthly plans.
Read the API quickstartLast updated: September 26, 2026