ElevenLabs Text-to-Speech

TTS with ElevenLabsTTSService (WebSocket), ElevenLabsHttpTTSService (HTTP), and ElevenLabsDialogueTTSService for Eleven v3.

Overview

ElevenLabs provides high-quality text-to-speech synthesis with three service implementations:

• ElevenLabsTTSService (WebSocket) — Real-time streaming with word-level timestamps, audio context management, and interruption handling. Recommended for interactive applications.
• ElevenLabsHttpTTSService (HTTP) — Simpler batch-style synthesis. Suitable for non-interactive use cases or when WebSocket connections are not possible.
• ElevenLabsDialogueTTSService (WebSocket) — Uses the multi-context Text-to-Dialogue endpoint, which is the only way to reach the Eleven v3 models (eleven_v3, eleven_v3_conversational) and their inline audio tags. Requires workspace access to the Text-to-Dialogue API.

ElevenLabs TTS API Reference

Complete API reference for all parameters and methods

Example Implementation

Complete example with WebSocket streaming

ElevenLabs Documentation

Official ElevenLabs TTS API documentation

Voice Library

Browse and clone voices from the community

Text-to-Dialogue Example

Complete example using Eleven v3 models

Text-to-Dialogue Documentation

Official ElevenLabs Text-to-Dialogue API documentation

Installation

uv add "pipecat-ai[elevenlabs]"

Prerequisites

1. ElevenLabs Account: Sign up at ElevenLabs
2. API Key: Generate an API key from your account dashboard
3. Voice Selection: Choose voice IDs from the voice library

Set the following environment variable:

export ELEVENLABS_API_KEY=your_api_key

Configuration

ElevenLabsTTSService

api_key · str · required

ElevenLabs API key.

voice_id · str · required · deprecated

Voice ID from the voice library. Deprecated in v0.0.105. Use settings=ElevenLabsTTSService.Settings(voice=...) instead.

model · str · default: "eleven_flash_v2_5" · deprecated

ElevenLabs model ID. To set language explicitly, use one of the models that accept a language code — eleven_flash_v2_5, eleven_turbo_v2_5, eleven_v3, or eleven_v3_conversational. Deprecated in v0.0.105. Use settings=ElevenLabsTTSService.Settings(model=...) instead.

url · str · default: "wss://api.elevenlabs.io"

WebSocket endpoint URL. Override for custom or proxied deployments.

sample_rate · int · default: "None"

Output audio sample rate in Hz. When None, uses the pipeline’s configured sample rate.

auto_mode · bool · default: "None"

Whether to enable ElevenLabs’ auto mode, which reduces latency by disabling server-side chunk scheduling and buffering. Recommended when sending complete sentences or phrases. When None (default), auto mode is automatically enabled for SENTENCE aggregation and disabled for TOKEN aggregation — because token streaming relies on the server-side chunk scheduler to accumulate enough text for natural-sounding synthesis.

text_aggregation_mode · TextAggregationMode · default: "TextAggregationMode.SENTENCE"

Controls how incoming text is aggregated before synthesis. SENTENCE (default) buffers text until sentence boundaries, producing more natural speech. TOKEN streams tokens directly for lower latency. Import from pipecat.services.tts_service.

aggregate_sentences · bool · default: "None" · deprecated

Deprecated in v0.0.104. Use text_aggregation_mode instead.

params · InputParams · default: "None" · deprecated

Deprecated in v0.0.105. Use settings=ElevenLabsTTSService.Settings(...) instead.

pronunciation_dictionary_locators · List[PronunciationDictionaryLocator] · default: "None" · deprecated

List of pronunciation dictionary locators to use. Deprecated in v1.6.0. Use the text_transforms parameter with replace_text instead. Pronunciation dictionary substitutions can rewrite the spoken words in ways that no longer match the text sent to synthesis, which breaks the alignment-based word-completion tracking used to attribute spoken text back to the conversation context. Will be removed in v2.0.0.

settings · ElevenLabsTTSService.Settings · default: "None"

Runtime-configurable settings. See Settings below.

ElevenLabsHttpTTSService

The HTTP service accepts the same parameters as the WebSocket service, with these differences:

aiohttp_session · aiohttp.ClientSession · required

An aiohttp session for HTTP requests. You must create and manage this yourself.

base_url · str · default: "https://api.elevenlabs.io"

HTTP API base URL (instead of url for WebSocket).

enable_logging · bool · default: "None"

Whether to enable ElevenLabs server-side logging. Set to False for zero retention mode (enterprise only).

pronunciation_dictionary_locators · List[PronunciationDictionaryLocator] · default: "None" · deprecated

List of pronunciation dictionary locators to use. Deprecated in v1.6.0. Use the text_transforms parameter with replace_text instead. Pronunciation dictionary substitutions can rewrite the spoken words in ways that no longer match the text sent to synthesis, which breaks the alignment-based word-completion tracking used to attribute spoken text back to the conversation context. Will be removed in v2.0.0.

The HTTP service uses ElevenLabsHttpTTSSettings which also includes:

optimize_streaming_latency · int · default: "None"

Latency optimization level (0–4). Higher values reduce latency at the cost of quality.

ElevenLabsDialogueTTSService

api_key · str · required

ElevenLabs API key.

url · str · default: "wss://api.elevenlabs.io"

WebSocket endpoint URL. Override for custom or proxied deployments.

sample_rate · int · default: "None"

Output audio sample rate in Hz. When None, uses the pipeline’s configured sample rate.

enable_logging · bool · default: "None"

Whether to enable ElevenLabs server-side logging. Set to False for zero retention mode (enterprise only).

seed · int · default: "None"

Seed for reproducible generation.

text_aggregation_mode · TextAggregationMode · default: "TextAggregationMode.SENTENCE"

Text-to-Dialogue concatenates consecutive inputs verbatim, so only SENTENCE aggregation is supported. Any other value is ignored with a warning.

settings · ElevenLabsDialogueTTSService.Settings · default: "None"

Runtime-configurable settings. See Text-to-Dialogue settings below.

Settings

Runtime-configurable settings passed via the settings constructor argument using ElevenLabsTTSService.Settings(...). These can be updated mid-conversation with TTSUpdateSettingsFrame. See Service Settings for details.

Parameter	Type	Default	Description
model	str	None	ElevenLabs model identifier. (Inherited from base settings.)
voice	str	None	Voice identifier. (Inherited from base settings.)
language	Language | str	None	Language code. Applies to the four models that accept one; see Notes. (Inherited from base settings.)
stability	float	NOT_GIVEN	Voice consistency (0.0–1.0). Lower values are more expressive, higher values are more consistent.
similarity_boost	float	NOT_GIVEN	Voice clarity and similarity to the original (0.0–1.0).
style	float	NOT_GIVEN	Style exaggeration (0.0–1.0). Higher values amplify the voice’s style.
use_speaker_boost	bool	NOT_GIVEN	Enhance clarity and target speaker similarity.
speed	float	NOT_GIVEN	Speech rate. WebSocket: 0.7–1.2. HTTP: 0.25–4.0.
apply_text_normalization	Literal	NOT_GIVEN	Text normalization: "auto", "on", or "off".

NOT_GIVEN values use the ElevenLabs API defaults. See ElevenLabs voice settings for details on how these parameters interact.

Text-to-Dialogue settings

ElevenLabsDialogueTTSService.Settings(...) accepts a smaller set. Text-to-Dialogue reads only stability; it silently ignores the other voice settings the text-to-speech endpoint accepts.

Parameter	Type	Default	Description
model	str	"eleven_v3_conversational"	Must be an Eleven v3 model (eleven_v3 or eleven_v3_conversational); anything else logs a warning.
voice	str	None	Voice identifier.
language	Language | str	None	Language code. Eleven v3 covers 74 languages; the v2.5 models cover 32.
stability	float	NOT_GIVEN	Voice stability (0.0–1.0). 0.0 is most expressive but can hallucinate, 0.5 stays closest to the reference recording, and 1.0 is most consistent but least responsive to audio tags.

Usage

Basic Setup

from pipecat.services.elevenlabs.tts import ElevenLabsTTSService

tts = ElevenLabsTTSService(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
    settings=ElevenLabsTTSService.Settings(
        voice="21m00Tcm4TlvDq8ikWAM",  # Rachel
    ),
)

With Voice Customization

tts = ElevenLabsTTSService(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
    settings=ElevenLabsTTSService.Settings(
        voice="21m00Tcm4TlvDq8ikWAM",
        model="eleven_flash_v2_5",
        language=Language.ES,
        stability=0.7,
        similarity_boost=0.8,
        speed=1.1,
    ),
)

Updating Settings at Runtime

Voice settings can be changed mid-conversation using TTSUpdateSettingsFrame:

from pipecat.frames.frames import TTSUpdateSettingsFrame
from pipecat.services.elevenlabs.tts import ElevenLabsTTSSettings

await worker.queue_frame(
    TTSUpdateSettingsFrame(
        delta=ElevenLabsTTSSettings(
            stability=0.3,
            speed=1.1,
        )
    )
)

HTTP Service

import aiohttp
from pipecat.services.elevenlabs.tts import ElevenLabsHttpTTSService

async with aiohttp.ClientSession() as session:
    tts = ElevenLabsHttpTTSService(
        api_key=os.getenv("ELEVENLABS_API_KEY"),
        settings=ElevenLabsHttpTTSService.Settings(
            voice="21m00Tcm4TlvDq8ikWAM",
        ),
        aiohttp_session=session,
    )

Text-to-Dialogue (Eleven v3)

from pipecat.services.elevenlabs.dialogue.tts import ElevenLabsDialogueTTSService

tts = ElevenLabsDialogueTTSService(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
    settings=ElevenLabsDialogueTTSService.Settings(
        voice=os.getenv("ELEVENLABS_VOICE_ID"),
        model="eleven_v3_conversational",
        stability=0.5,
    ),
)

The InputParams / params= pattern is deprecated as of v0.0.105. Use Settings / settings= instead. See the Service Settings guide for migration details.

Notes

• Models that accept language: Four models take a language code — eleven_flash_v2_5 and eleven_turbo_v2_5 cover 32 languages, and eleven_v3 and eleven_v3_conversational cover 74, a superset that adds Farsi, Pashto, and Sindhi among others. Any other model, eleven_multilingual_v2 included, detects the language from the text itself; setting language there logs a warning and the code is dropped. A code the model doesn’t cover is dropped the same way.
• WebSocket vs HTTP: The WebSocket service supports word-level timestamps and interruption handling, making it significantly better for interactive conversations. The HTTP service is simpler but lacks these features.
• Text aggregation: Sentence aggregation is enabled by default (text_aggregation_mode=TextAggregationMode.SENTENCE). Buffering until sentence boundaries produces more natural speech. Set text_aggregation_mode=TextAggregationMode.TOKEN to stream tokens directly for lower latency. The auto_mode parameter is automatically configured based on the aggregation mode for optimal quality.
• Word timestamp accuracy: Word timestamps reflect the original input text by default, preserving non-Latin scripts in transcripts and LLM context. Text normalization (apply_text_normalization) does not affect which alignment field is used.
• Choosing a service: Use ElevenLabsTTSService for the Flash, Turbo, and Multilingual models — it has lower latency and a fuller set of voice controls. Use ElevenLabsDialogueTTSService only when you need Eleven v3.
• Text-to-Dialogue access: ElevenLabsDialogueTTSService requires workspace access to ElevenLabs’ Text-to-Dialogue WebSocket API.
• Audio tags: Eleven v3 performs inline audio tags such as [laughs] and [excited]. They come back as spoken characters in the alignment, so they reach the LLM context as text unless a text filter removes them.
• Set a voice up front: Text-to-Dialogue rejects keepalives that don’t name a registered context. If no voice is set when the service connects, the connection idles out after 20 seconds.
• Pronunciation dictionaries: The pronunciation_dictionary_locators parameter is deprecated as of v1.6.0. Use the text_transforms parameter with replace_text instead. Pronunciation dictionary substitutions can rewrite the spoken words in ways that no longer match the text sent to synthesis, which breaks the alignment-based word-completion tracking. Client-side replace_text transforms are tracked correctly and maintain word timestamp accuracy.

Event Handlers

ElevenLabs TTS supports the standard service connection events:

Event	Description
on_connected	Connected to ElevenLabs WebSocket
on_disconnected	Disconnected from ElevenLabs WebSocket
on_connection_error	WebSocket connection error occurred

@tts.event_handler("on_connected")
async def on_connected(service):
    print("Connected to ElevenLabs")