Developer docs

One endpoint to speak a phrase. Machine-readable files are provided for AI assistants.

Quick start

Create a key in the dashboard. The fast way to get speech is a stream: audio starts playing in about 44 milliseconds with the Phonon voices, before the sentence has finished generating. It takes two calls and works on every plan. A complete script you can run is in the streaming guide; speed, price and limits for voice agents are on the voice agent page.

# 1) ask for a stream: the answer has a stream_url, a one-use token and the request body to send
R=$(curl -s https://speakvora.com/api/v1/speak \
  -H "x-api-key: $SPEAKVORA_KEY" -H "Content-Type: application/json" \
  -d '{"text":"Your order is ready for pickup.","voice":"ph_zoey","lang":"en","stream":true}')

# 2) open the stream_url with the token and send the request body. The answer is raw 16-bit mono PCM at 24 kHz; play it as it arrives (needs jq and ffmpeg)
curl -N "$(jq -r .stream_url <<<"$R")" \
  -H "authorization: Bearer $(jq -r .token <<<"$R")" -H "Content-Type: application/json" \
  -d "$(jq -c .request.body <<<"$R")" \
  | ffplay -f s16le -ar 24000 -ac 1 -nodisp -

Measured on 21 November 2026 from one client in AWS us-east-1, one request at a time, with Speakvora streamed from our Mac mini over the public internet (the streaming call only; the request in step 1 is not in the figure), time until the first audible sound: Phonon voices (ph_) 44 ms median, Pocket voices (pk_) 90 ms. The request in step 1 is a separate call, so send it ahead of the moment you need the audio (a browser can do it on focus or hover, which is what our playground does). The token works once and expires after expires_in_seconds. Free accounts are spoken on our own machine, so a rare slow start or a short "server busy" answer is possible; paid accounts use faster servers and can also open a session with POST /v1/session. If the answer has "stream": false, the line was already stored, so play its url instead; either way you are only billed once.

Prefer a plain link to a finished clip? Send "stream": false:

curl https://speakvora.com/api/v1/speak \
  -H "x-api-key: $SPEAKVORA_KEY" -H "Content-Type: application/json" \
  -d '{"text":"Aim assist is off.","voice":"af_heart","lang":"en","stream":false}'

Speak

POST /v1/speak returns JSON with a url to the audio (m4a), or with "stream": true a one-use stream_url that starts playing in about 44 ms (see the quick start). Full schema in the OpenAPI spec.

Any text, live

Text that is not in the phrase library is voiced on demand with our catalog voices (English, Spanish, French, Portuguese, Hindi, Japanese and Mandarin; non-English results are marked native_review_pending) and returned as an mp3 url. With "stream": true (see the quick start) the first audio arrives in about 44 ms on the Phonon voices. As a finished clip link, a brand-new sentence takes about 0.4 to 1.5 seconds depending on the voice, and the same text afterwards returns in about 0.15 seconds. Streaming numbers measured on 7 November 2026; earlier numbers on 9 October 2026; method and numbers at /performance. Add "marks": true to a request to also get speech marks: exact start and end times for each sentence and a start and end for each word, for highlighting text as it plays. The field precision.words says how the word times were made: model_aligned (a speech-recognition aligner; about 15 ms from a second, independent aligner on average), aligned (measured from the audio: about 70 ms on average, eight in ten words within 100 ms) or estimated (spread by word length, the fallback). Measured on 21 November 2026 on real clips. Word times are not engine-exact like Amazon Polly's. Premium voices use the phrase library only.

Languages

Pass language as an ISO code or auto. Ambiguous text is rejected rather than guessed. Non-English clips carry native_review_pending until a native speaker approves them.

Drop-in for Amazon Polly, OpenAI and ElevenLabs

Plain text to speech works with your existing client: change the endpoint and use a Speakvora key. Polly: boto3.client("polly", endpoint_url="https://speakvora.com/api", aws_access_key_id=KEY, aws_secret_access_key="unused"). OpenAI: base_url="https://speakvora.com/api/v1". ElevenLabs: POST /api/v1/text-to-speech/{voice_id} with xi-api-key. Audio is mp3 or AAC. SSML, lexicons and other formats return an error. Speech marks work too: OutputFormat json with SpeechMarkTypes word and sentence returns Amazon-format JSON lines with byte offsets into your text (no viseme or SSML marks). Text up to 3,000 characters per call, as Polly; longer than 500 is spoken in pieces and joined. Accented letters and common symbols are folded so a café never fails. See Switch from Amazon Polly.

Free allowance

Every account gets 100,000 free characters every month (renewing on the 1st, UTC), with no card, to speak any catalog-voice text: the phrase library, packs and new sentences. New sentences in the catalog voices count against it too. The free 100,000 characters a month cover catalog voices only; lines in your own voice are $3 per 1M characters and need a card or credit on the account. (402 live_needs_card) Today a free account can still send a few trial lines in its own voice through POST /v1/speak while free characters remain; that is a convenience, not part of the plan, and preparing (POST /v1/prepare) or streaming (POST /v1/session) your own voice needs a paid account. The portal shows how much free allowance is left. When it is used up, requests return 402 free_allowance_used until you add a card. Library phrases count by their length like any other text.

Try it without an account

The home page and playground speak through POST /api/demo/speak: up to 140 characters, nine voices, and a small hourly limit per visitor. Use it to hear a voice. Use your key for real work.

MCP: use Speakvora from Claude, Cursor and other AI tools

Speakvora runs a Model Context Protocol server, so an AI assistant can speak text, list voices and search phrases without any code from you. Endpoint: https://speakvora.com/api/mcp (streamable HTTP). Send your key as x-api-key or Authorization: Bearer.

# Claude Code
claude mcp add --transport http speakvora https://speakvora.com/api/mcp --header "x-api-key: YOUR_KEY"

# Cursor and other clients that read an mcp.json file
{ "mcpServers": { "speakvora": { "url": "https://speakvora.com/api/mcp", "headers": { "x-api-key": "YOUR_KEY" } } } }

Tools: speak (text, voice, lang) returns an audio URL; list_voices; search_phrases (query, lang, limit). Client setup differs between tools, so check yours for how it stores HTTP servers and headers.

GET /api/v1/search?q=refund+order&lang=en&limit=10 returns phrases that contain your words, ranked, with the voices that have them. A library phrase plays instantly and costs nothing to generate. Search is word-based today; meaning-based search is planned.

Offline packs

GET /api/v1/packs lists downloadable zips. Each holds the audio and a manifest.json that maps sentence to file. Browse them on the packs page.

Your own voice

Customers can have a voice of their own, made in the portal in three ways: record a paragraph in the browser, upload a recording (10 to 60 seconds of one clear voice), or describe and tune a voice with meters (gender, age, pitch, pace, warmth, energy) and optional notes. A designed voice is first rendered as a reference sample, then saved like a recording, so it sounds the same every time. Designing a voice to imitate a named real person is refused. A recorded or uploaded voice needs a confirmation that it is yours or you have the speaker's permission.

A voice becomes ready once its recording passes a basic check (readable audio, at least 5 seconds). We keep that recording, encrypted and private to your account, for as long as the voice exists, because our own servers prepare the voice from it; it is not sent to any outside provider. Replacing the sample deletes the old recording, and deleting the voice deletes the recording too. Then about two dozen common support lines (greetings, thanks, clarification, waiting, closing) are prepared in the background, with progress shown, so those play instantly. Everything else is generated on first use and reused. Each account can keep 3 voices. You can preview, replace the sample, or delete a voice; deleting also removes every private recording made with it.

Language with a custom voiceStatus (measured with a cloned voice)
EnglishSupported
French, German, Spanish, Hindi, Chinese, JapaneseNot offered for your own voice. Use a catalog voice.

Custom voices are generated on our own servers with an open voice-cloning model (Pocket TTS, CC BY 4.0). They are not available to other accounts. Spoken laughter and other sound tags are not supported: a written "haha" is spoken as written. Personality does not add effects.

Everything is included at $3

There is one price: $3 per million characters, for catalog voices and for your own voice. Every feature is part of that price, with nothing to unlock: stored-clip playback, audio in the same response ("return":"audio" on POST /v1/speak), direct streaming for catalog voices from the first sentence (POST /v1/session, then stream from the address it returns; paid accounts), long-text handling and pronunciation rules for letters such as API and URL, and spoken laughter tags on English own voices. Delivery styles (happy, excited, sorry, calm, serious) were discontinued on 29 October 2026; a request with a style other than neutral now returns style_not_available. Tags such as [laugh] stay available on your own voice.

Caching and retention. A custom-voice sentence is stored only once it has been asked for twice; the first request is generated and returned without being kept. Stored recordings are private to your account and deleted after 75 days without use (each reuse restarts the 75 days).

Speech to text

Send audio, get text. Billed per second of audio at $0.0015 per minute; your first 60 minutes every month are free (renewing on the 1st, UTC).

POST /api/v1/listen   header x-api-key: <key>
{ "audio_base64": "<base64>", "format": "wav|mp3|m4a|ogg|flac|webm", "language": "en" }    # language is optional

200 { "text": "Your refund will arrive in three to five business days.", "seconds": 3, "language": "en" }

Audio must be 1 KB to 4.5 MB per request; send longer recordings in pieces. Not offered yet: speaker labels and word timestamps. Errors: 400 invalid_request, 402 free_allowance_used, 502 upstream_unavailable.

Live streaming (WebSocket)

For live transcription and streamed speech, open a WebSocket and send JSON text frames. The first message must authenticate.

wss://48f8pzwtee.execute-api.us-east-1.amazonaws.com/v1      (the address of this environment)

> {"type":"auth","key":"YOUR_KEY"}                                   < {"type":"ready"}

Live transcription
> {"type":"listen.start","language":"en","rate":16000,"interim":false}   # optional: endpoint_ms (700), vad_threshold (400)
> {"type":"audio","seq":0,"data":"<base64 PCM16 mono, 100-500 ms>"}      # seq counts up from 0
< {"type":"final","text":"...","seconds":4,"latency_ms":830}            # about 0.8 s after speech stops
> {"type":"listen.end"}                                               # flush

Streamed speech
> {"type":"speak","id":"1","text":"Your order has shipped. It arrives Friday.","voice":"af_heart","lang":"en"}
< {"type":"audio","index":0,"text":"Your order has shipped.","url":"https://...","source":"live"}   # one per sentence, in order
< {"type":"done","sentences":2,"characters":50}

End-of-speech detection uses loudness: raise vad_threshold in noisy rooms. With interim: true you also receive partial results about every 2 seconds of speech; these re-transcribe the buffer and are billed as audio seconds. Audio comes back as links to play, not as raw streamed audio.

Prices

Free allowance and billing. Every account gets 100,000 free characters every month (renewing on the 1st, UTC), plus 60 minutes of transcription every month (also renewing on the 1st, UTC). The free allowance covers any catalog-voice text: the phrase library, packs, and new sentences. The free 100,000 characters a month cover catalog voices only; lines in your own voice are $3 per 1M characters and need a card or credit on the account. Once you add a card, billing is pay as you go with no monthly minimum: you pay only for what you use, $3 per million catalog characters. Packs are one-time and have no minimum.

ProductPrice
Catalog voices$3 per 1M characters
Your own voice$3 per 1M characters
Speech to text$0.0015 per minute
Offline phrase packsAudio only US$14 to US$199; with the agent US$214 to US$399 (list price plus US$200, never more than US$399); paid once per pack and location

Free: 100,000 characters every month, plus 60 minutes of speech to text every month (both renew on the 1st, UTC; no card needed). Characters are counted on the text you send. Prices are list prices in US dollars.

Offline phrase packs

A pack is a zip of ready-made audio for one topic, language and voice, to ship inside your app so common lines play with no network and no per-play cost. Each pack holds manifest.json (every sentence with its audio file), phrases.csv, the audio (.m4a) and a licence. Packs are paid once per business location: audio only US$14 to US$199 by size and topic, or US$214 to US$399 with the local agent and dashboard, which includes the first 12 months of updates and support (then an optional flat US$99 a year). They are rebuilt as the library grows. What you download and install keeps working with no remote shutdown. An audio-only owner can upgrade by paying the difference. What the licence allows.

The pack agent (included in every audio + agent)

Every full pack zip also holds agent/, a small standard-library Python program, ready workflows for the pack's industry, and the lines those workflows need (including the notices your industry must say). It runs on your server next to your app, so there is no Speakvora per-use fee; your own phone, text and chat providers bill you for their services.

unzip pack.zip && cd pack
sh sv-agent init --pack .        # writes agent.json + workflows.json for this industry
sh sv-agent check                # what is connected, which lines are missing
sh sv-agent source add github    # ready mappings: github, gitlab, pagerduty, stripe, shopify, calendly, generic-pos
sh sv-agent run                  # DRY RUN: records what it would do; add --live to send
sh sv-agent slots --send         # ask Speakvora to write any line the pack lacks, for every pack of the industry

It connects to your own Android phone for texts (the free SMS Gateway app), Telegram, WhatsApp through Meta's Cloud API, your existing office phone system for calls (a SIP extension, tested with Asterisk), Twilio (texts, calls, WhatsApp) or any provider's web API for texts and calls, Slack and Microsoft Teams, Google and Microsoft 365 calendars, SMTP and IMAP email, and any system that sends a webhook or has a web API (GitHub, GitLab, PagerDuty, Stripe, Shopify, Calendly, your own app). Limits are yours (strict, standard or open); opt-outs, required notices and the kill switch are always on. See the Full Guide button on each Connect card, the step-by-step phone, Telegram, WhatsApp and office phone system guide, the guides inside agent/docs/ and what a pack does.

GET /api/v1/packs                                    public list: id, title, phrases, size, price_usd, sample_url, examples
GET /packs/{id}/sample.zip                           free sample, 25 phrases, no key
GET /api/v1/packs/{id}/download   x-api-key          200 {"url": "...zip (valid 5 minutes)"} once the pack is bought on the account, else 402 pack_not_purchased

Buy a pack on the packs page; it is paid by card and appears under Plan and billing in the portal.

Status

Live checks and daily uptime are on the status page. GET /api/status returns the same data.

SDKs

Official clients for JavaScript (Node 18+ and browsers) and Python (3.8+), with no dependencies. They cover speech, prepare, speech to text, voices, search, offline packs, live streaming and webhook checks, and return errors with a plain-language fix.

# JavaScript                                              # Python
npm install speakvora   pip install speakvora

const { Speakvora } = require("speakvora");               from speakvora import Speakvora
const sv = new Speakvora(process.env.SPEAKVORA_KEY);      sv = Speakvora(os.environ["SPEAKVORA_KEY"])
const clip = await sv.speak("Your order has shipped.");   clip = sv.speak("Your order has shipped.")
await sv.prepare(["Your table is ready."]);               sv.prepare(["Your table is ready."])
const { text } = await sv.listen(wavBuffer);              text = sv.listen(wav_bytes)["text"]

Single-file copies for pasting into a project: speakvora.js and speakvora.py. The npm and PyPI listings will follow the production launch.

Webhooks

Add a URL in the portal and we POST signed JSON events: test.ping, key.created, key.revoked. Each request carries x-speakvora-timestamp and x-speakvora-signature, the hex HMAC-SHA256 of timestamp + "." + raw body using your signing secret. Use Speakvora.verifyWebhook or verify_webhook from the SDKs, and reject anything older than five minutes.

Voices and languages

Use GET /api/v1/voices and GET /api/v1/languages for the live list. Voices that can speak any text live:

LanguagelangVoices
Englishenaf_heart, af_bella, af_nicole, af_sarah, af_sky, am_adam, am_michael
Spanishesef_dora, em_alex
Frenchfrff_siwis
Portugueseptpf_dora, pm_alex
Hindihihf_alpha, hm_omega
Japanesejajf_alpha, jm_kumo
Mandarin Chinesezhzf_001, zm_009

Other voices and languages play phrases from the library only, until live generation reaches them. The language you send must match the voice.

Limits

  • Text: 1 to 500 characters per request.
  • Rate: 15 requests per second per account on the free plan (100 on paid), counted over 10 seconds. Above that you get 429 rate_limited with retry_after_seconds.
  • Keys: up to 5 active keys per account. Webhooks: up to 3.
  • Numbers: English accepts digits. Every other language needs numbers written out in words.
  • Library first: library phrases are unlimited and instant. Brand-new catalog sentences are generated live and limited to 20 a minute per free account (120 paid), error live_rate_limited. Speed: library phrases and repeats are instant. POST /v1/speak returns a finished audio file, so you wait for the whole sentence (stored sentences come back almost instantly; a new one takes longer). For audio in tens of milliseconds use streaming, which is for paid accounts. A new custom-voice sentence takes about 2 seconds; a repeat is a cache hit (about 0.3 s).

Errors and fixes

Every error reply has error, message, fix and docs fields. The status codes are the standard ones.

StatuserrorMeaning and fix
401unauthorizedKey missing, wrong or revoked. Send it in x-api-key. Check for spaces or quotes around it.
400invalid_jsonBody is not valid JSON. Send content-type: application/json and check commas and quotes.
400text_required_max_500_charsText empty or over 500 characters. Split it.
400voice_requiredAdd a voice id.
422custom_voice_errorThe custom voice could not be used. Read detail: styles are English only, the voice must be ready, the id must be yours.
422style_not_availableDelivery styles were discontinued on 29 October 2026. Send the request without a style (or with "neutral").
400invalid_requestSpeech-to-text or streaming request malformed. Read detail.
404voice_not_liveThat voice cannot speak new text. Pick one from the table above.
422language_not_supported_for_voicelang does not match the voice. The reply says which language the voice speaks.
422language_not_supportedLanguage not available yet. The reply lists the ones that are.
422invalid_textText rejected. Read reasons_explained: usually digits in a non-English language, a placeholder like (name), or a safety claim.
404voice_not_available_for_textThe phrase exists, but not in that voice. The reply lists the voices that have it.
404not_in_libraryNot a library phrase and live generation could not run for it.
422generation_failed_qualityThe audio was too short or broken, so it was not served. Add a full stop or reword.
429(Too Many Requests)Over the rate limit. Wait a moment and retry with a short backoff.
502/503/504(gateway timeout)A new sentence took longer than the time limit, usually a very long sentence or a busy moment. Retry the same request.

Troubleshooting checklist

  1. Run the quick check in the portal under Troubleshoot. It tests that the API is reachable and that your key works.
  2. Try the exact curl command from the portal in a terminal. If curl works but your app does not, the problem is in your app: the header name, an environment variable that is empty, or a proxy.
  3. Check the header. It is x-api-key, with no Bearer unless you use Authorization.
  4. Match language and voice. A Chinese voice with lang: "en" fails.
  5. Calling from a browser? Do not ship your key in public web code. Call Speakvora from your server, then give the audio link to the browser.
  6. Slow on the first call? New sentences are generated live. Repeats are instant. Retry once before assuming something is broken.
  7. Audio will not play? The reply is a link. Open the url directly. Browsers need a click or tap before they will autoplay audio.
  8. Still stuck? Paste the request and response in the portal's Troubleshoot tab. It checks your account and request and explains the cause.

FAQ

Why was a key rejected right after I created it? Check for a trailing space or newline when you pasted it. Keys start with sv_.

Can I send personal data? No. Use placeholders on your side and speak the personal part another way.

Are non-English voices final? They are labelled native_review_pending until a native speaker approves the language.

Privacy and retention

Two different things happen to audio, and the rules differ:

Catalog voices (/v1/speak, phrase library)Custom voices
Who can fetch the audioAnyone with the link. Links are long and unguessable but public, and the same text in the same voice returns the same file.Only your account. Links are signed and last 5 minutes.
How long it is keptLibrary clips: served with a one-year cache lifetime. Live-generated clips: kept for reuse.75 days after the last time it was used; each reuse restarts the 75 days. Expired audio is refused and deleted.
Personal data in the textDo not send it. Send generic sentences and speak the personal part another way.Allowed if you have the right to use it. It stays private to your account.

Other things to know: Your text is processed by our AI provider (DeepInfra) when you use its language or transcription models; it lists zero retention on the models we use. A recording you submit to make a voice is not sent to DeepInfra or any other outside provider: we keep it, encrypted and private to your account, for as long as the voice exists so our own servers can speak in it, and we delete it when you delete the voice or replace the sample. Styled voices were discontinued on 29 October 2026, so we no longer make or keep a voice fingerprint. You can delete one voice, one recording, or all private audio from the portal. Private audio has a storage quota (500 MB by default). Text with unresolved placeholders such as (name) or {name} is rejected, so build the real sentence on your side. Whether you may record, clone or process someone's voice or personal data is your responsibility under the laws that apply to you; we are not a law firm and this is not legal advice.

Safety note: Speakvora rejects text that is not a real sentence and never generates affirmative safety claims. Do not use synthetic speech to imply a person is on the line.

For AI assistants

Point your coding assistant at /docs/llms.txt and the OpenAPI spec; they contain everything needed to wire up the API.