ElevenLabs Text-to-Speech

​

Overview

• 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 serves the Eleven v3 and v4 dialogue models (eleven_v3, eleven_v3_conversational, eleven_v4_turbo). The default model is eleven_v4_turbo. These models support inline audio tags. Requires workspace access to the Text-to-Dialogue API.

​

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

export ELEVENLABS_API_KEY=your_api_key

​

Configuration

​

ElevenLabsTTSService

​

ElevenLabsHttpTTSService

​

ElevenLabsDialogueTTSService

​

Settings

​

Text-to-Dialogue settings

​

Usage

​

Basic Setup

import os

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

from pipecat.transcriptions.language import Language

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

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 and v4)

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_v4_turbo",
        stability=0.5,
    ),
)

​

Notes

• Models that accept language: Six models take a language code — eleven_flash_v2_5 and eleven_turbo_v2_5 cover 32 languages; eleven_v3 and eleven_v3_conversational cover 74; and eleven_v4 and eleven_v4_turbo cover 84 (adding Asturian, Burmese, Cantonese, Māori, Maltese, Mongolian, Occitan, Odia, Tajik, and Uzbek to the v3 set). 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: Both services report word-level timestamps. The WebSocket service keeps one connection open and streams text into it, making it better for interactive conversations. The HTTP service makes a separate request for each piece of text.
• 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 v2.5, and Multilingual models — it has a fuller set of voice controls. Use ElevenLabsDialogueTTSService for Eleven v3 and v4 dialogue models.
• Text-to-Dialogue access: ElevenLabsDialogueTTSService requires workspace access to ElevenLabs’ Text-to-Dialogue WebSocket API.
• Audio tags: Eleven v3 and v4 perform 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.
• Pronunciation hints: ElevenLabsTTSService and ElevenLabsHttpTTSService support SSML <phoneme> tags on v2 models (eleven_flash_v2, eleven_turbo_v2) only. The WebSocket service requires enable_ssml_parsing=True; the HTTP service always reads SSML. ElevenLabsDialogueTTSService (v3 models) reads IPA between slashes instead of SSML tags.

​

Event Handlers

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