Basic call shape

from elevenlabs.client import ElevenLabs

client = ElevenLabs()  # reads ELEVENLABS_API_KEY from env
audio = client.text_to_speech.convert(
    text="The first move is what sets everything in motion.",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    model_id="eleven_flash_v2_5",
    output_format="mp3_44100_128",
)
with open("out.mp3", "wb") as f:
    for chunk in audio:
        f.write(chunk)

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
const client = new ElevenLabsClient();
const audio = await client.textToSpeech.convert("JBFqnCBsd6RMkjVDRZzb", {
  text: "The first move is what sets everything in motion.",
  modelId: "eleven_flash_v2_5",
  outputFormat: "mp3_44100_128",
});

convert() returns an iterator of bytes (Python) or a ReadableStream<Uint8Array> (JS). It does not write to disk. The agent must collect bytes and write the file.

Model selection

Pick by latency and credit math, not by name. Flash and Turbo are half-price per character.

Decision rule: real-time or tight budget, use eleven_flash_v2_5. Polished narration in 29 main languages, eleven_multilingual_v2. Expressive character work, audio-tagged emotion, or rare languages, eleven_v3. Flash and Turbo do not auto-normalize numbers; if the script has "1999" the model may read "one nine nine nine". Pre-normalize the text, or set apply_text_normalization on Creator+ plans.

Voice selection and cloning

Default voices come with the account. List them with client.voices.search(). Pin a voice_id once chosen so output is reproducible.

Two cloning paths:

• Instant Voice Cloning (IVC): 1 sample, ~1 min audio. Starter plan and up. Lower fidelity, fast.
• Professional Voice Cloning (PVC): 30+ min of clean audio, captcha-verified. Creator plan ($22/mo) and above. Much better fidelity.

voice = client.voices.ivc.create(
    name="Narrator Alex",
    files=["./sample_0.mp3", "./sample_1.mp3", "./sample_2.mp3"],
)
# Store voice.voice_id and reuse it on every convert() call.

PVC verification asks the speaker to read a captcha phrase in the same voice as the uploads. ElevenLabs denies activation on mismatch. The agent cannot bypass this.

Streaming pattern

Use streaming when first-audio-byte latency under 1 second matters (live agent, interactive playback). Skip streaming for batch narration to file.

from elevenlabs import stream
from elevenlabs.client import ElevenLabs
audio_stream = ElevenLabs().text_to_speech.stream(
    text="Streaming response coming through.",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    model_id="eleven_flash_v2_5",
)
stream(audio_stream)  # plays locally; or pipe bytes to a websocket

For sub-200ms first-byte latency use the websocket endpoint (text-to-speech/{voice_id}/stream-input) and feed text chunks as the upstream LLM produces them. Multi-context websocket is only needed for concurrent independent streams over one socket.

Voice settings worth tuning

voice_settings accepts: stability (0-1, default 0.5; lower means more emotional range), similarity_boost (0-1, default 0.75; how strictly the model adheres to the cloned voice), style (0-1, default 0; exaggerates characteristics, leave at 0 unless you want stylized reads), use_speaker_boost (bool, default true), speed (default 1.0; safe range 0.7 to 1.2).

For audiobook narration: stability 0.55, similarity_boost 0.85, style 0. For dialog and character reads drop stability to 0.3.

Cost gotchas

• Free tier: 10,000 credits/month, NO commercial license, forced attribution
• 1 credit = 1 character on v2/v3, 0.5 credits/char on Flash and Turbo
• Failed requests (filter or quota) usually do not refund credits
• PVC needs Creator plan ($22/mo), IVC works on Starter
• Conversational AI agents are billed per-minute, separate from TTS character pool
• Scribe STT is billed per minute of input audio

Point the user at scopeful.org/tools/elevenlabs for live USD-per-character math across all plans, including cloning and Scribe.

What to deliver to the user

When the agent produces speech, return:

1. The output file path (write to disk, do not dump bytes into chat)
2. One line stating the model used and the character count, so the user can verify burn rate
3. The voice_id used, so the user can reproduce or iterate
4. If voice_settings was used, the exact values

Example: Wrote out.mp3 (1,247 chars on eleven_flash_v2_5, ~624 credits). Voice: JBFqnCBsd6RMkjVDRZzb (George). stability=0.5, similarity_boost=0.75.

What NOT to do

• Do not clone a voice the user does not own or have written permission to use. ElevenLabs ToS allows only your own voice or one you are explicitly authorized to share. Cloning a celebrity, podcast host, or coworker without consent is a ToS violation and in many jurisdictions is illegal.
• Do not generate commercial content on the free tier. No commercial license, attribution required.
• Do not loop convert() over many small chunks of one document. Use the websocket streaming endpoint or batch into one call up to the model's max characters.
• Do not commit API keys to git. Use env vars or a secrets manager.
• Do not assume credit refunds on failed generations. Validate input length and voice_id before firing the call.
• Do not pick eleven_v3 by default. It is the most expressive but capped at 5,000 chars per call. For most narration jobs eleven_multilingual_v2 or eleven_flash_v2_5 is the right pick.

Useful follow-ups after a successful generation

• Lip-sync video on top of this VO? Chain to Hedra or HeyGen with the audio file as input
• Background music under the narration? Chain to Suno for the bed, mix in a DAW or with ffmpeg
• Captions? Run Scribe (speech_to_text) on the file for word-level timestamps suitable for SRT or VTT
• Agent that needs both ears and mouth? Wire eleven_flash_v2_5 for TTS plus scribe_v2_realtime for STT, both via the same MCP server