Idempotency key

Why use it

Retries after a timeout or ambiguous 5xx are common. Without an idempotency key, the server may treat each retry as a new request — duplicate tasks, extra credits, or duplicate webhooks. X-Idempotency-Key marks one logical submission. Under your API Key, the same path + key is accepted only once within the TTL (default 24 hours). Retry the same intent with the same key; start a new job with a new key.

Idempotency prevents duplicate submissions, not two different jobs.

What to send

Add the header on every POST request to the Open API (/openapi/v1/**):

X-Idempotency-Key: <unique-string>

Rules:

Non-empty after trim, max length 64
Generate the key before the first attempt and keep it for safe retries
Do not reuse a key for a different payload — you will get 409 Conflict

If the key was already used

HTTP 409 Conflict
Header Retry-After: 2
Body: code: 409, message contains Idempotency key already used

Safe retry vs new work

Situation	Key
First submit	New unique key
Retry after timeout (same intent)	Same key
New task or new write	New key

Example

export IDEM_KEY="job-$(date +%s)-$RANDOM"

curl -X POST "https://api.vmeg.ai/openapi/v1/task/tts/create" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Idempotency-Key: $IDEM_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json

If the result is unclear, retry with the same key. Do not generate a new key on every retry, or you risk duplicate writes.

Tools reference Request ID

Get started

Authentication

MCP

Reliable requests

Webhooks

Assets

Products

Limits

Why use it

What to send

If the key was already used

Safe retry vs new work

Example

​Why use it

​What to send

​If the key was already used

​Safe retry vs new work

​Example

Why use it

What to send

If the key was already used

Safe retry vs new work

Example