Text To Speech

ElevenLabs Text-to-Speech

Generate natural speech from text - supports 70+ languages, multiple models for quality vs latency tradeoffs.

Setup: See Installation Guide. For JavaScript, use @elevenlabs/* packages only.

Project defaults — load .env FIRST

Before any TTS call in this repo, load .env and use the project defaults defined there. Pull voice_id, model_id, and all voice_settings from environment variables — do not hardcode them, even in throwaway scripts.

Full snippets (Python / JS / cURL) and the speed-selection rule live in references/voice-settings.md. The Quick Start below shows hardcoded values for illustration only — every real call must read from env.

Quick Start

Python

from elevenlabs import ElevenLabs

client = ElevenLabs()

audio = client.text_to_speech.convert(
    text="Hello, welcome to ElevenLabs!",
    voice_id="JBFqnCBsd6RMkjVDRZzb",  # George
    model_id="eleven_multilingual_v2"
)

with open("output.mp3", "wb") as f:
    for chunk in audio:
        f.write(chunk)

JavaScript

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import { createWriteStream } from "fs";

const client = new ElevenLabsClient();
const audio = await client.textToSpeech.convert("JBFqnCBsd6RMkjVDRZzb", {
  text: "Hello, welcome to ElevenLabs!",
  modelId: "eleven_multilingual_v2",
});
audio.pipe(createWriteStream("output.mp3"));

cURL

curl -X POST "https://api.elevenlabs.io/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
  -d '{"text": "Hello!", "model_id": "eleven_multilingual_v2"}' --output output.mp3

Models

Voice IDs

Use pre-made voices or create custom voices in the dashboard.

Popular voices:

• JBFqnCBsd6RMkjVDRZzb - George (male, narrative)
• EXAVITQu4vr4xnSDxMaL - Sarah (female, soft)
• onwK4e9ZLuTAKqWW03F9 - Daniel (male, authoritative)
• XB0fDUnXU5powFXDhCwa - Charlotte (female, conversational)

voices = client.voices.get_all()
for voice in voices.voices:
    print(f"{voice.voice_id}: {voice.name}")

Voice Settings

Fine-tune how the voice sounds:

• Stability: How consistent the voice stays. Lower values = more emotional range and variation, but can sound unstable. Higher = steady, predictable delivery.
• Similarity boost: How closely to match the original voice sample. Higher values sound more like the original but may amplify audio artifacts.
• Style: Exaggerates the voice's unique style characteristics (only works with v2+ models).
• Speaker boost: Post-processing that enhances clarity and voice similarity.

from elevenlabs import VoiceSettings

audio = client.text_to_speech.convert(
    text="Customize my voice settings.",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    voice_settings=VoiceSettings(
        stability=0.5,
        similarity_boost=0.75,
        style=0.5,
        speed=1.0,             # 0.25 to 4.0 (default 1.0)
        use_speaker_boost=True
    )
)

Language Enforcement

Force specific language for pronunciation:

audio = client.text_to_speech.convert(
    text="Bonjour, comment allez-vous?",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    model_id="eleven_multilingual_v2",
    language_code="fr"  # ISO 639-1 code
)

Text Normalization

Controls how numbers, dates, and abbreviations are converted to spoken words. For example, "01/15/2026" becomes "January fifteenth, twenty twenty-six":

• "auto" (default): Model decides based on context
• "on": Always normalize (use when you want natural speech)
• "off": Speak literally (use when you want "zero one slash one five...")

audio = client.text_to_speech.convert(
    text="Call 1-800-555-0123 on 01/15/2026",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    apply_text_normalization="on"
)

Request Stitching

When generating long audio in multiple requests, the audio can have pops, unnatural pauses, or tone shifts at the boundaries. Request stitching solves this by letting each request know what comes before/after it:

# First request
audio1 = client.text_to_speech.convert(
    text="This is the first part.",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    next_text="And this continues the story."
)

# Second request using previous context
audio2 = client.text_to_speech.convert(
    text="And this continues the story.",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    previous_text="This is the first part."
)

Output Formats

Word/character timestamps — default for any sync use case

If downstream code needs to know when each word is spoken (subtitles, captions, marker highlights, animation triggers, scene transitions tied to narration), use convert_with_timestamps — never generate audio first and run Whisper on it. ElevenLabs returns character-level alignment alongside the audio in a single call, so timestamps come from the same model that produced the audio (sample-accurate, no transcription drift, no extra dependency).

Python — audio + word-level transcript

import base64, json, os, wave
from dotenv import load_dotenv
from elevenlabs import ElevenLabs, VoiceSettings

load_dotenv()
client = ElevenLabs(api_key=os.environ["ELEVENLABS_API_KEY"])

resp = client.text_to_speech.convert_with_timestamps(
    voice_id=os.environ["ELEVENLABS_VOICE_ID"],
    text="Claude just got fifteen new connectors. AllTrails. Spotify.",
    model_id=os.environ["ELEVENLABS_MODEL_ID"],
    output_format="pcm_44100",
    voice_settings=VoiceSettings(
        stability=float(os.environ["ELEVENLABS_STABILITY"]),
        similarity_boost=float(os.environ["ELEVENLABS_SIMILARITY_BOOST"]),
        style=float(os.environ["ELEVENLABS_STYLE"]),
        speed=float(os.environ["ELEVENLABS_SPEED"]),
        use_speaker_boost=True,
    ),
)

# 1. Audio: base64-decode and wrap raw PCM in a WAV header.
pcm = base64.b64decode(resp.audio_base_64)
with wave.open("narration.wav", "wb") as f:
    f.setnchannels(1); f.setsampwidth(2); f.setframerate(44100)
    f.writeframes(pcm)

# 2. Word-level transcript: collapse character alignment into whitespace-delimited tokens.
align = resp.normalized_alignment or resp.alignment  # normalized strips punctuation oddities
words, current = [], None
for ch, t0, t1 in zip(align.characters, align.character_start_times_seconds, align.character_end_times_seconds):
    if ch.isspace():
        if current: words.append(current); current = None
    else:
        if current is None: current = {"word": ch, "start": t0, "end": t1}
        else: current["word"] += ch; current["end"] = t1
if current: words.append(current)

with open("transcript.json", "w", encoding="utf-8") as f:
    json.dump(words, f, ensure_ascii=False, indent=2)

Response shape

AudioWithTimestampsResponse has:

• audio_base_64 — the audio (base64-encoded; decode before writing to disk)
• alignment — character-level: characters[], character_start_times_seconds[], character_end_times_seconds[]
• normalized_alignment — same shape, but for the normalized text (numbers expanded, abbreviations spelled out, etc.). Prefer this when grouping into words — it matches what the model actually spoke.

When to skip timestamps

Plain convert (no timestamps) is fine when the audio is the only output and nothing downstream needs sync — e.g. one-off voiceovers, podcasts where word-by-word timing doesn't matter. For anything visual that has to land on a syllable, use convert_with_timestamps.

Streaming

For real-time applications, use the stream method (returns audio chunks as they're generated):

audio_stream = client.text_to_speech.stream(
    text="This text will be streamed as audio.",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    model_id="eleven_flash_v2_5"  # Ultra-low latency
)

for chunk in audio_stream:
    play_audio(chunk)

See references/streaming.md for WebSocket streaming.

Error Handling

try:
    audio = client.text_to_speech.convert(
        text="Generate speech",
        voice_id="invalid-voice-id"
    )
except Exception as e:
    print(f"API error: {e}")

Common errors:

• 401: Invalid API key
• 422: Invalid parameters (check voice_id, model_id)
• 429: Rate limit exceeded

Tracking Costs

Monitor character usage via response headers (x-character-count, request-id):

response = client.text_to_speech.convert.with_raw_response(
    text="Hello!", voice_id="JBFqnCBsd6RMkjVDRZzb", model_id="eleven_multilingual_v2"
)
audio = response.parse()
print(f"Characters used: {response.headers.get('x-character-count')}")

References

• Installation Guide
• Streaming Audio
• Voice Settings

Installation

JavaScript / TypeScript

npm install @elevenlabs/elevenlabs-js

Important: Always use @elevenlabs/elevenlabs-js. The old elevenlabs npm package (v1.x) is deprecated and should not be used.

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

// Option 1: Environment variable (recommended)
// Set ELEVENLABS_API_KEY in your environment
const client = new ElevenLabsClient();

// Option 2: Pass directly
const client = new ElevenLabsClient({ apiKey: "your-api-key" });

Migrating from deprecated packages

If you have old packages installed, remove them:

# Remove deprecated packages
npm uninstall elevenlabs

# Install the current packages
npm install @elevenlabs/elevenlabs-js

Import changes:

// OLD (deprecated)
import { ElevenLabsClient } from "elevenlabs";

// NEW (current)
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

Python

pip install elevenlabs

from elevenlabs import ElevenLabs

# Option 1: Environment variable (recommended)
# Set ELEVENLABS_API_KEY in your environment
client = ElevenLabs()

# Option 2: Pass directly
client = ElevenLabs(api_key="your-api-key")

cURL / REST API

Set your API key as an environment variable:

export ELEVENLABS_API_KEY="your-api-key"

Include in requests via the xi-api-key header:

curl -X POST "https://api.elevenlabs.io/v1/text-to-speech/{voice_id}" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world", "model_id": "eleven_multilingual_v2"}'

Getting an API Key

1. Sign up at elevenlabs.io 2. Go to API Keys 3. Click Create API Key 4. Copy and store securely

Or use the setup-api-key skill for guided setup.

Environment Variables

Streaming Audio

Stream audio chunks as they're generated for lower latency.

Model Selection for Streaming

Python Streaming

from elevenlabs import ElevenLabs

client = ElevenLabs()

audio_stream = client.text_to_speech.stream(
    text="This is a streaming example with ultra-low latency.",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    model_id="eleven_flash_v2_5"
)

with open("output.mp3", "wb") as f:
    for chunk in audio_stream:
        f.write(chunk)

Real-Time Playback

import subprocess

def play_stream(audio_stream):
    process = subprocess.Popen(
        ["ffplay", "-nodisp", "-autoexit", "-"],
        stdin=subprocess.PIPE
    )
    for chunk in audio_stream:
        process.stdin.write(chunk)
    process.stdin.close()
    process.wait()

audio_stream = client.text_to_speech.stream(
    text="Playing this audio in real-time.",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    model_id="eleven_flash_v2_5"
)
play_stream(audio_stream)

JavaScript Streaming

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import { createWriteStream } from "fs";

const client = new ElevenLabsClient();

const audioStream = await client.textToSpeech.convert("JBFqnCBsd6RMkjVDRZzb", {
  text: "Streaming audio in JavaScript.",
  modelId: "eleven_flash_v2_5",
});

// Write to file
const writeStream = createWriteStream("output.mp3");
audioStream.pipe(writeStream);

// Or process chunks
for await (const chunk of audioStream) {
  console.log(`Received ${chunk.length} bytes`);
}

WebSocket Streaming

For text-streaming input where you send text chunks as they arrive (e.g., from an LLM).

Connection

wss://api.elevenlabs.io/v1/text-to-speech/{voiceId}/stream-input?model_id={modelId}

Note: WebSockets are unavailable for the eleven_v3 model. Use eleven_flash_v2_5 for lowest latency.

Message Flow

1. Initialize - Send voice settings and configuration 2. Send text - Stream text chunks as they arrive 3. Close - Send empty string to signal completion 4. Receive - Process audio chunks as they're generated

Python WebSocket

import asyncio
import json
import base64
import os
import websockets
from dotenv import load_dotenv

load_dotenv()

ELEVENLABS_API_KEY = os.getenv("ELEVENLABS_API_KEY")

async def text_to_speech_ws_streaming(voice_id: str, model_id: str):
    uri = f"wss://api.elevenlabs.io/v1/text-to-speech/{voice_id}/stream-input?model_id={model_id}"

    async with websockets.connect(uri) as websocket:
        # Initialize connection
        await websocket.send(json.dumps({
            "text": " ",
            "voice_settings": {
                "stability": 0.5,
                "similarity_boost": 0.8
            },
            "generation_config": {
                "chunk_length_schedule": [120, 160, 250, 290]
            },
            "xi_api_key": ELEVENLABS_API_KEY
        }))

        # Send text chunks
        await websocket.send(json.dumps({"text": "Hello, "}))
        await websocket.send(json.dumps({"text": "this is streaming text "}))
        await websocket.send(json.dumps({"text": "from a WebSocket connection."}))

        # Close stream (empty text signals completion)
        await websocket.send(json.dumps({"text": ""}))

        # Receive and process audio chunks
        audio_chunks = []
        while True:
            message = await websocket.recv()
            data = json.loads(message)
            if data.get("audio"):
                audio_chunks.append(base64.b64decode(data["audio"]))
            elif data.get("isFinal"):
                break

        return b"".join(audio_chunks)

async def main():
    audio = await text_to_speech_ws_streaming(
        voice_id="JBFqnCBsd6RMkjVDRZzb",
        model_id="eleven_flash_v2_5"
    )
    with open("output.mp3", "wb") as f:
        f.write(audio)

if __name__ == "__main__":
    asyncio.run(main())

JavaScript WebSocket

import "dotenv/config";
import WebSocket from "ws";
import * as fs from "node:fs";

const ELEVENLABS_API_KEY = process.env.ELEVENLABS_API_KEY;

async function textToSpeechWsStreaming(voiceId, modelId) {
  const uri = `wss://api.elevenlabs.io/v1/text-to-speech/${voiceId}/stream-input?model_id=${modelId}`;

  return new Promise((resolve, reject) => {
    const websocket = new WebSocket(uri, {
      headers: { "xi-api-key": ELEVENLABS_API_KEY },
    });

    const audioChunks = [];

    websocket.on("open", () => {
      // Initialize connection
      websocket.send(
        JSON.stringify({
          text: " ",
          voice_settings: {
            stability: 0.5,
            similarity_boost: 0.8,
          },
          generation_config: {
            chunk_length_schedule: [120, 160, 250, 290],
          },
        })
      );

      // Send text chunks
      websocket.send(JSON.stringify({ text: "Hello, " }));
      websocket.send(JSON.stringify({ text: "this is streaming text " }));
      websocket.send(JSON.stringify({ text: "from a WebSocket connection." }));

      // Close stream
      websocket.send(JSON.stringify({ text: "" }));
    });

    websocket.on("message", (event) => {
      const data = JSON.parse(event.toString());
      if (data.audio) {
        audioChunks.push(Buffer.from(data.audio, "base64"));
      } else if (data.isFinal) {
        websocket.close();
        resolve(Buffer.concat(audioChunks));
      }
    });

    websocket.on("error", reject);
  });
}

const audio = await textToSpeechWsStreaming(
  "JBFqnCBsd6RMkjVDRZzb",
  "eleven_flash_v2_5"
);
fs.writeFileSync("output.mp3", audio);

Input Messages

Initialization (first message):

{
  "text": " ",
  "voice_settings": {
    "stability": 0.5,
    "similarity_boost": 0.8,
    "use_speaker_boost": false
  },
  "generation_config": {
    "chunk_length_schedule": [120, 160, 250, 290]
  },
  "xi_api_key": "your_api_key"
}

Text chunks:

{ "text": "Your text content here" }

Force flush (generate audio immediately):

{ "text": "End of sentence.", "flush": true }

Close connection:

{ "text": "" }

Output Messages

Audio chunk:

{
  "audio": "base64_encoded_audio_data"
}

Stream complete:

{
  "isFinal": true
}

Key Parameters

Important Notes

• Inactivity timeout: Connection closes after 20 seconds without activity. Send a space " " to keep alive.
• TTFB (Time to First Byte): How long until audio starts playing. Affected by chunk_length_schedule - the model waits for enough text before generating.
• Model limitation: WebSockets are unavailable for eleven_v3.
• Best practice: Use flush: true at conversation turn endings to ensure the buffered text gets spoken.
• Alignment data: Word-level timestamps available via alignment field for lip-sync or captions.

Best Practices

1. Use Flash models for real-time:

• eleven_flash_v2_5 for multilingual (~75ms)
• eleven_flash_v2 for English-only (~75ms)

2. Buffer audio before playback to prevent choppy output

3. Handle disconnections gracefully in WebSocket streams

4. Choose output format based on use case:

• pcm_24000 - lowest latency processing
• mp3_44100_128 - direct playback
• ulaw_8000 - telephony/Twilio integration

Voice Settings

Fine-tune voice characteristics for your use case.

Project defaults from .env — ALWAYS use these first

This project ships voice defaults in `.env` at the repo root. Every ElevenLabs TTS call from this skill must load them and pass them as `voice_settings` unless the user explicitly overrides a value in the prompt.

Speed selection rule: if the target video is a YouTube Short / vertical / templates/shorts/** composition, use ELEVENLABS_SPEED_SHORTS. Otherwise use ELEVENLABS_SPEED. Never hardcode 1.0.

Python — load defaults and call

import os
from dotenv import load_dotenv  # pip install python-dotenv
from elevenlabs import ElevenLabs, VoiceSettings

load_dotenv()  # reads .env at repo root

def project_voice_settings(*, is_shorts: bool = False) -> VoiceSettings:
    speed_var = "ELEVENLABS_SPEED_SHORTS" if is_shorts else "ELEVENLABS_SPEED"
    return VoiceSettings(
        stability=float(os.environ["ELEVENLABS_STABILITY"]),
        similarity_boost=float(os.environ["ELEVENLABS_SIMILARITY_BOOST"]),
        style=float(os.environ["ELEVENLABS_STYLE"]),
        speed=float(os.environ[speed_var]),
        use_speaker_boost=os.environ["ELEVENLABS_USE_SPEAKER_BOOST"].lower() == "true",
    )

client = ElevenLabs()  # picks up ELEVENLABS_API_KEY from env
audio = client.text_to_speech.convert(
    text="Hello from the project defaults.",
    voice_id=os.environ["ELEVENLABS_VOICE_ID"],
    model_id=os.environ["ELEVENLABS_MODEL_ID"],
    voice_settings=project_voice_settings(is_shorts=True),
)

JavaScript — load defaults and call

import "dotenv/config";  // npm i dotenv  (or pnpm add dotenv)
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

function projectVoiceSettings({ isShorts = false } = {}) {
  const speedVar = isShorts ? "ELEVENLABS_SPEED_SHORTS" : "ELEVENLABS_SPEED";
  return {
    stability: parseFloat(process.env.ELEVENLABS_STABILITY),
    similarityBoost: parseFloat(process.env.ELEVENLABS_SIMILARITY_BOOST),
    style: parseFloat(process.env.ELEVENLABS_STYLE),
    speed: parseFloat(process.env[speedVar]),
    useSpeakerBoost: process.env.ELEVENLABS_USE_SPEAKER_BOOST === "true",
  };
}

const client = new ElevenLabsClient();
const audio = await client.textToSpeech.convert(process.env.ELEVENLABS_VOICE_ID, {
  text: "Hello from the project defaults.",
  modelId: process.env.ELEVENLABS_MODEL_ID,
  voiceSettings: projectVoiceSettings({ isShorts: true }),
});

cURL — source .env and substitute

set -a; source .env; set +a   # exports every key from .env into the shell

curl -X POST "https://api.elevenlabs.io/v1/text-to-speech/$ELEVENLABS_VOICE_ID" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"text\": \"Hello from the project defaults.\",
    \"model_id\": \"$ELEVENLABS_MODEL_ID\",
    \"voice_settings\": {
      \"stability\": $ELEVENLABS_STABILITY,
      \"similarity_boost\": $ELEVENLABS_SIMILARITY_BOOST,
      \"style\": $ELEVENLABS_STYLE,
      \"speed\": $ELEVENLABS_SPEED_SHORTS,
      \"use_speaker_boost\": $ELEVENLABS_USE_SPEAKER_BOOST
    }
  }" \
  --output output.mp3

If a value is missing from .env, fail loudly — do NOT silently fall back to the ElevenLabs defaults below. The fallback table is reference material for callers who explicitly opt out of project defaults.

When the audio drives anything visual: use convert_with_timestamps

For HyperFrames work — captions, marker highlights, scene transitions tied to narration — call convert_with_timestamps instead of convert. ElevenLabs returns character-level alignment in the same response, so you get the audio AND a word-level transcript from one model in one call. Don't generate audio first and run Whisper on it; that adds a dependency, costs a second pass, and introduces transcription drift.

See SKILL.md → Word/character timestamps for the full pattern. The repo ships a working invocation at scripts/elevenlabs-tts.py that loads .env, calls convert_with_timestamps, writes audio/narration.wav, and emits transcript.json in HyperFrames' [{word, start, end}] shape:

python scripts/elevenlabs-tts.py videos/<slug> --shorts   # use ELEVENLABS_SPEED_SHORTS
python scripts/elevenlabs-tts.py videos/<slug>            # use ELEVENLABS_SPEED (long-form)

---

Parameters

Python Example

from elevenlabs import ElevenLabs
from elevenlabs import VoiceSettings

client = ElevenLabs()

audio = client.text_to_speech.convert(
    text="Testing different voice settings.",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    model_id="eleven_v3",
    voice_settings=VoiceSettings(
        stability=0.5,
        similarity_boost=0.75,
        style=0.0,
        use_speaker_boost=True
    )
)

JavaScript Example

const audio = await client.textToSpeech.convert("JBFqnCBsd6RMkjVDRZzb", {
  text: "Testing different voice settings.",
  modelId: "eleven_v3",
  voiceSettings: {
    stability: 0.5,
    similarityBoost: 0.75,
    style: 0.0,
    useSpeakerBoost: true,
  },
});

cURL Example

curl -X POST "https://api.elevenlabs.io/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Testing different voice settings.",
    "model_id": "eleven_v3",
    "voice_settings": {
      "stability": 0.5,
      "similarity_boost": 0.75,
      "style": 0.0,
      "use_speaker_boost": true
    }
  }' \
  --output output.mp3

Use Case Recommendations

Audiobooks / Narration

voice_settings=VoiceSettings(
    stability=0.7,        # Consistent tone
    similarity_boost=0.5, # Natural variation
    style=0.0
)

Conversational / Chatbots

voice_settings=VoiceSettings(
    stability=0.4,        # More expressive
    similarity_boost=0.75,
    style=0.3             # Slight style emphasis
)

News / Professional

voice_settings=VoiceSettings(
    stability=0.8,        # Very consistent
    similarity_boost=0.6,
    style=0.0
)

Character Voices / Drama

voice_settings=VoiceSettings(
    stability=0.3,        # Highly expressive
    similarity_boost=0.8,
    style=0.5             # Strong style
)

Tips

• Start with defaults and adjust incrementally
• Lower stability if voice sounds monotonous
• Reduce similarity_boost if you hear audio artifacts
• Style works with v2+, v3, and multilingual models
• Test with representative text from your actual use case
• Flash models ignore some voice settings for speed