Generate a unique key per logical operation (a UUID is ideal), send it on the first attempt, and reuse the SAME key on every retry of that operation. Keys are up to 128 characters and scoped to your account, so they cannot collide with another customer's.
Authentication
The key is bound to the request BODY as well as to your account. Reusing a key with different content is treated as a new request, not a replay — so a client that recycles keys carelessly gets charged rather than silently receiving the wrong result.
Create a key in Settings → API Keys. It is shown once, so copy it then. Every example below reads it from $SONICVOX_API_KEY.
Endpoints
Send Idempotency-Key on any credit-consuming POST that supports it — text-to-speech, dubbing, voice cloning, sound generation, speech-to-speech, speech-to-text, voice enhancement, image/video generation and agent creation. Every one of them charges the retry once, but the guarantee comes in two strengths. Text-to-speech, dubbing, sound generation, speech-to-speech and image/video generation hand back the original response verbatim with Idempotent-Replay: true, and nothing re-runs. Voice cloning and agent creation also return the original resource rather than creating a second one, but they do not set that header. Speech-to-text and voice enhancement dedupe only the CHARGE: the retry re-runs and returns a fresh transcript or enhanced file, billed once. Branch on the header only for the first group.
- Scope
- tts:synthesize
- Credits
- charged once, however many times you retry
KEY=$(uuidgen)
# First attempt — times out on your side, but may have succeeded
curl https://staging.sonicvox.ai/api/v1/text-to-speech \
-H "sv-api-key: $SONICVOX_API_KEY" \
-H "Idempotency-Key: $KEY" \
-H "content-type: application/json" \
-d '{"text":"Bill me once.","voice_id":"cmpwrfi46015zkww3t8nui4ye"}' \
--output hello.wav
# Safe retry — same key, same body. Returns the original, charges nothing.
curl https://staging.sonicvox.ai/api/v1/text-to-speech \
-H "sv-api-key: $SONICVOX_API_KEY" \
-H "Idempotency-Key: $KEY" \
-H "content-type: application/json" \
-d '{"text":"Bill me once.","voice_id":"cmpwrfi46015zkww3t8nui4ye"}' \
--output hello.wavHTTP/1.1 200 OK
content-type: audio/wav
idempotent-replay: true
x-credits-charged: 0
<the original audio>When it fails
Every error carries type, code, message, request_id and a doc_url. Branch on type for retry policy.
| idempotency_conflict | Only the image/video endpoint answers this. Its dedupe is anchored on the credit ledger, so once the original job is gone there is nothing to replay and re-running would be free — refusing the key is the only safe answer. Use a new key. |