Environment:Elevenlabs Elevenlabs python Python Websockets

Knowledge Sources	elevenlabs-python websockets documentation
Domains	Infrastructure, Realtime_Communication
Last Updated	2026-02-15 12:00 GMT

Overview

Python 3.8+ environment with the websockets library for ElevenLabs real-time streaming features.

Description

This environment provides WebSocket connectivity for all real-time streaming ElevenLabs SDK features. The SDK uses the websockets library (both sync via `websockets.sync.client.connect` and async via `websockets.asyncio.client.connect`) for bidirectional communication with the ElevenLabs API. This covers real-time text-to-speech streaming, conversational AI sessions, and real-time speech-to-text (Scribe).

Usage

Use this environment for any ElevenLabs SDK operation that requires WebSocket streaming. This includes `convert_realtime()` for real-time TTS, the `Conversation` / `AsyncConversation` classes for conversational AI, and `ScribeRealtime.connect()` for real-time speech-to-text. It is required alongside the HTTP environment for these features.

System Requirements

Category	Requirement	Notes
OS	Any (Windows, macOS, Linux)	Cross-platform support
Python	>= 3.8	Required by elevenlabs SDK
Network	WebSocket access to wss://api.elevenlabs.io	Persistent connection required; check firewall/proxy rules for WSS

Dependencies

Python Packages

`websockets` >= 11.0

Credentials

The following environment variables must be set:

`ELEVENLABS_API_KEY`: Required for WebSocket authentication. Passed as `xi-api-key` header on connection.

Quick Install

# Install the ElevenLabs SDK (includes websockets)
pip install elevenlabs

# Or install websockets manually
pip install websockets>=11.0

Code Evidence

Import and usage in `realtime_tts.py:7-9`:

import websockets
from websockets.sync.client import connect

Sync WebSocket connection for realtime TTS in `realtime_tts.py:94-107`:

with connect(
    urllib.parse.urljoin(
      self._ws_base_url,
      f"v1/text-to-speech/{jsonable_encoder(voice_id)}/stream-input?model_id={model_id}&output_format={output_format}"
    ),
    additional_headers=jsonable_encoder(...)
) as socket:

Import check with error message in `realtime/scribe.py:10-16`:

try:
    from websockets.asyncio.client import connect as websocket_connect
except ImportError:
    raise ImportError(
        "The websockets package is required for realtime speech-to-text. "
        "Install it with: pip install websockets"
    )

ConvAI WebSocket imports in `conversation.py:13-15`:

import websockets
from websockets.exceptions import ConnectionClosedOK
from websockets.sync.client import Connection, connect

Common Errors

Error Message	Cause	Solution
`ImportError: The websockets package is required`	websockets not installed	`pip install websockets>=11.0`
`websockets.exceptions.ConnectionClosedError`	Server rejected connection or network issue	Check API key, network connectivity, and WebSocket URL
`ConnectionRefusedError` on WSS	Firewall blocking WebSocket connections	Ensure WSS (port 443) traffic is allowed to api.elevenlabs.io

Compatibility Notes

Sync and Async: The SDK uses both `websockets.sync.client.connect` (for `Conversation`, `convert_realtime`) and `websockets.asyncio.client.connect` (for `AsyncConversation`, `ScribeRealtime`).
websockets >= 11.0: Required for the sync client API (`websockets.sync.client`), which was introduced in websockets 11.0.
URL scheme conversion: The SDK automatically converts `https://` base URLs to `wss://` for WebSocket connections.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment