From first request to production
Getting a first audio file out of the ElevenLabs API takes about five minutes. Getting an integration that survives real traffic takes rather longer, and most of the tutorials online stop somewhere in between.
This guide covers the whole path. We will start with authentication and a single request, then work through the decisions that actually determine whether your integration holds up: which transfer mode to use, how to pick a model and output format, how to bound concurrency, how to cache so you never pay twice for the same audio, and how to retry when things fail.
Code samples are in Python and Node, since those are the two officially supported SDKs. A raw HTTP option exists if you are working in another language.
Step 1: Get your API key and install the SDK
Start in the ElevenLabs dashboard by generating an API key. Don't hardcode this anywhere — store it as a managed secret, whether that's an environment variable, a .env file, or whatever your deployment platform uses to handle configuration. This key is the one credential that gates every request you'll make, so treat it with the same care you'd give a database password.
From there, install the official SDK for your language. ElevenLabs maintains official SDKs for both Python and Node.js, so you can pull in the library through your usual package manager and get straight to authenticating your client. If you're working in a language without an official SDK, the raw HTTP API is fully documented and works just as well — you'll just be constructing requests by hand instead of through SDK methods.
Once your key is stored and the SDK is installed, you're ready to authenticate your client and make your first request.
Step 2: Choose a voice
Every text-to-speech request needs a voice_id. You retrieve the available voices from the GET /v1/voices endpoint, which returns the library along with metadata for each voice — accent, age, gender and intended use case, plus whether it is premade, cloned or generated.
The library is large, well past ten thousand voices, so filtering on that metadata matters more than browsing. Two practical notes:
- Audition the voice inside a realistic sample of your actual script, not a generic sentence. A voice that sounds warm reading marketing copy can sound wrong reading an account balance.
- Once you settle on a voice, store the voice_id in your environment config and reference it everywhere. It does not change, and hardcoding it in twelve places will hurt later.
Step 3: Make your first request
There is one main text-to-speech endpoint, POST /v1/text-to-speech/{voice_id}, and you can access it three different ways. Start with the simplest: batch conversion. You send one request with your text and receive one complete audio response.
Batch is the lowest-complexity option, and it is the right choice whenever the text is known in advance and nobody is waiting in real time: generating narration, pre-rendering IVR prompts, producing audio for a content library. Its drawback is time-to-first-audio, because the entire clip is synthesised before any bytes come back.
The generation parameters worth understanding
- stability (0–1). Controls consistency. Lower values introduce more emotional variation and expressiveness; higher values produce steadier, more predictable delivery. For transactional content, lean higher. For storytelling, lower.
- similarity_boost (0–1). Governs how closely the output tracks the original voice characteristics.
- style (0–1). Amplifies stylistic traits. Use it sparingly — it is easy to overshoot into something that sounds mannered.
Resist the urge to tune all three at once. Change one, listen, then change the next.
Step 4: Upgrade to streaming
The moment a human being is waiting for the audio, batch is the wrong mode. Switch to HTTP streaming.
The change is small: you append /stream to the path and call the streaming method instead of the convert method. The request is otherwise nearly identical. What changes is that audio returns as a chunked response, so playback can begin before generation finishes. Perceived latency drops dramatically even though total generation time is similar.
When to use WebSockets instead
For persistent, real-time applications — a live agent, an interactive assistant, anything where text arrives incrementally rather than all at once — use the WebSocket stream-input mode. It keeps a connection open and accepts text as it becomes available, which is exactly what you need when the text is itself being generated token by token by a language model.
Picking the right model
Model choice is a straight latency-versus-expressiveness trade:
- Flash v2.5 targets around 75ms latency and is the right pick for real-time, conversational use.
- Multilingual v2 favours quality and nuance over speed, and suits pre-rendered or non-interactive content.
On output formats, MP3 is the default. PCM and μ-law are also available — μ-law matters specifically if you are feeding audio into a telephony system, which generally expects it.
Step 5: Make it survive production
This is the section most tutorials skip, and it is the difference between a demo and a service.
Retries and backoff
Handle the status codes deliberately. A 429 means you have hit a rate limit; 5xx means something failed on the server side. Both should be retried using exponential backoff with full jitter — the jitter matters, because synchronised retries across your fleet will simply recreate the spike that caused the problem.
A 401 means authentication failed and retrying will not help; check the key. A 400 means the request itself is malformed and also not worth retrying. Log both loudly.
Caching
Text-to-speech billing runs on credits, and for TTS the arithmetic is simple: one character of input text costs one credit. That makes repeated generation of identical text pure waste.
Cache aggressively on a hash of the text plus every generation parameter that affects the output — voice, model, stability, similarity and format. In most real applications a surprising share of requests are repeats: greetings, confirmations, error messages, standard prompts. Caching those is usually the single largest cost reduction available to you.
One caveat: caching removes the natural variation the model would otherwise produce across repeated generations of the same phrase. For system prompts that is fine, and arguably better. For anything meant to sound spontaneous, it is not.
Concurrency bounding
Your plan carries a concurrency limit, and exceeding it produces failures rather than a queue. Put a bounded worker pool or semaphore in front of your calls so your own application enforces the ceiling gracefully instead of discovering it under load.
Step 6: The production security checklist
One rule dominates all others here, and it is repeated in every serious guide for good reason: never embed your API key client-side.
This applies with particular force to mobile applications, where the key ends up inside a shipped binary that anyone can extract. The correct architecture is straightforward — your client calls your own authenticated backend endpoint, and your backend calls ElevenLabs server-side. The key never leaves your infrastructure.
The rest of the checklist:
- Authenticate and rate-limit your own proxy endpoint, or you have simply moved the abuse target.
- Keep keys in a secret manager, not in source control, and rotate them on a schedule.
- Log usage per user or per tenant so a runaway client is visible before it is expensive.
- Set alerts on credit consumption. Usage-based billing punishes surprises.
- Handle failures gracefully in the UI — a silent absence of audio is a confusing failure mode.
A note on credits and billing
Credits are the universal unit across ElevenLabs products. For text-to-speech, one input character equals one credit; other operations bill per second of audio processed. Credits reset monthly and unused credits roll over for up to two months.
This matters architecturally more than it might seem. Because you are billed on input characters rather than output duration, your text preprocessing has a direct cost consequence. Trimming redundant text, avoiding regeneration and caching well are cost controls, not just performance ones.
Where this goes next
What we have built here is a text-to-speech integration: you supply text, you get audio. That is the correct foundation for narration, IVR prompts, notifications and content production.
It is not the same thing as a conversational voice agent, which additionally needs speech-to-text on the inbound side, a language model to decide what to say, and orchestration to hold the whole loop together in real time. ElevenLabs offers a dedicated product for that, and building one is the subject of the next post in this series.
If you are choosing between wiring these APIs together yourself and using the managed agents platform, read that post before you commit to an architecture.