Implementation:Elevenlabs Elevenlabs python Package Exports

Field	Value
sources	src/elevenlabs/__init__.py
domains	Package Initialization, Lazy Loading, Public API Surface, Type Re-exports
last_updated	2026-02-15

Overview

The Package Exports module (__init__.py) serves as the public API surface for the elevenlabs Python package. At 5,103 lines, it is an auto-generated file (produced by Fern) that re-exports all public types, error classes, client classes, submodules, and utility functions from the SDK.

The module uses a lazy-loading pattern via Python's __getattr__ module-level hook and a _dynamic_imports dictionary to defer imports until attributes are actually accessed. This avoids loading the entire SDK into memory at import time. Static type checkers see the full set of imports via a typing.TYPE_CHECKING guard block.

Key features:

• Lazy loading - Attributes are resolved on first access via __getattr__ and importlib.import_module.
• Recursion limit guard - Sets sys.setrecursionlimit(5000) if the current limit is below that threshold, preventing stack overflow during deep import chains.
• Comprehensive __all__ - Defines approximately 1,685 public symbols for explicit export control.
• Type-checking imports - Full static imports are provided under if typing.TYPE_CHECKING: for IDE support and mypy compatibility.

Typical usage:

from elevenlabs import ElevenLabs, AsyncElevenLabs
from elevenlabs import play, save, stream
from elevenlabs import __version__
from elevenlabs import ElevenLabsEnvironment

Code Reference

Source file: src/elevenlabs/__init__.py (5,103 lines)

Module Structure

The file is organized into the following sections:

Section	Lines (approx.)	Description
Preamble	1 - 10	Auto-generation comment, imports of sys, typing, importlib; recursion limit guard
TYPE_CHECKING imports	11 - 1,708	Full static imports for type checkers (types, errors, clients, submodules, utilities)
_dynamic_imports dictionary	1,709 - 3,394	Maps ~1,685 attribute names to their source module paths for lazy loading
__getattr__ function	3,397 - 3,410	Module-level attribute hook that resolves lazy imports at runtime
__dir__ function	3,413 - 3,415	Returns sorted list of all lazy-loadable attribute names for introspection
__all__ list	3,418 - 5,103	Comprehensive list of all public symbols exported by the package

Lazy Loading Mechanism

_dynamic_imports: typing.Dict[str, str] = {
    "AddChapterResponseModel": ".types",
    "ElevenLabs": ".client",
    "AsyncElevenLabs": ".client",
    "ElevenLabsEnvironment": ".environment",
    "BadRequestError": ".errors",
    "play": ".play",
    "save": ".play",
    "stream": ".play",
    "__version__": ".version",
    # ... ~1,685 total entries
}

def __getattr__(attr_name: str) -> typing.Any:
    module_name = _dynamic_imports.get(attr_name)
    if module_name is None:
        raise AttributeError(f"No {attr_name} found in _dynamic_imports for module name -> {__name__}")
    try:
        module = import_module(module_name, __package__)
        if module_name == f".{attr_name}":
            return module
        else:
            return getattr(module, attr_name)
    except ImportError as e:
        raise ImportError(f"Failed to import {attr_name} from {module_name}: {e}") from e
    except AttributeError as e:
        raise AttributeError(f"Failed to get {attr_name} from {module_name}: {e}") from e

When module_name == f".{attr_name}", the attribute is a submodule and the module itself is returned. Otherwise, the named attribute is extracted from the imported module via getattr.

Import statement

import elevenlabs
# or
from elevenlabs import ElevenLabs, AsyncElevenLabs

I/O Contract

This module does not define callable functions with traditional I/O contracts. Instead, it acts as a namespace aggregator that re-exports symbols from sub-packages. The key exported categories are documented below.

Exported Client Classes

Symbol	Source Module	Description
ElevenLabs	.client	Main synchronous SDK client
AsyncElevenLabs	.client	Main asynchronous SDK client
ElevenLabsEnvironment	.environment	Environment configuration (base URLs)

Exported Error Classes

Symbol	Source Module	Description
BadRequestError	.errors	HTTP 400 error
UnauthorizedError	.errors	HTTP 401 error
ForbiddenError	.errors	HTTP 403 error
NotFoundError	.errors	HTTP 404 error
ConflictError	.errors	HTTP 409 error
TooEarlyError	.errors	HTTP 425 error
UnprocessableEntityError	.errors	HTTP 422 error

Exported Utility Functions

Symbol	Source Module	Description
play	.play	Play audio bytes through the system audio output
save	.play	Save audio bytes to a file
stream	.play	Stream audio bytes for playback
__version__	.version	Package version string

Exported Submodules

Submodule	Description
audio_isolation	Audio isolation/background removal
audio_native	Audio Native project creation
conversational_ai	Conversational AI agent management
dubbing	Audio/video dubbing
forced_alignment	Forced alignment of audio and text
history	Generation history retrieval
models	Model listing and information
music	Music generation and composition
pronunciation_dictionaries	Custom pronunciation dictionary management
samples	Voice sample management
service_accounts	Workspace service account management
speech_to_speech	Voice conversion (speech-to-speech)
speech_to_text	Speech transcription
studio	Studio projects and podcasts
text_to_dialogue	Multi-voice dialogue generation
text_to_sound_effects	Sound effects generation
text_to_speech	Text-to-speech synthesis
text_to_voice	Voice design from text descriptions
tokens	Token management
usage	Usage statistics
user	User account information
voices	Voice library management
webhooks	Webhook management and verification
workspace	Workspace and team management
v_1_speech_to_text_realtime	Real-time speech-to-text WebSocket
v_1_text_to_speech_voice_id_multi_stream_input	Multi-stream TTS WebSocket input
v_1_text_to_speech_voice_id_stream_input	Single-stream TTS WebSocket input

Exported Realtime Types

Symbol	Source Module	Description
AudioFormat	.realtime	Audio format configuration for realtime connections
CommitStrategy	.realtime	Strategy for committing text chunks in realtime TTS
RealtimeAudioOptions	.realtime	Audio options for realtime sessions
RealtimeConnection	.realtime	WebSocket connection wrapper for realtime API
RealtimeEvents	.realtime	Event types received from realtime sessions
RealtimeUrlOptions	.realtime	URL configuration for realtime endpoints

Exported Type Models (Summary)

The module exports approximately 1,580+ type model classes from .types, covering the full API surface including:

• Agent configuration types - AgentConfig, AgentMetadata, AgentBranchResponse, etc.
• Voice types - VoiceResponse, VoiceSettings, VoiceVerificationResponse, etc.
• Audio types - AllowedOutputFormats, AudioOutput, AudioFormat, etc.
• Conversation types - ConversationHistoryMetadataOutput, ConversationConfig, etc.
• Workflow types - AgentWorkflowRequestModel, WorkflowToolNodeModelInput, etc.
• AST expression types - AstAndOperatorNodeInput, AstEqualsOperatorNodeInput, etc.
• Workspace types - WorkspaceApiKeyResponseModel, WorkspaceGroupByNameResponseModel, etc.

Usage Examples

Basic Client Initialization

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="your_api_key")

Async Client Initialization

from elevenlabs import AsyncElevenLabs

client = AsyncElevenLabs(api_key="your_api_key")

Using Utility Functions

from elevenlabs import ElevenLabs, play, save, stream

client = ElevenLabs(api_key="your_api_key")
audio = client.text_to_speech.convert(
    voice_id="voice_abc123",
    text="Hello, world!",
)

# Play audio through speakers
play(audio)

# Save audio to file
save(audio, "output.mp3")

# Stream audio for playback
stream(audio)

Importing Specific Types

from elevenlabs import (
    VoiceSettings,
    ElevenLabsEnvironment,
    BadRequestError,
    AllowedOutputFormats,
)

Checking Package Version

from elevenlabs import __version__
print(f"ElevenLabs SDK version: {__version__}")

Using Custom Environment

from elevenlabs import ElevenLabs, ElevenLabsEnvironment

client = ElevenLabs(
    api_key="your_api_key",
    environment=ElevenLabsEnvironment.PRODUCTION,
)

Related Pages

• Elevenlabs_Elevenlabs_python_MusicCustomClient - Custom music client (composed into the main client via the music submodule)
• Elevenlabs_Elevenlabs_python_WebhookSignatureVerification - Webhook verification (composed into the main client via the webhooks submodule)
• Elevenlabs_Elevenlabs_python_RawBaseClient - Low-level raw HTTP client providing raw response access