Skip to content
ElevenLabs Text to Speech

ElevenLabs Text to Speech Skill

ElevenLabs' official skill for generating speech from text with the ElevenLabs API, SDKs and CLI: model choice, voices, voice settings, language codes, audio effects, streaming and errors.

GitHub Docs

Install

Install with the skills CLI

One command for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf and dozens of other agents. Needs Node.js; the skill is fetched straight from elevenlabs/skills.

$ npx skills add elevenlabs/skills --skill text-to-speech

Run it in a terminal. The CLI finds the agents installed on your machine, asks which ones to add the skill to, and whether to install it into the folder you ran it from or for all your projects.

Other ways to install

Copy the whole skill folder — SKILL.md and any scripts or references beside it — into ~/.claude/skills/text-to-speech/, where Claude Code picks it up in every project. Only git is needed.

tmp=$(mktemp -d) && \
  git clone --depth 1 --branch main https://github.com/elevenlabs/skills.git "$tmp" && \
  mkdir -p ~/.claude/skills && \
  cp -R "$tmp"/text-to-speech ~/.claude/skills/text-to-speech

No scripts or references next to it? Saving the SKILL.md alone as ~/.claude/skills/text-to-speech/SKILL.md works too.

Using another agent? Its personal skills folder
Codex
~/.agents/skills/
Cursor
~/.cursor/skills/
GitHub Copilot
~/.copilot/skills/
Gemini CLI
~/.gemini/skills/
Windsurf
~/.codeium/windsurf/skills/
OpenCode
~/.config/opencode/skills/

About

  • Python, JavaScript and CLI examples for converting text to speech
  • Model comparison from Eleven v4 to the low-latency Flash models
  • Voice selection guidance, including what free plans can use
  • Voice settings, language enforcement and text normalisation
  • Audio effects: filters, distance, reverb, background noise and panning
  • Request stitching, streaming, output formats, errors and cost tracking

ElevenLabs Text to Speech is the official ElevenLabs agent skill for turning text into speech, from the elevenlabs/skills repository. It helps a coding agent generate voiceovers, add speech to an app or build voice features with the ElevenLabs API, and requires internet access and an ELEVENLABS_API_KEY; if the key is missing it tells the agent to run the ElevenLabs CLI's onboarding first.

Quick starts show the same request in Python, JavaScript (with the stream bridged to a file in Node) and the CLI, where elevenlabs say plays text immediately and the text-to-speech convert command sets parameters directly. A model table compares Eleven v4 (the default in its examples, 90+ languages), v4 Turbo for real-time use, the Flash v2.5 and v2 models for the lowest latency and cost, and the previous Multilingual v2 and v3 models, with notes on what v4 does not support, such as SSML and style or speed settings.

Further sections cover choosing voices (pre-made voices work on free plans, while Voice Library voices return a 402 there), voice settings such as stability and similarity boost, enforcing a language with ISO 639-1 codes, text normalisation of numbers and dates, audio effects (filter presets, distance, reverb environments, background noise beds and panning), request stitching to avoid pops, pauses and tone shifts where long audio is split across requests, output formats, streaming, error handling and tracking costs. MIT licensed.

SKILL.md

The instructions your agent loads, as published by ElevenLabs.

SKILL.md
name
text-to-speech
description
Convert text to speech using ElevenLabs voice AI. Use when generating audio from text, creating voiceovers, building voice apps, or synthesizing speech in 90+ languages.
license
MIT
compatibility
Requires internet access and an ElevenLabs API key (ELEVENLABS_API_KEY).
metadata
{"openclaw": {"requires": {"env": ["ELEVENLABS_API_KEY"]}, "primaryEnv": "ELEVENLABS_API_KEY"}}

ElevenLabs Text-to-Speech

Generate natural speech from text - supports 90+ languages, multiple models for quality vs latency tradeoffs. Examples default to eleven_v4, the latest and highest-quality model.

Setup, before writing any code: if ELEVENLABS_API_KEY isn't set for this project, run npx -y @elevenlabs/cli@latest onboard init from the app's folder first and follow what it prints: it signs the user in and stores a key for the project, so nobody copies one by hand. Otherwise see the [Installation Guide](references/installation.md). For JavaScript, use @elevenlabs/* packages only.
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_v4"
)

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";
import { Readable } from "stream";

const client = new ElevenLabsClient();
const audio = await client.textToSpeech.convert("JBFqnCBsd6RMkjVDRZzb", {
  text: "Hello, welcome to ElevenLabs!",
  modelId: "eleven_v4",
});
// convert() returns a web ReadableStream — bridge it to a Node stream to write to disk
Readable.fromWeb(audio).pipe(createWriteStream("output.mp3"));
CLI

Use say to play text immediately with the default voice and eleven_v3 model:

elevenlabs say "Hello!"

Pipe text into say when another command produces the input:

echo "The build finished successfully." | elevenlabs say

Use the API command when you need to set request parameters directly:

elevenlabs text-to-speech convert --voice-id JBFqnCBsd6RMkjVDRZzb \
  --text "Hello!" --model-id eleven_v4 --output output.mp3

The CLI reads ELEVENLABS_API_KEY from the environment automatically.

Models
Model IDLanguagesLatencyBest For
eleven_v490+StandardDefault. Highest quality, emotional range, audio tags, voice cloning accuracy
eleven_v4_turbo90+~100msReal-time v4 quality for agents and interactive apps (via [Text to Dialogue WebSocket](references/streaming.md#eleven-v4-turbo-websocket))
eleven_flash_v2_532~75msLowest latency, lowest cost, stream-input WebSocket
eleven_flash_v2English~75msEnglish-only, lowest latency
eleven_multilingual_v229StandardPrevious generation; most stable on very long-form generations
eleven_v370+StandardPrevious generation expressive model

eleven_turbo_v2_5 and eleven_turbo_v2 are superseded by the Flash models (same output, lower latency) — use eleven_flash_v2_5 / eleven_flash_v2 instead.

Eleven v4 notes: supports only stability and similarity_boost voice settings (no style or speed), does not support SSML, and is not available on the stream-input TTS WebSocket. Direct delivery with audio tags such as [whispers], [laughs], [sarcastic].

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)

Pick a voice the account's plan can use. Free plans can use pre-made voices through the API, but not Voice Library voices: those fail with a 402 (paid_plan_required). Use George unless the user asks for something else. Do not use a voice ID from memory. Tutorials still use voices that have since been retired (Rachel, Charlotte, Josh and others), and those fail the same way on a free plan. To choose another voice, list the pre-made ones:

voices = client.voices.get_all()
for voice in voices.voices:
    if voice.category == "premade":
        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 (v2/v3 models; not supported on Eleven v4).
  • Speed: Speech speed multiplier (v2/v3 models; not supported on Eleven v4).
  • 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",
    model_id="eleven_v4",
    voice_settings=VoiceSettings(
        stability=0.5,          # Lower = more expressive, higher = more consistent
        similarity_boost=0.75,  # Higher = closer to the reference voice
    )
)
Language Selection

Use language_code with models that support language enforcement to guide pronunciation and text normalization. Unsupported language codes are ignored, and language_code is not supported on eleven_multilingual_v2.

audio = client.text_to_speech.convert(
    text="Bonjour, comment allez-vous?",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    model_id="eleven_v4",
    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",
    model_id="eleven_v4",
    apply_text_normalization="on"
)
Audio Effects

Use audio_effects to process the generated audio with a filter preset, perceived distance, a reverb environment, a looped background noise bed, and stereo panning. Effects do not change the cost of a request.

FieldRangeDescription
filter_preset_idCatalog IDFilter that colors the voice, such as phone or old_radio
distance0-1 (default 0)How far the speaker sounds from the microphone
environment_idCatalog IDReverb environment, such as small_room or hall
send_level0-1 (default 1)How much of the voice feeds the reverb; 0 turns reverb off
background_noise_idCatalog IDBackground noise looped under the voice, such as cafe or keyboard
pan-1 to 1 (default 0)Stereo position of the voice, from hard left to hard right

List valid filter preset, environment, and background noise IDs with the catalog endpoint (GET /v1/audio-effects/catalog):

from elevenlabs import EffectsSpecInput

catalog = client.audio_effects.get_catalog()
for environment in catalog.environments:
    print(f"{environment.environment_id}: {environment.name}")

audio = client.text_to_speech.convert(
    text="Welcome to the concert hall.",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    model_id="eleven_v4",
    audio_effects=EffectsSpecInput(
        environment_id="hall",
        distance=0.3,
        pan=-0.5,
    )
)

Reverb and non-zero pan produce stereo audio and are rejected for ulaw_*, alaw_*, and pcm_* output formats. Unknown effect IDs return a 404 error.

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",
    model_id="eleven_v4",
    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",
    model_id="eleven_v4",
    previous_text="This is the first part."
)
Output Formats
FormatDescription
mp3_44100_128MP3 44.1kHz 128kbps (default) - compressed, good for web/apps
mp3_44100_192MP3 44.1kHz 192kbps (Creator+) - higher quality compressed
mp3_44100_64MP3 44.1kHz 64kbps - lower quality, smaller files
mp3_22050_32MP3 22.05kHz 32kbps - smallest MP3 files
pcm_16000Raw PCM 16kHz - use for real-time processing
pcm_22050Raw PCM 22.05kHz
pcm_24000Raw PCM 24kHz - good balance for streaming
pcm_44100Raw PCM 44.1kHz (Pro+) - CD quality
pcm_48000Raw PCM 48kHz (Pro+) - highest quality
ulaw_8000μ-law 8kHz - standard for phone systems (Twilio, telephony)
alaw_8000A-law 8kHz - telephony (alternative to μ-law)
opus_48000_64Opus 48kHz 64kbps - efficient streaming codec
wav_44100WAV 44.1kHz - uncompressed with headers
Streaming

Use the stream method to receive 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_v4"
)

for chunk in audio_stream:
    play_audio(chunk)

For real-time apps where latency matters most, use eleven_v4_turbo (~100ms) over the Text to Dialogue WebSocket, or eleven_flash_v2_5 (~75ms) over HTTP streaming or the stream-input WebSocket. See [references/streaming.md](references/streaming.md).

Error Handling
try:
    audio = client.text_to_speech.convert(
        text="Generate speech",
        voice_id="invalid-voice-id",
        model_id="eleven_v4"
    )
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_v4"
)
audio = response.parse()
print(f"Characters used: {response.headers.get('x-character-count')}")
References
  • [Installation Guide](references/installation.md)
  • [Streaming Audio](references/streaming.md)
  • [Voice Settings](references/voice-settings.md)
Install

Skill: MCP Builder

by Anthropic

Anthropic's guide for building high-quality MCP servers end to end — research, tool design, implementation in TypeScript or Python, testing, and a 10-question evaluation suite.

Skill: AWS CDK

by Amazon Web Services

Featured

Official AWS skill for authoring, deploying and debugging CDK stacks — construct patterns, bootstrap, drift, resource import and the CloudFormation errors that trap people.

Skill: uv

by Astral

New

Astral's official skill that teaches coding agents to use uv for Python scripts, projects, tools and type checking, and to migrate pip, pipx and pyenv commands to their uv equivalents.

Browse all skills →