API reference

Base URL /v1 · JSON in, audio out · $ per million input characters.

Quickstart

1. Create an account — you get free characters.
2. Create a key on the API keys page.
3. Make a request:

curl "{API}/audio/speech" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "{MODEL}", "voice": "alba", "input": "Hello! Your order ships today."}' \
  --output hello.mp3

Authentication

Send your key as a bearer token: Authorization: Bearer sk_live_.... X-API-Key is also accepted. Keys are secret; call the API from your server, never from a browser or mobile app.

sk_test_ keys return real audio for free, limited to 100 characters per request and 100 requests per day.

Using the OpenAI SDKs

The speech endpoint is wire-compatible with OpenAI's. Point the SDK's base URL at us; tts-1, tts-1-hd and gpt-4o-mini-tts are accepted as model names, and OpenAI voice names (alloy, nova, onyx, ...) map to similar stock voices. instructions is accepted and ignored (reported in X-Ignored-Parameters).

from openai import OpenAI

client = OpenAI(base_url="{API}", api_key="sk_live_...")
client.audio.speech.create(model="{MODEL}", voice="alba", input="Hi!").write_to_file("hi.mp3")

Create speech

POST/v1/audio/speech

Every response carries X-Request-Id, X-Billable-Characters and X-Voice-Id; non-streamed responses also include X-Audio-Duration-Ms.

Streaming

With "stream": true the first bytes arrive after the first sentence is synthesized, so playback can start long before the full clip is ready. Use pcm for the lowest latency in voice agents (play samples directly), or mp3 for broad player support.

curl -N "{API}/audio/speech" -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"input": "A long story...", "voice": "george", "response_format": "pcm", "stream": true}' \
  | ffplay -f s16le -ar 24000 -ac 1 -nodisp -autoexit -

Delivery options

Audio is never stored by default. With "delivery": "url" we keep the file for 24 hours and return:

{
  "object": "audio.speech",
  "id": "req_...",
  "voice": "alba",
  "format": "mp3",
  "duration_ms": 5120,
  "audio": { "url": "{API}/files/aud_...mp3?exp=...&sig=...", "expires_at": 1791763200, "bytes": 41210 },
  "usage": { "billable_characters": 84, "normalized_characters": 97, "cost_usd": 0.00042, "balance_usd": 12.34558 }
}

Anyone with the link can download the file until it expires, so treat links like secrets. Not available with zero data retention.

Text normalization

On by default. Numbers, currency ($1,299.99), dates (3/14), times (9:30pm), ordinals, temperatures, phone-style digit runs, acronyms, Roman numerals, markdown, URLs and emoji are converted into words the voice reads naturally. Preview the result for free:

POST/v1/normalize

{ "input": "Dr. Smith paid $42.50 on 3/14.", "pronunciations": [{ "word": "Smith", "respelling": "Smyth" }] }
-> { "normalized": "Doctor Smyth paid forty two dollars and fifty cents on March fourteenth.", "billable_characters": 30, "estimated_cost_usd": 0.00015 }

List voices

GET/v1/voices   GET/v1/voices/{id}

Returns your clones first, then the stock catalogue. Filter with ?type=clone or ?type=stock. Every stock voice has a preview_url you can play without authentication.

Voice cloning

POST/v1/voices   PATCH/v1/voices/{id}   DELETE/v1/voices/{id}

Accept the cloning terms once in the dashboard, then upload 3-60 seconds of clean speech (10-20 s is ideal). Accepted formats: wav, mp3, m4a/aac, ogg/opus, webm, flac, up to 12 MB. Up to 20 voices per account; creating them is free and they cost the same to use as stock voices.

curl "{API}/voices" -H "Authorization: Bearer $API_KEY" \
  -F name="Sam narrator" -F file=@sam.m4a -F consent=true
-> { "id": "cloned_3f9c...", "object": "voice", "name": "Sam narrator", "type": "clone", ... }

consent=true is your attestation, for this specific recording, that it is your voice or that you have the speaker's documented permission. Your recording is decoded in memory and discarded; we keep only an encrypted voice profile.

Balance & usage

GET/v1/balance

{ "object": "balance", "balance_usd": 12.34, "characters_remaining": 2468000,
  "auto_topup": { "enabled": true, "threshold_usd": 5, "amount_usd": 25, "pending": false, "last_failure": null } }

GET/v1/usage?start=2026-10-01&end=2026-10-31&group_by=day — group_by is day, key or none. Totals include requests, errors, characters, audio seconds and cost.

Warmup & cold starts

Most requests are served by a warm instance. A cold instance takes up to ~11 seconds to start. If a request must be fast (a live call is about to begin, say), warm up a few seconds beforehand. It is free and limited to once per minute per key.

POST/v1/warmup?wait=true

{ "object": "warmup", "status": "warm", "waited_ms": 8420, "instance_uptime_s": 9.1 }

Without wait it returns immediately with "warming" or "warm". Instances stay warm for several minutes after their last request. Under bursty load a new request may still land on a fresh instance.

Zero data retention

Turn on ZDR for your whole account (Profile) or per key. With ZDR we write no request logs and store none of your text. Character counts and charges are still recorded because they are your billing record, and /v1/usage keeps working. delivery: "url" is rejected with zdr_conflict.

Errors

Errors use OpenAI's shape and always include a stable code and the request_id:

{ "error": { "message": "This request costs $0.000420 but your balance is $0.000100. Add credits or enable auto top-up.",
  "type": "billing_error", "code": "insufficient_balance", "param": null, "request_id": "req_8fK2...", "doc_url": "..." } }

If a request fails on our side (5xx), you are not charged. 429 and 503 responses include Retry-After.

Retries & idempotency

Send an Idempotency-Key header (any unique string, e.g. a UUID) to make retries safe for 24 hours:

• Same key, same body, first attempt failed → the retry runs normally.
• Same key while the first is still running → 409 idempotency_in_progress.
• Same key after success → 409 idempotency_replay; you are not charged again. For delivery: "url" the original result is returned in error.previous_result.
• Same key with a different body → 409 idempotency_conflict.

Retry 429, 500, 502, 503 and 504 with exponential backoff. Don't retry other 4xx errors without changing the request.

Limits

Need more? Contact us.

OpenAPI spec

The machine-readable spec is at /v1/openapi.json. Import it into Postman, Insomnia or an SDK generator.