# ElevenLabs text to speech API quickstart with eleven_v4

Updated 2026-11-06

Call `POST /v1/text-to-speech/{voice_id}` with your ElevenLabs API key in the `xi-api-key` header and `model_id` set to `eleven_v4`. Save the returned bytes as audio. I'd use Dexter for the first integration test because its instructional delivery makes omissions easy to hear, then choose a voice for the finished product.

The examples below make a real, billable generation request when you run them with a valid key. They are alternatives, so you only need to run one. Voice Library API access requires an eligible paid ElevenLabs account. A voice ID copied from a web page does not grant access to the voice.

## What should I prepare before sending a request?

Store `ELEVENLABS_API_KEY` in your process environment or a local secret manager. Use a server process for production. Browser-delivered JavaScript cannot keep a key private, and a public repository is a poor place for it too.

Open [Dexter's voice page](https://voicefieldguide.com/elevenlabs-voices/dexter-customer-support-pro), audition the preview, then [add Dexter to My Voices](https://elevenlabs.io/app/voice-lab/share/2c79c9f85b01099b7eb10d1340f7f6d43d132db92fe0ede23cd10eef2678f8f1/Smxkoz0xiOoHo5WcSskf). The ID in these examples belongs to Dexter. My machine-readable [voice catalog](https://voicefieldguide.com/voices.json) contains the other exact IDs and share links.

Create `speech.json` with this content.

```json
{
  "text": "Your audio file is ready. Play it once before you connect the next step.",
  "model_id": "eleven_v4"
}
```

The output format is in the request URL. `mp3_44100_128` is a convenient first download for listening; your delivery platform may require a different format. Check its specifications before producing the whole batch.

## How do I save an MP3 with curl?

This example uses a POSIX shell. In PowerShell, use the Node or Python version below, or adapt the environment-variable syntax and invoke `curl.exe` explicitly.

```sh
curl --fail-with-body \
  --request POST \
  'https://api.elevenlabs.io/v1/text-to-speech/Smxkoz0xiOoHo5WcSskf?output_format=mp3_44100_128' \
  --header "xi-api-key: $ELEVENLABS_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @speech.json \
  --output speech.mp3
```

Inspect the exit status before treating `speech.mp3` as usable audio. A failed request can leave an error body in the output file. Open the file in a player only after the command succeeds; don't solve an unreadable file by renaming it to WAV.

## What does the Python version look like?

Python's standard library can make the same request without an SDK dependency. Save this as `speak.py`. It reads the environment variable and writes the file only after a successful response.

```python
import json
import os
import urllib.request
from pathlib import Path

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

key = os.environ["ELEVENLABS_API_KEY"]
voice = "Smxkoz0xiOoHo5WcSskf"
url = f"https://api.elevenlabs.io/v1/text-to-speech/{voice}?output_format=mp3_44100_128"
payload = {
    "text": "Your audio file is ready. Play it once before you connect the next step.",
    "model_id": "eleven_v4",
}
request = urllib.request.Request(
    url,
    data=json.dumps(payload).encode("utf-8"),
    headers={"xi-api-key": key, "Content-Type": "application/json"},
    method="POST",
)
opener = urllib.request.build_opener(NoRedirect())
with opener.open(request, timeout=120) as response:
    if not response.headers.get_content_type().startswith("audio/"):
        raise RuntimeError("Expected audio; no file was saved.")
    audio = response.read()
Path("speech.mp3").write_bytes(audio)
```

Let an unsuccessful request stop the process. Catch and classify errors when you turn this into a service, but keep an error response out of the audio folder. Never include the request headers in a public debug report.

## Can Node save the same response?

Use a current Node version with built-in `fetch`, and save this as `speak.mjs`. Its request matches the other examples.

```js
import { writeFile } from 'node:fs/promises';

const key = process.env.ELEVENLABS_API_KEY;
if (!key) throw new Error('Set ELEVENLABS_API_KEY locally.');
const voice = 'Smxkoz0xiOoHo5WcSskf';
const url = `https://api.elevenlabs.io/v1/text-to-speech/${voice}?output_format=mp3_44100_128`;
const response = await fetch(url, {
  method: 'POST',
  headers: { 'xi-api-key': key, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    text: 'Your audio file is ready. Play it once before you connect the next step.',
    model_id: 'eleven_v4'
  }),
  signal: AbortSignal.timeout(120000),
  redirect: 'error'
});
if (!response.ok) {
  throw new Error(`Speech request failed with HTTP ${response.status}`);
}
if (!(response.headers.get('content-type') || '').startsWith('audio/')) {
  throw new Error('Expected audio; no file was saved.');
}
await writeFile('speech.mp3', Buffer.from(await response.arrayBuffer()));
```

Check the error details privately in your server logs when a status alone isn't enough. Keep the key out of those logs. For a finished application, also restrict who can request speech and how much text each request accepts.

If the connection times out after submission, the outcome is unknown. Don't automatically resend the full request. Check your account's generation history and usage first so an uncertain response doesn't become several charged copies of the same take.

## What should I check when the first request fails?

Work through three layers. First, confirm authentication without printing the key. A missing environment variable is a local configuration problem. An account or permission error needs attention in the ElevenLabs workspace.

Next, check voice access. Use the exact ID, and confirm that the same account can select that voice. Free Voice Library access in the app and Voice Library access through the API are different questions.

Finally, inspect the request shape and model. The reference documents HTTP 422 for an invalid request. Check the returned explanation, the model available to your account, and the output format. Changing the voice at random makes this harder to diagnose. Change one field, then repeat a short test.

## How do I move from a connection test to useful audio?

Save the successful request recipe alongside the script, without the key. Add a versioned output name so a retry cannot overwrite the approved take. Listen to the first and last sentence before you connect publishing.

My catalog offers different tests. [Jett](https://voicefieldguide.com/elevenlabs-voices/jett-fast-paced-and-sharp-narrator) has a brisk delivery that exposes filler in a short explainer. [Heisenberg](https://voicefieldguide.com/elevenlabs-voices/heisenberg-polished-and-clear) gives longer explanations room. Their measured rates are close, about 180 and 175 words per minute in my clips, and neither number replaces timing the actual file. A successful API response is the beginning of audio review.

## Audition details

These picks compare my fifteen voices. I own them, and ElevenLabs may pay me when you use them.

### Dexter: First integration test

Plain instructional delivery makes missing words easy to notice. It isn't a showcase voice for a dramatic launch.

- Voice ID: `Smxkoz0xiOoHo5WcSskf`
- Voice page: https://voicefieldguide.com/elevenlabs-voices/dexter-customer-support-pro
- Add to My Voices: https://elevenlabs.io/app/voice-lab/share/2c79c9f85b01099b7eb10d1340f7f6d43d132db92fe0ede23cd10eef2678f8f1/Smxkoz0xiOoHo5WcSskf
- This guide's Eleven v4 clip: https://voicefieldguide.com/audio/v4/guide--elevenlabs-api-text-to-speech-quickstart--dexter-customer-support-pro.mp3

Sample line: Your audio file is ready. Before you connect the next step, play it once and check the beginning and the final word. Then save the approved file beside the script that produced it.

### Jett: Fast explainer output

Brisk, distinct speech for a short application demo. A cluttered test paragraph will expose every redundant phrase.

- Voice ID: `Hi6tnmUNNYzDCgW5eJyH`
- Voice page: https://voicefieldguide.com/elevenlabs-voices/jett-fast-paced-and-sharp-narrator
- Add to My Voices: https://elevenlabs.io/app/voice-lab/share/bd54bfca975b7a429fcdc927f8d90e31d6655f014dca365112e523a3abd45ee3/Hi6tnmUNNYzDCgW5eJyH
- This guide's Eleven v4 clip: https://voicefieldguide.com/audio/v4/guide--elevenlabs-api-text-to-speech-quickstart--jett-fast-paced-and-sharp-narrator.mp3

Sample line: The request has three moving parts. Choose the voice, send the words, and save the returned audio. Keep the key on your server so the page can ask for speech without exposing your account.

### Heisenberg: Longer narration test

A low, even read for evaluating paragraph continuity. Tight notification slots need a shorter script.

- Voice ID: `iEBOK9alpKauGRvBSsFi`
- Voice page: https://voicefieldguide.com/elevenlabs-voices/heisenberg-polished-and-clear
- Add to My Voices: https://elevenlabs.io/app/voice-lab/share/e0464333b21941625fcdd28b2ce050bc74911f6bd69cec0d6861a8bd9e24032b/iEBOK9alpKauGRvBSsFi
- This guide's Eleven v4 clip: https://voicefieldguide.com/audio/v4/guide--elevenlabs-api-text-to-speech-quickstart--heisenberg-polished-and-clear.mp3

Sample line: One short request proves the connection works. A full paragraph tells you more about the narrator. Listen for the difficult name, and check whether the final sentence still sounds like the first.

## Sources

- [ElevenLabs: API quickstart](https://elevenlabs.io/docs/eleven-api/guides/cookbooks/text-to-speech)
- [ElevenLabs: Create speech](https://elevenlabs.io/docs/api-reference/text-to-speech/convert)
- [ElevenLabs: Text to Speech product guide](https://elevenlabs.io/docs/eleven-creative/playground/text-to-speech)
- [ElevenLabs: Text to Speech overview](https://elevenlabs.io/docs/overview/capabilities/text-to-speech)

Source page: https://voicefieldguide.com/guides/elevenlabs-api-text-to-speech-quickstart
