v3 upgrade guide

Note: v3 is currently in prerelease. Details may change before the stable release.

v3 of the ElevenLabs Python SDK renames the ElevenAgents namespace, replaces the hand-written realtime clients with generated WebSocket clients for every realtime product, and removes long-deprecated endpoints.

Requirements

• Python ≥ 3.10 — 3.8 and 3.9 are no longer supported.
• Pydantic ≥ 2 — the Pydantic v1 compatibility layer is dropped.
• Install with pip install "elevenlabs>=3,<4" (or pip install --pre elevenlabs during the prerelease period).
• New optional aiohttp transport for the async client: pip install "elevenlabs[aiohttp]".

conversational_ai is now agents

The conversational_ai namespace is renamed to agents, matching the ElevenAgents product name. API URLs are unchanged (/v1/convai/*) — only the SDK surface moves. The former agents sub-resource is flattened onto the group, so agent CRUD loses one level:

Old	New
client.conversational_ai.agents.create	client.agents.create
client.conversational_ai.agents.get / .update / .delete / .list	client.agents.get / .update / .delete / .list
client.conversational_ai.agents.widget.get	client.agents.widget.get
client.conversational_ai.agents.link.get	client.agents.link.get
client.conversational_ai.conversations.*	client.agents.conversations.*
client.conversational_ai.knowledge_base.*	client.agents.knowledge_base.*
client.conversational_ai.tools.*	client.agents.tools.*
client.conversational_ai.tests.*	client.agents.tests.*
client.conversational_ai.phone_numbers.*	client.agents.phone_numbers.*
client.conversational_ai.batch_calls.*	client.agents.batch_calls.*
client.conversational_ai.mcp_servers.*	client.agents.mcp_servers.*
client.conversational_ai.llm_usage.calculate	client.agents.llm_usage.calculate
client.conversational_ai.agents.llm_usage.calculate	client.agents.agents.llm_usage.calculate (per-agent variant)

Every other client.conversational_ai.<x> path becomes client.agents.<x> the same way.

Import paths move too:

# Before
from elevenlabs.conversational_ai.conversation import Conversation, ClientTools
from elevenlabs.conversational_ai.default_audio_interface import DefaultAudioInterface

# After
from elevenlabs.agents.conversation import Conversation, ClientTools
from elevenlabs.agents.default_audio_interface import DefaultAudioInterface

If your tests patch module paths as strings (mock.patch("elevenlabs.conversational_ai.conversation...")), update those strings as well.

OnPremInitiationData is now OrchestratorConfig

Self-hosted (on-prem / in-VPC) conversation config is renamed to align with the @elevenlabs/client JS SDK:

• OnPremInitiationData → OrchestratorConfig
• Conversation(..., on_prem_config=...) → Conversation(..., orchestrator_config=...)
• on_prem_conversation_url= → url= (first positional parameter; must be ws:// or wss://)
• All other OrchestratorConfig fields are keyword-only.

# Before
from elevenlabs.conversational_ai.conversation import Conversation, OnPremInitiationData

conversation = Conversation(
    client, agent_id, requires_auth=False,
    on_prem_config=OnPremInitiationData(
        on_prem_conversation_url="wss://my-host/sagemaker/convai/conversation",
        agent_config_dict=config,
    ),
)

# After
from elevenlabs.agents.conversation import Conversation, OrchestratorConfig

conversation = Conversation(
    client, agent_id, requires_auth=False,
    orchestrator_config=OrchestratorConfig(
        "wss://my-host/sagemaker/convai/conversation",
        agent_config_dict=config,
    ),
)

The wire format (enclave_setup_config) is unchanged — no orchestrator-side changes needed.

Realtime speech-to-text: generated WebSocket client

The hand-written elevenlabs.realtime package is removed, along with its root re-exports (RealtimeConnection, RealtimeEvents, RealtimeAudioOptions, RealtimeUrlOptions, AudioFormat, CommitStrategy). client.speech_to_text.realtime(...) is now a generated context manager yielding a typed socket client — with full parameter coverage and, for the first time, an async variant.

Before:

connection = await client.speech_to_text.realtime.connect({
    "model_id": "scribe_v2_realtime",
    "audio_format": AudioFormat.PCM_16000,
    "sample_rate": 16000,
})
connection.on(RealtimeEvents.TRANSCRIPT, print)
await connection.send({"audio_base_64": chunk})

After:

from elevenlabs import InputAudioChunk

with client.speech_to_text.realtime(model_id="scribe_v2_realtime", audio_format="pcm_16000") as socket:
    socket.send_publish(InputAudioChunk(audio_base_64=chunk_base64))
    for message in socket:
        print(message)

# async
async with async_client.speech_to_text.realtime(model_id="scribe_v2_realtime") as socket:
    await socket.send_publish(InputAudioChunk(audio_base_64=chunk_base64))
    async for message in socket:
        print(message)

URL-based streaming (the v2 url option, which shelled out to ffmpeg) has no generated equivalent — stream the audio yourself and send chunks.

Realtime text-to-speech and other websockets

RealtimeTextToSpeechClient.convert_realtime(...) is removed. Every realtime product now has a generated websocket client with the same shape, on both the sync and async clients:

with client.text_to_speech.realtime(voice_id, model_id="eleven_flash_v2_5") as socket:
    ...

Dialogue, multi-context, and translation websockets have equivalent generated clients.

Removed endpoints

All endpoints that were marked deprecated in v2 are removed:

Removed	Replacement
client.voices.get_all	client.voices.search
client.text_to_voice.create_previews	client.text_to_voice.design
client.conversational_ai.add_to_knowledge_base	client.agents.knowledge_base.documents.create_from_file / _from_url / _from_text
client.conversational_ai.agents.simulate_conversation (+ _stream)	agent-testing endpoints (client.agents.tests.*)
client.conversational_ai.mcp_servers.approval_policy.update	client.agents.mcp_servers.update
client.usage.get	workspace analytics usage queries
client.dubbing.transcript.get	client.dubbing.transcripts.get
client.dubbing.resource.* (entire deprecated resource sub-API)	Dubbing Studio endpoints
cloud_storage_url parameter on client.speech_to_text.convert	source_url

Speech Engine internals

The public exports of elevenlabs.speech_engine are unchanged. The internal elevenlabs.speech_engine.types module is renamed to elevenlabs.speech_engine.session_types (the generated types/ package now occupies that name) — update any deep imports of WebSocketLike, ConversationMessage, or wrap_websocket.

Renamed request helper types

Per-endpoint request helper types are renamed verb-first, e.g.:

Old	New
ConversationsGetRequestFormat	GetConversationsRequestFormat
DocumentsUpdateResponse	UpdateDocumentsResponse

If an import breaks, search for the same words in verb-first order.