Python SDK reference

This page documents the public API for the Speech Engine Python SDK (elevenlabs).

Retrieve a SpeechEngineResource by its engine ID. The returned object provides methods to start a server, verify requests, or create individual sessions.

from elevenlabs import AsyncElevenLabs

elevenlabs = AsyncElevenLabs()
engine = await elevenlabs.speech_engine.get("seng_8k3m9xr4hjnfg983brhmhkd98n6")

Start a standalone WebSocket server. Blocks until stopped.

await engine.serve(
    port=3001,
    path="/ws",
    debug=True,
    on_transcript=handle_transcript,
)

By default serve() verifies the X-Elevenlabs-Speech-Engine-Authorization header on every incoming connection. If your server sits behind an infrastructure layer that already restricts incoming traffic to ElevenLabs (typically an IP allowlist scoped to ElevenLabs' egress ranges), you can skip JWT verification by passing disable_auth=True:

# No api_key required when disable_auth is True
await engine.serve(port=3001, disable_auth=True, on_transcript=on_transcript)

# Or directly on SpeechEngineServer
from elevenlabs.speech_engine import SpeechEngineServer

server = SpeechEngineServer(port=3001, disable_auth=True, on_transcript=on_transcript)
await server.serve()

When auth is disabled the server accepts any client that can reach it and emits a UserWarning on startup.

Verify that an incoming request originates from the ElevenLabs Speech Engine API. Checks the X-Elevenlabs-Speech-Engine-Authorization header for a valid JWT signed with the SHA-256 hash of your API key.

Only needed when managing the WebSocket upgrade yourself. When using serve(), verification is handled automatically (unless disable_auth=True was set).

is_valid = engine.verify_request(headers)

Returns: bool — True if the request is valid.

Wrap an accepted WebSocket in a SpeechEngineSession. Use this for custom server integration (e.g. FastAPI, Starlette, or manual WebSocket handling).

session = engine.create_session(websocket, debug=True)
session.on("user_transcript", handle_transcript)
await session.run()

Returns: SpeechEngineSession

Wraps a single WebSocket connection. Each connection represents one conversation. The session emits events for transcripts and lifecycle changes, and provides methods to send LLM responses back.

When a new transcript arrives, the previous transcript handler is cancelled automatically, interrupting any in-flight LLM call.

Register a handler for an event. Returns the session for chaining.

session.on("user_transcript", handler)

Remove a previously registered handler.

session.off("user_transcript", handler)

Register a handler that fires once then removes itself.

session.once("init", handler)

Send an LLM response back to the Speech Engine API for text-to-speech synthesis. Must be called inside an on_transcript handler. Calling it outside of a handler emits a warning and returns without sending.

# String response
await session.send_response("Hello, how can I help?")

# Streamed response (OpenAI, Anthropic, or Gemini)
stream = await openai_client.responses.create(model="gpt-4o", input=messages, stream=True)
await session.send_response(stream)

The SDK auto-detects and extracts text from the following LLM stream formats:

Run the receive loop until the WebSocket closes. This is the main entry point after constructing a session manually via create_session().

session = engine.create_session(websocket)
session.on("user_transcript", handle_transcript)
await session.run()

Close the session and the underlying WebSocket connection.

session.close()

The keyword arguments passed to serve(). All callbacks are optional. Handlers can be synchronous or asynchronous (coroutine) functions.

When using session.on() directly instead of callbacks, these are the event names and their handler signatures.

Event name constants are available for type-safe usage:

from elevenlabs.speech_engine import USER_TRANSCRIPT, INIT, CLOSE, DISCONNECTED, ERROR

session.on(USER_TRANSCRIPT, handle_transcript)

A single message in the conversation history. The full transcript is passed to on_transcript on every turn.

For reference, these are the JSON messages exchanged over the WebSocket connection. The SDK handles serialization and deserialization automatically.