Idempotency

A retry shouldn't cost you twice. Send an Idempotency-Key header on any POST and Vidocu will run the request once, no matter how many times it arrives.

curl -X POST https://api.vidocu.ai/v1/videos/vid_abc123/export \
  -H "Authorization: Bearer vdo_live_your_key_here" \
  -H "Idempotency-Key: 8f14e45f-ceea-167a-5a36-dedd4bea2543" \
  -H "Content-Type: application/json" \
  -d '{"ratio": "9:16"}'

Use any unique string - a UUID per logical operation is the usual choice.

What happens

Situation	Result
First request with this key	Runs normally; the response is stored
Repeat, same key and body	The stored response, with Idempotent-Replay: true
Repeat while the first is still running	409 conflict - retry shortly
Same key, different body	409 conflict - the key is already spoken for
First attempt failed (4xx/5xx)	The key is released, so a retry genuinely retries

That last row matters: a stored failure would turn one bad request into a permanently poisoned key. Only successful responses are replayed.

Keys are scoped to your workspace and to the specific endpoint, so two operations can't collide on the same key. They expire after 24 hours - beyond that, a retry isn't a retry.

When to use it

Anywhere a duplicate would cost real money or produce a duplicate artifact:

• Export and Process - a duplicate is a second render
• Execute Tool - a duplicate is a second billable run
• Analyze, Translate, Voiceover

Some endpoints already collapse obvious duplicates on their own - a second export of a video whose export is still running returns the in-flight job. That only helps while the first job is running, and only on endpoints that do it. An idempotency key is the general answer.

GET and DELETE are naturally idempotent and ignore the header.