API Docs

Authentication

Include your API key in the X-API-Key header.

X-API-Key: <your_api_key>

POST /api/tts

Generate speech from text. Returns raw audio bytes with the appropriate Content-Type header.

{
  "text": "Hello world",
  "voice": "Lauren",
  "format": "mp3",
  "speed": 1.0,
  "pitch": 1.0,
  "sampleRate": 24000
}

Parameters

Response

On success, returns 200 with raw audio bytes. The Content-Type header is audio/mpeg for MP3 or audio/wav for WAV. The X-Chars-Used header shows how many characters were consumed.

Using Cloned Voices

Studio plan users with cloned voices can use them via the API. Use the clone-{name} format, where {name} is the name you gave your clone (lowercase, hyphens for spaces).

// If your clone is named "Joshua":
{
  "text": "Hello from my cloned voice",
  "voice": "clone-joshua"
}

// If your clone is named "My Narrator":
{
  "text": "Welcome to the show",
  "voice": "clone-my-narrator"
}

You can also use the clone UUID returned when the voice was created: clone-{uuid}. Find your clone voice IDs in your account dashboard under Voice Cloning.

Audio Markup (Delivery Style)

Pro and Studio plans can use audio markup tags to control delivery style. Place one tag at the start of your text for best results. Tags are not counted toward your character limit. English only. This is an experimental feature.

// Emotion / delivery tags (place at start of text):
[happy]  [sad]  [angry]  [excited]  [whisper]
[calm]  [scared]  [friendly]  [professional]  [sarcastic]

// Example request:
{
  "text": "[excited] Check out this amazing new feature!",
  "voice": "Sarah"
}

Tip: For best results, use one tag per request. If you need different emotions for different parts, split them into separate API calls.

Sound Effects

Insert non-verbal sounds inline in your text. Sound effects are available on all plans and produce actual audio in the output.

// Available sound effect tags:
[laughing]  [cough]  [sigh]  [gasp]  [groan]
[yawn]  [sniff]  [clap]  [shush]  [hmm]
[ugh]  [cheer]

// Example:
{
  "text": "[laughing] That was hilarious! [sigh] Okay, back to work.",
  "voice": "Alex"
}

Word Timestamps / SRT Subtitles

Pro and Studio plans can request word-level timestamps. The response includes an X-Timestamps header with JSON-encoded timing data, and an SRT subtitle file can be downloaded alongside the audio from the web interface.

// To request timestamps, add the header:
X-Include-Timestamps: true

// The response will include:
// - Audio bytes in the body
// - X-Timestamps header with JSON array of word timings
// - X-Chars-Used header with character count

// Timestamp format:
[
  { "word": "Hello", "start": 0.0, "end": 0.42 },
  { "word": "world", "start": 0.45, "end": 0.87 }
]

Available Voices

Voices are organized by tier. Your plan determines which voices you can access via the API. Use the voice name as the voice parameter.

For the full voice list with language, gender, and accent metadata, call GET /api/voice-metadata (public, no auth required).

Rate Limits

If you hit a rate limit, the API returns 429 with a Retry-After header.

Voice Design via API

Voice Design (creating a custom voice from a text description) is currently available through the web interface only. Designed voices are automatically saved to your account and can then be used via the API using the clone-{name} voice ID format, just like cloned voices. Voice design shares the same 3-slot limit as voice cloning.

Error Codes