Get started
Idempotency
Retry a timed-out generation request without starting or charging for a duplicate job.
By Wilson Sik Founder, Reviral Last updated
Short answer
Send the same Idempotency-Key header with the exact same body when you retry a timed-out request to generate-media, image-ads or ugc-ad. You get the same job back, not a second job and not a second charge. Use an order ID as the key. A different body with a reused key returns HTTP 409.
| Situation | Without the key | With the key |
|---|---|---|
| A request times out and you send it again | A second job can start, with a second charge | You get the original job back, with no second charge |
| You check the job after a resend | You may have two jobs to track | The replay shows the job's current status: queued, running, ready or failed |
| You change the request on purpose | A new job starts | Use a new key; the old key with a different body returns HTTP 409 idempotency_key_reuse |
Idempotency-Key header
Send a unique value of 1–128 characters with every POST /api/v1/generate-media, POST /api/v1/image-ads, or POST /api/v1/ugc-ad request. The header is required for UGC ads. Use an order ID or another stable business identifier.
Safe retry
If a connection times out, resend the exact body with the same key. The API returns the original job instead of starting another one. A replay returns the job's current status (queued, running, ready or failed); fetch statusUrl for outputs.
curl -X POST "https://reviral.ai/api/v1/generate-media" \
-H "Authorization: Bearer $REVIRAL_API_KEY" \
-H "Idempotency-Key: first-generation" \
-H "Content-Type: application/json" \
--data '{"model":"seedance-2","prompt":"A slow camera move across a quiet lake at sunrise","durationSec":5,"resolution":"720p","aspectRatio":"16:9","maxCredits":106}'Conflict behavior
Reusing a key with a different request body returns HTTP 409 idempotency_key_reuse. Generate a new key only when the intended request is genuinely different.