Docs•Developer

Text to Speech API

Turn text into audio over HTTP. Pick a voice, post your text, get a WAV back.

Open API reference

Synthesis is a single POST, and text is the only field the API requires. The one you will actually think about is voice_id — leave it out and you get the account default voice, which is rarely the one you meant — so this page starts by finding one.

Authentication

Send your account API key in the sv-api-key header (Authorization: Bearer works too). Synthesis needs the tts:synthesize scope; listing voices needs voices:read. API access requires a plan that includes it.

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

GET/api/v1/voicesFull reference →

List the voices this key may use — the shared library plus any you have cloned. Every voice_id returned here is one the synthesize endpoint accepts. Filter with category, gender, language or search; page with page and page_size (max 100).

Scope
voices:read
Credits
0 — browsing the library is free
curl https://staging.sonicvox.ai/api/v1/voices?language=en&page_size=1 \
  -H "sv-api-key: $SONICVOX_API_KEY"
Response
{
  "voices": [
    {
      "voice_id": "cmpwrfi46015zkww3t8nui4ye",
      "name": "Nash Wilder",
      "category": "Premium",
      "gender": "male",
      "age": "young_adult",
      "accent": "us_general",
      "language": "en",
      "preview_url": "https://staging.sonicvox.ai/api/voice-library/cmpwrfi.../preview",
      "description": "Warm, intimate broadcast tone at a slow pace."
    }
  ],
  "page": 1,
  "page_size": 1,
  "total": 4915,
  "has_more": true
}
POST/api/v1/text-to-speechFull reference →

Synthesize speech. Returns audio bytes directly — not JSON — so write the body to a file or stream it on. Optional: model (see GET /api/v1/models), language, speed, output_format.

Scope
tts:synthesize
Credits
⌈characters / 100⌉ × 100
curl https://staging.sonicvox.ai/api/v1/text-to-speech \
  -H "sv-api-key: $SONICVOX_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "text": "Hello from SonicVox.",
    "voice_id": "cmpwrfi46015zkww3t8nui4ye"
  }' \
  --output hello.wav
Response
HTTP/1.1 200 OK
content-type: audio/wav
x-credits-charged: 100
x-credits-remaining: 499900
x-request-id: 9f1c2e40-3b7a-4d18-9a55-1c0e2f7b6a31

<binary audio>
POST/api/v1/text-to-speech/estimateFull reference →

Price a string before you synthesize it. Free, charges nothing, and returns the live formula — useful for showing a cost in your own UI, or for refusing a job you cannot afford.

Scope
tts:synthesize
Credits
0
curl https://staging.sonicvox.ai/api/v1/text-to-speech/estimate \
  -H "sv-api-key: $SONICVOX_API_KEY" \
  -H "content-type: application/json" \
  -d '{"text": "Hello from SonicVox."}'
Response
{
  "characters": 20,
  "credits": 100,
  "affordable": true,
  "credits_remaining": 500000,
  "credits_remaining_after": 499900,
  "formula": {
    "base": 0,
    "per_chars": 100,
    "per_chars_cost": 100,
    "max_chars": 50000
  },
  "note": "Estimate only — no audio was synthesized and no credits were charged."
}
GET/api/v1/modelsFull reference →

The engines accepted in the model field, the languages each covers, and which request fields each one actually applies. Sending a field an engine ignores is not an error, so check supports before relying on it.

Scope
voices:read
Credits
0
curl https://staging.sonicvox.ai/api/v1/models \
  -H "sv-api-key: $SONICVOX_API_KEY"
Response
{
  "models": [
    {
      "model_id": "signature",
      "name": "Signature",
      "description": "Our flagship engine — the closest match to your selected voice.",
      "recommended": true,
      "languages": ["en", "zh", "ja", "ko", "de", "fr", "..."]
    }
  ]
}

When it fails

Every error carries type, code, message, request_id and a doc_url. Branch on type for retry policy.

voice_not_foundThe voice_id does not exist, or this key may not use it. List /api/v1/voices to see what it can.
insufficient_creditsThe balance will not cover the request. Nothing was charged; call /estimate first to avoid it.
validation_errorThe body failed schema validation — most often text over the 50,000-character cap.
tts_request_rejectedThe engine could not render this request (an unsupported model/language pairing). Retrying unchanged will not help.
rate_limit_exceededOver your plan's per-minute limit. Back off using the Retry-After header.
Every error code →

Next

Streaming

Start playback before synthesis finishes, for real-time experiences.

Full API reference

Every operation, parameter and response, with Try It.

Error catalog

Every code the API returns, and what to do about each.

Was this page helpful?
Text to Speech API | SonicVox Docs