calesthio/elevenlabs-tts
Produce, direct, integrate, and quality-control ElevenLabs text-to-speech for narration, character performance, multilingual media, long-form voiceover, and streamed or batch AI-content audio. Use when selecting ElevenLabs models or voices; preparing spoken text; controlling pronunciation, pacing, emotion, and code-switching; using TTS APIs; cloning or designing a voice with consent; repairing artifacts; mastering deliverables; or evaluating generated speech. Excludes music, sound-effect generation, conversational-agent design, and general speech recognition except transcription used to verify TTS.
npx skills add https://github.com/calesthio/generative-media-skills --skill elevenlabs-tts
Treat speech generation as casting, script adaptation, performance direction, rendering, and finishing—not as a single API call. Optimize for the listener and delivery channel, then for latency or cost.
Interpret guidance by its label:
Volatile ElevenLabs facts in this skill were checked on 2026-07-09. Before a consequential production run, query GET /v1/models, inspect the chosen voice, and recheck the current API reference, plan entitlements, policies, and terms. Never infer current availability from an old voice name or model list.
Use this skill for rendered speech and voice production. Do not expand into:
Speech-to-text may be used only as one TTS QA signal. It must not replace listening.
Before selecting a model, write down:
10. rights, consent, disclosure, privacy, plan, and budget constraints.
Do not approve a voice from a showcase sentence. Audition finalists with the actual script's hardest 20–40 seconds: emotional turns, proper nouns, numbers, and language switches.
Documented, verified 2026-07-09: current core TTS model IDs and per-request limits are listed on the ElevenLabs models page. Query the models endpoint before execution.
| Model | Use it when | Important limits and tradeoffs |
|---|---|---|
| eleven_v3 | Performance, dramatic range, inline audio tags, broad multilingual work, or native IPA control are central. | 5,000 characters/request; 70+ languages. The TTS input WebSocket and request stitching do not support v3. It does not support SSML break tags. Speaker Boost is unavailable. Greater expressiveness can increase variance and artifact risk. |
| eleven_multilingual_v2 | Stable long-form narration, professional voiceover, and high-fidelity multilingual content matter more than minimum latency. | 10,000 characters/request; 29 languages. Official guidance identifies it as the most stable long-form model. language_code is not supported for this model. Use alias dictionaries rather than phoneme tags. |
| eleven_flash_v2_5 | Low latency, scale, or incremental TTS matters and the content spans its 32 supported languages. | 40,000 characters/request; roughly 75 ms model inference for typical short inputs, excluding network/application latency. Normalize numbers, dates, currencies, URLs, and abbreviations before synthesis. |
| eleven_flash_v2 | English-only low-latency work needs phoneme-tag support. | English only; 30,000 characters/request. It supports phoneme tags and TTS WebSocket input streaming. |
Documented: ElevenLabs describes Turbo v2/v2.5 as functionally equivalent to corresponding Flash models but slower on average, and recommends Flash instead. Legacy eleven_monolingual_v1 and eleven_multilingual_v1 were scheduled for removal on 2026-07-09; do not start new work on them. Treat any still-visible legacy ID as migration-only.
Production heuristic: render the same difficult audition on two plausible model/voice combinations. Select by blind listening, pronunciation accuracy, timing, and revision stability—not provider marketing adjectives.
Documented: ElevenLabs' product guide ranks voice selection ahead of model selection and settings. A voice carries its source accent, cadence, timbre, recording traits, and performance range.
Choose among:
disable_at_unix; shared voices can become unavailable. Preserve an approved fallback voice and a migration test.Keep the text, model, and output format fixed while comparing voices. Score each 1–5 on:
Reject a voice whose source performance conflicts with the requested direction. A tag such as [whispers] cannot reliably turn a shout-trained voice into an intimate whisper.
Create a spoken-text version separate from the editorial script. Preserve the original for traceability.
01/02/2026 → choose “January second, twenty twenty-six” or “the first of February, twenty twenty-six”;$1.05 → choose “one dollar and five cents,” not a mechanical character reading;Dr. → decide “Doctor” versus “Drive”;IV → decide “four,” “the fourth,” or “I V”;Documented: Multilingual v2 generally normalizes complex numeric text more naturally than Flash v2.5. The API exposes apply_text_normalization as auto, on, or off; plan/model behavior can differ. Do not assume the normalizer knows the business meaning of an ambiguous number.
Production heuristic: normalize deterministically in your application for brand names, IDs, prices, dates, and compliance statements. Store both display text and spoken text.
Use this escalation ladder:
The enzyme /ˌrɪbəʊnjuːˈkleɪeɪs/ breaks the bond. V3 IPA is not perfectly deterministic; audition multiple renders when exactness matters.<phoneme> tags support CMU Arpabet or IPA for individual words. CMU Arpabet is the documented consistency preference for English.pronunciation_dictionary_locators, applied in order. Pin both dictionary ID and version ID in the render manifest.Never paste unsupported XML and assume it will be interpreted. Test a dictionary using the exact voice/model pair; a correct lexicon can still sound wrong in context.
stability spans 0–1. Lower values broaden emotional variation; higher values reduce variation and can become monotone.similarity_boost spans 0–1 and controls adherence to the source voice. Very high similarity may reproduce source defects.style exaggerates source style, can increase latency and instability, and should normally begin at 0.use_speaker_boost can subtly increase identity similarity at a latency cost.speed supports 0.7–1.2, with 1.0 neutral; extremes can reduce quality.<break time="1.2s" /> only on models that support break tags. Documented: breaks can be up to three seconds; excessive tags may introduce speed changes or artifacts.Production heuristic: do not compensate for a bad cast with extreme settings. Test a compact grid around the stored voice settings, then lock the chosen settings in the manifest.
[whispers], [sighs], [curious], or [excited] only when they fit the voice and scene.Production heuristic: tags are performance suggestions, not deterministic commands. Generate variants, select the take, and log the exact text, voice, model, settings, seed, and request ID. A seed is only a best-effort repeatability aid; the API does not guarantee determinism.
Documented: use a voice trained in the target language and region for the most natural accent. A voice used outside its training language may retain or drift toward its source accent. Website language detection can be confused by multiple languages in one prompt; the API's optional ISO 639-1 language_code can disambiguate supported models and normalization, but is not supported by Multilingual v2.
For one target language:
For code-switching:
language_code across genuinely mixed-language text;Inference: v3's broader language coverage may reduce the need to split some mixed-language performances, but its higher expressive variance can still create accent or timing discontinuities. Test the actual combination.
Prefer ElevenCreative Studio when editors need paragraph-level generation history, locking, timing edits, pronunciation dictionaries, collaboration, and chapter/project export. Use the API when the pipeline needs deterministic manifests, automated batching, programmatic retry, or custom assembly.
For API long-form work:
previous_text and next_text for boundary context, or use request stitching with prior request IDs where supported;Production heuristic: a paragraph is a useful editing unit, not a universal chunk size. Very short chunks lose prosodic context; very long chunks make repair expensive and can drift. Choose chunks by discourse and revision risk.
POST /v1/text-to-speech/{voice_id})Use when the complete text is known, simplicity matters, and playback can wait for the full response.
.../{voice_id}/stream)Use when the complete text is known but a listener should hear audio before the render finishes. It changes time-to-first-audio, not the need for textual context.
.../{voice_id}/stream-input)Use when text arrives incrementally. Documented: it does not support eleven_v3. Prefer auto_mode; otherwise keep the default chunk_length_schedule until measured evidence justifies a change. Smaller text thresholds can reduce latency but commit prosody before enough context exists. Send flush: true at a turn boundary where supported; an empty text string closes the connection, while a single space can keep it alive. The current guide states that idle connections close after 20 seconds.
Use speech-with-timestamps or stream-with-timestamps when captions, word highlighting, lip-sync guides, or edit alignment are required. The response contains base64 audio and character alignment for original and normalized text. Validate timing after final text and audio edits.
mp3_44100_128; higher-quality formats can require higher tiers. Treat plan entitlements as volatile.ELEVENLABS_API_KEY from a secret store; never log or ship it to a client.voice_id.current-concurrent-requests / maximum-concurrent-requests headers.429, distinguish rate limit from concurrent-limit error and use exponential backoff with jitter or wait for active work to finish. Retry transient 5xx; do not blindly retry authentication or invalid payloads.optimize_streaming_latency as deprecated.Example, not a mandatory formula.
Intent: produce a polished 45-second English product explainer with two brand names, a price, and caption timing. Latency is irrelevant; stable delivery and clean revision are primary.
Selection: audition native regional narration voices on the hardest paragraph; choose eleven_multilingual_v2 for steady professional narration. Use an alias dictionary for the brand name because Multilingual v2 does not use phoneme tags.
Spoken text:
Meet Auralis. It turns a forty-nine-dollar monthly workflow into one clear production board.
Import the brief, approve each voice take, and export a review link—without renaming files by hand.
Alias dictionary excerpt (auralis-brand.pls):
<?xml version="1.0" encoding="UTF-8"?>
<lexicon version="1.0"
xmlns="http://www.w3.org/2005/01/pronunciation-lexicon"
alphabet="ipa"
xml:lang="en-US">
<lexeme>
<grapheme>Auralis</grapheme>
<alias>aw RAL iss</alias>
</lexeme>
</lexicon>
Render manifest excerpt:
provider: elevenlabs
model_id: eleven_multilingual_v2
voice_id: <auditioned-native-narration-voice-id>
output_format: mp3_44100_128
voice_settings:
stability: 0.62
similarity_boost: 0.76
style: 0.0
use_speaker_boost: true
speed: 0.97
pronunciation_dictionary:
id: <dictionary-id>
version_id: <pinned-version-id>
text_normalization: auto
Complete Python call:
import os
from elevenlabs import VoiceSettings
from elevenlabs.client import ElevenLabs
from elevenlabs.play import PronunciationDictionaryVersionLocator
client = ElevenLabs(api_key=os.environ["ELEVENLABS_API_KEY"])
audio = client.text_to_speech.convert(
voice_id=os.environ["ELEVENLABS_VOICE_ID"],
model_id="eleven_multilingual_v2",
output_format="mp3_44100_128",
text=(
"Meet Auralis. It turns a forty-nine-dollar "
"monthly workflow into one clear production board.\n\n"
"Import the brief, approve each voice take, and export a review link—"
"without renaming files by hand."
),
voice_settings=VoiceSettings(
stability=0.62,
similarity_boost=0.76,
style=0.0,
use_speaker_boost=True,
speed=0.97,
),
pronunciation_dictionary_locators=[
PronunciationDictionaryVersionLocator(
pronunciation_dictionary_id=os.environ["ELEVENLABS_DICT_ID"],
version_id=os.environ["ELEVENLABS_DICT_VERSION"],
)
],
)
with open("narration.mp3", "wb") as f:
for chunk in audio:
f.write(chunk)
Why: the text expands price and hyphenates spoken phrasing; the dictionary makes the brand reusable; moderate stability preserves life without making revisions chaotic; style begins at zero.
Expected result: credible, restrained narration with the price and brand pronounced consistently. Generate a timestamped version separately if the SDK surface in use requires a distinct method.
Likely failures and repairs:
Variation: for a live preview, keep the same model/voice but use HTTP streaming; do not move to the input WebSocket because the full script is already known.
Example, not a mandatory formula.
Intent: create a 15-second game teaser line that moves from confidential to delighted while precisely pronouncing a fictional name.
Selection: use a consent-cleared designed voice whose source range already supports whisper and excitement; choose eleven_v3 for inline performance direction and native IPA.
Complete input:
[whispers] They told us the vault beneath /keɪˈlɔːrə/ was empty...
[restrained excitement] They were VERY wrong. [soft laugh]
Parameters: model_id=eleven_v3, selected v3-compatible voice, HTTP complete or HTTP stream endpoint, v3 Natural stability behavior, speed=1.0, output_format=mp3_44100_128, fixed seed only as a best-effort comparison aid. Do not send SSML breaks or Speaker Boost.
Why: the cast already supports the intended range; tags describe audible delivery; IPA is selective; punctuation provides the pause.
Expected result: a controlled whisper, a weighted pause, then contained excitement without changing speaker identity.
Likely failures and repairs:
Variation: for a stable 20-minute narrator, switch the production design to Multilingual v2 and paragraph chunks rather than forcing v3 to behave like a long-form stability model.
Example, not a mandatory formula.
Intent: narrate an English tutorial containing a Spanish customer quote while preserving one narrator identity.
Inputs: native bilingual voice audition, English base text, reviewed Spanish quote, locale-specific pronunciations, 48 kHz edit timeline.
Workflow:
language_code over the mixed paragraph.Expected result: intelligible switches without an accidental caricatured accent or identity jump.
Likely failures: language detector chooses the wrong language on the short quote; English proper nouns acquire Spanish phonology; split clips change room tone or energy. Repair by extending contextual text, selecting a genuinely bilingual voice, or using a separately cast and disclosed speaker when identity continuity is less important than native delivery.
Automated checks catch defects; listeners decide whether the voice communicates.
Standard: use ITU-T P.800-style controlled listening or ITU-T P.808 guidance for crowdsourced listening when running formal tests. Keep test conditions and instructions consistent; randomize and blind samples where practical.
Production heuristic: have at least one target-language native listener and one production listener rate:
Use a 1–5 scale with written defect timecodes. Compare against the prior approved take and, where licensed, a human reference. Do not average away a critical mispronunciation or rights failure.
An ASR transcript or word-error comparison may flag omissions and substitutions, but it cannot judge acting, accent appropriateness, prosody, or subtle artifacts.
Diagnose before changing parameters:
| Failure | First checks | Repair order |
|---|---|---|
| Wrong word/number | spoken-text normalization, locale, dictionary support/version | rewrite → alias/IPA/phoneme if supported → alternate native voice/model |
| Flat delivery | cast, source performance, stability too high, weak text cues | improve cast/text → lower stability cautiously → v3 with suitable tags |
| Overacting/hallucinated sounds | v3 tags, Creative behavior, stability too low, mismatched voice | remove tags → use Natural/Robust behavior → select calmer voice/model |
| Identity drift | chunk length, voice quality, similarity, model/settings changes | restore fixed manifest → add context/stitching → raise consistency cautiously → recast |
| Audible seams | arbitrary splits, missing context, loudness/room mismatch | split at clauses → previous/next context or request IDs → local edit/crossfade |
| Numeric errors on Flash | unnormalized text, normalization policy | deterministic spoken expansion → enable supported normalization → Multilingual v2 |
| High latency | measured TTFA components, model, protocol, buffer, voice type, geography | HTTP stream known text → WebSocket incremental text → Flash/voice/buffer tuning |
| 429 | rate vs concurrency code and response headers | reduce/queue concurrency → exponential backoff with jitter |
| 4xx payload/auth | model access, voice access, key, limit, format | fix request; do not blind-retry |
| Persistent 5xx | provider status, request ID, minimal reproduction | bounded retry with backoff → preserve failure metadata → escalate |
Change one variable per diagnostic render. Preserve the failed audio and its manifest so the lesson is reproducible.
Before cloning or deploying any recognizable voice:
10. protect scripts and voice data. Documented: API enable_logging=false activates Zero Retention Mode only for eligible Enterprise customers and disables history-dependent features such as request stitching. Default processing otherwise follows the applicable Privacy Policy and terms. Decide explicitly whether confidentiality or history-dependent continuity wins;
11. do not advertise detection as proof of authenticity. ElevenLabs' signed-in Audio Detector checks SynthID where present and falls back to a statistical classifier; coverage is not universal, and modified audio may evade statistical detection.
When a rights or safety gate fails, stop. A technically excellent render is not releasable without authorization.
All volatile ElevenLabs sources below were checked 2026-07-09.
Take calesthio/elevenlabs-tts from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.