Core concepts

Idempotency

Retry job-creating requests safely, without creating or paying for duplicates.

Networks fail. If a request times out you cannot know whether Voiser received it. Add an Idempotency-Key header to requests that create jobs, and you can retry them as often as you need: the first request creates the job, and every retry with the same key returns that same job instead of starting (and charging for) a new one.

curl -X POST https://api.34.181.188.80.sslip.io/v2/text-to-speech \
  -H "Authorization: Bearer $VOISER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-intro-audio" \
  -d '{ "text": "Thanks for your order!", "voice_id": "voice_8f2Kq1LmZx3T" }'

Choosing a key

  • 8 to 100 characters from A-Z, a-z, 0-9 and _ . : -.
  • Use one key per logical operation. A random UUID generated when you first decide to do the work is ideal; an id from your own system (such as order-1042-intro-audio) works well too.
  • Reuse the key only to retry the same request. Sending a different body with a key you already used fails with 409 job_idempotency_conflict.

Behaviour

SituationResult
First request with a keyThe job is created; 202 with the new job.
Retry with the same key and the same bodyNo new job; the original job is returned in its current state.
Same key, different body409 with job_idempotency_conflict.
No keyEvery request creates a new job.

Read requests (GET) are always safe to retry and do not need a key.

Endpoints that accept a key