ElevenLabs Python SDK

To integrate the Speech Engine into an existing web server instead of using the standalone serve() method, use engine.create_session(). This allows you to manage the WebSocket connection manually within your framework's routing.

from fastapi import FastAPI, WebSocket

app = FastAPI()
engine = ...  # SpeechEngineResource from await client.speech_engine.get(...)

@app.websocket("/api/speech-engine/ws")
async def speech_engine_ws(ws: WebSocket):
    await ws.accept()
    session = engine.create_session(ws, debug=True)
    session.on("user_transcript", handle_transcript)
    await session.run()

Use Conversation and DefaultAudioInterface to build real-time conversational AI agents. You can start a session with conversation.start_session() and end it with conversation.end_session().

from elevenlabs.client import ElevenLabs
from elevenlabs.conversational_ai.conversation import Conversation, ClientTools
from elevenlabs.conversational_ai.default_audio_interface import DefaultAudioInterface

elevenlabs = ElevenLabs(
  api_key="YOUR_API_KEY",
)

# Create audio interface for real-time audio input/output
audio_interface = DefaultAudioInterface()

# Create conversation
conversation = Conversation(
    client=elevenlabs,
    agent_id="your-agent-id",
    requires_auth=True,
    audio_interface=audio_interface,
)

# Start the conversation
conversation.start_session()

# The conversation runs in background until you call:
conversation.end_session()

Install the official ElevenLabs Python library using pip.

pip install elevenlabs

By default, engine.serve() and SpeechEngineServer verify the X-Elevenlabs-Speech-Engine-Authorization header using the API key from your AsyncElevenLabs client or the ELEVENLABS_API_KEY environment variable.

Disabling Authentication: If your server is protected by an IP allowlist (e.g., restricting traffic to ElevenLabs' egress ranges), you can disable JWT verification by passing disable_auth=True.

Warning: Only disable authentication if you have network-level restrictions in place. Without them, anyone can access your server and consume your LLM/compute quota.

# Via engine.serve()
await engine.serve(port=3001, disable_auth=True, on_transcript=on_transcript)

# Or directly on SpeechEngineServer
server = SpeechEngineServer(port=3001, disable_auth=True, on_transcript=on_transcript)
await server.serve()

Use AsyncElevenLabs to perform environment variable operations in an asynchronous event loop. The methods list, create, get, and update are all async and must be awaited.

import asyncio
from elevenlabs import AsyncElevenLabs
from elevenlabs.environment_variables import (
    EnvironmentVariablesCreateRequestBody_String,
)

client = AsyncElevenLabs(
    api_key="YOUR_API_KEY",
)

async def main() -> None:
    # Example: List
    await client.environment_variables.list(
        cursor="cursor",
        page_size=1,
        label="label",
        environment="environment",
        type="string",
    )
    
    # Example: Create
    await client.environment_variables.create(
        request=EnvironmentVariablesCreateRequestBody_String(
            label="label",
            values={"key": "value"},
        ),
    )

asyncio.run(main())

The methods simulate_conversation and simulate_conversation_stream are deprecated.

To create and run simulations, use the following endpoints instead:

• /v1/convai/agent-testing/create
• /v1/convai/agents/:agent_id/run-tests

Use elevenlabs.text_to_speech.stream() to generate audio as a stream. You can either play the stream locally using the stream() function or iterate through the audio_stream to process raw audio bytes manually.

from elevenlabs import stream
from elevenlabs.client import ElevenLabs

elevenlabs = ElevenLabs(
  api_key="YOUR_API_KEY",
)

audio_stream = elevenlabs.text_to_speech.stream(
    text="This is a test",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    model_id="eleven_multilingual_v2"
)

# option 1: play the streamed audio locally
stream(audio_stream)

# option 2: process the audio bytes manually
for chunk in audio_stream:
    if isinstance(chunk, bytes):
        print(chunk)

Use client.voices.samples.audio.get to return the audio bytes corresponding to a sample attached to a voice. This returns an iterator of bytes.

from elevenlabs import ElevenLabs
from elevenlabs.environment import ElevenLabsEnvironment

client = ElevenLabs(
    environment=ElevenLabsEnvironment.PRODUCTION,
)

client.voices.samples.audio.get(
    voice_id="voice_id",
    sample_id="sample_id",
)

Remove an existing role from a user, group, or service account API key for a workspace resource. You must have admin access to the resource. Note that you cannot remove permissions from the user who originally created the resource.

from elevenlabs import ElevenLabs
from elevenlabs.environment import ElevenLabsEnvironment

client = ElevenLabs(
    environment=ElevenLabsEnvironment.PRODUCTION,
)

client.workspace.resources.unshare(
    resource_id="resource_id",
    resource_type="voice",
)