Loading repository data…
elevenlabs / repository
The official Python SDK for the ElevenLabs API.
The official Python SDK for ElevenLabs. ElevenLabs brings the most compelling, rich and lifelike voices to creators and developers in just a few lines of code.
Check out the HTTP API documentation.
pip install elevenlabs
Eleven v3 (eleven_v3)
Eleven Multilingual v2 (eleven_multilingual_v2)
Eleven Flash v2.5 (eleven_flash_v2_5)
Eleven Turbo v2.5 (eleven_turbo_v2_5)
For more detailed information about these models and others, visit the ElevenLabs Models documentation.
from dotenv import load_dotenv
from elevenlabs.client import ElevenLabs
from elevenlabs.play import play
load_dotenv()
elevenlabs = ElevenLabs()
audio = elevenlabs.text_to_speech.convert(
text="The first move is what sets everything in motion.",
voice_id="JBFqnCBsd6RMkjVDRZzb",
model_id="eleven_v3",
output_format="mp3_44100_128",
)
play(audio)
🎧 Try it out! Want to hear our voices in action? Visit the ElevenLabs Voice Lab to experiment with different voices, languages, and settings.
List all your available voices with search().
from elevenlabs.client import ElevenLabs
elevenlabs = ElevenLabs(
api_key="YOUR_API_KEY",
)
response = elevenlabs.voices.search()
print(response.voices)
For information about the structure of the voices output, please refer to the official ElevenLabs API documentation for Get Voices.
Build a voice object with custom settings to personalize the voice style, or call
elevenlabs.voices.settings.get("your-voice-id") to get the default settings for the voice.
Clone your voice in an instant. Note that voice cloning requires an API key, see below.
from elevenlabs.client import ElevenLabs
from elevenlabs.play import play
elevenlabs = ElevenLabs(
api_key="YOUR_API_KEY",
)
voice = elevenlabs.voices.ivc.create(
name="Alex",
description="An old American male voice with a slight hoarseness in his throat. Perfect for news", # Optional
files=["./sample_0.mp3", "./sample_1.mp3", "./sample_2.mp3"],
)
Stream audio in real-time, as it's being generated.
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 AsyncElevenLabs if you want to make API calls asynchronously.
import asyncio
from elevenlabs.client import AsyncElevenLabs
elevenlabs = AsyncElevenLabs(
api_key="MY_API_KEY"
)
async def print_models() -> None:
models = await elevenlabs.models.list()
print(models)
asyncio.run(print_models())
Build interactive AI agents with real-time audio capabilities using ElevenAgents.
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()
For advanced use cases involving context propagation, resource reuse, or specific event loop management, ClientTools supports custom asyncio event loops:
import asyncio
from elevenlabs.conversational_ai.conversation import ClientTools
elevenlabs = ElevenLabs(
api_key="YOUR_API_KEY",
)
async def main():
# Get the current event loop
custom_loop = asyncio.get_running_loop()
# Create ClientTools with custom loop to prevent "different event loop" errors
client_tools = ClientTools(loop=custom_loop)
# Register your tools
async def get_weather(params):
location = params.get("location", "Unknown")
# Your async logic here
return f"Weather in {location}: Sunny, 72°F"
client_tools.register("get_weather", get_weather, is_async=True)
# Use with conversation
conversation = Conversation(
client=elevenlabs,
agent_id="your-agent-id",
requires_auth=True,
audio_interface=audio_interface,
client_tools=client_tools
)
asyncio.run(main())
Benefits of Custom Event Loop:
Important: When using a custom loop, you're responsible for its lifecycle Don't close the loop while ClientTools are still using it.
Register custom tools that the AI agent can call during conversations:
client_tools = ClientTools()
# Sync tool
def calculate_sum(params):
numbers = params.get("numbers", [])
return sum(numbers)
# Async tool
async def fetch_data(params):
url = params.get("url")
# Your async HTTP request logic
return {"data": "fetched"}
client_tools.register("calculate_sum", calculate_sum, is_async=False)
client_tools.register("fetch_data", fetch_data, is_async=True)
Speech Engine lets you build server-side voice agents that receive real-time transcripts from the ElevenLabs API and stream LLM responses back for text-to-speech synthesis. Your server acts as a WebSocket endpoint — ElevenLabs connects to it, sends user transcripts, and your code decides how to respond.
Speech Engine is async-only and available on AsyncElevenLabs.
import asyncio
from openai import AsyncOpenAI
from elevenlabs import AsyncElevenLabs
openai_client = AsyncOpenAI()
elevenlabs = AsyncElevenLabs()
async def main():
engine = await elevenlabs.speech_engine.get("seng_123")
async def on_transcript(transcript, session):
stream = await openai_client.responses.create(
model="gpt-4o",
input=[
{"role": "assistant" if m.role == "agent" else m.role, "content": m.content}
for m in transcript
],
stream=True,
)
await session.send_response(stream)
async def on_init(conversation_id, session):
print(f"Session started: {conversation_id}")
async def on_close(session):
print(f"Session ended: {session.conversation_id}")
async def on_error(err, session):
print(f"Error: {err}")
await engine.serve(
port=3001,
debug=True,
on_init=on_init,
on_transcript=on_transcript,
on_close=on_close,
on_error=on_error,
)
asyncio.run(main())
When engine.serve() starts, it opens a WebSocket server on the specified port. For each incoming connection from the ElevenLabs API:
init message arrives with a conversation_iduser_transcript messages arrive with the full conversation historyon_transcript handler generates a response (using any LLM) and calls session.send_response()send_response() accepts strings or async iterators. LLM stream formats from OpenAI, Anthropic, and Google Gemini are auto-detected:
# Plain string
await session.send_response("Hello world")
# OpenAI stream (auto-parsed)
stream = await openai_client.responses.create(model="gpt-4o", ..., stream=True)
await session.send_response(stream)
# Anthropic stream (auto-parsed)
stream = anthropic_client.messages.stream(model="claude-sonnet-4-20250514", ...)
await session.send_response(stream)
# Any async iterator of strings
async def my_generator():
yield "Hello "
yield "world"
await session.send_response(my_generator())
When a new transcript arrives while a previous response is still streaming, the previous handler's asyncio.Task is cancelled automatically. Any await in your handler (including LLM SDK calls) will raise asyncio.CancelledError, which cleanly aborts the in-flight request. No manual signal handling needed.
For integrating with an existing web server, use create_session() instead of serve():
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()
When using session.on() directly, handlers receive just the event data (no session argument, since you already have the reference):
| Event | Handler signature |
|---|---|
"init" | async (conversation_id: str) -> None |
"user_transcript" | async (transcript: list[ConversationMessage]) -> None |
"close" | async () -> None |
"disconnected" | async () -> None |
"error" | async (error: Exception) -> None |
For full control over the server lifecycle, use SpeechEngineServer directly:
from elevenlabs.speech_engine import SpeechEngineServer
server = SpeechEngineServer(
port=3001,
debug=True,
on_transcript=handle_transcript,
)
# In one task:
await server.serve()
# In another task (e.g. signal handler):
await server.stop()
Both engine.serve() and `SpeechEngineS
Selected from shared topics, language and repository description—not editorial ratings.
MayBind /
Official SDK for the Maybind Digital Twin Platform — interact with AI twins via a powerful API.