Python SDK — ElevenLabs Documentation

Installation

Install the elevenlabs Python package in your project:

$ pip install elevenlabs
> # or
> poetry add elevenlabs

If you want to use the default implementation of audio input/output you will also need the pyaudio extra:

$ pip install "elevenlabs[pyaudio]"
> # or
> poetry add "elevenlabs[pyaudio]"

The pyaudio package installation might require additional system dependencies.

See PyAudio package README for more information.

Linux

macOS

On Debian-based systems you can install the dependencies with:

$ sudo apt install portaudio19

Usage

In this example we will create a simple script that runs a conversation with the ElevenLabs Conversational AI agent. You can find the full code in the ElevenLabs examples repository.

First import the necessary dependencies:

1 import os
2 import signal
3 
4 from elevenlabs.client import ElevenLabs
5 from elevenlabs.conversational_ai.conversation import Conversation
6 from elevenlabs.conversational_ai.default_audio_interface import DefaultAudioInterface

Next load the agent ID and API key from environment variables:

1 agent_id = os.getenv("AGENT_ID")
2 api_key = os.getenv("ELEVENLABS_API_KEY")

The API key is only required for non-public agents that have authentication enabled. You don’t have to set it for public agents and the code will work fine without it.

Then create the ElevenLabs client instance:

1 client = ElevenLabs(api_key=API_KEY)

Now we initialize the Conversation instance:

1 conversation = Conversation(
2     # API client and agent ID.
3     client,
4     AGENT_ID,
5 
6     # Assume auth is required when API_KEY is set.
7     requires_auth=bool(API_KEY),
8 
9     # Use the default audio interface.
10     audio_interface=DefaultAudioInterface(),
11 
12     # Simple callbacks that print the conversation to the console.
13     callback_agent_response=lambda response: print(f"Agent: {response}"),
14     callback_agent_response_correction=lambda original, corrected: print(f"Agent: {original} -> {corrected}"),
15     callback_user_transcript=lambda transcript: print(f"User: {transcript}"),
16 
17     # Uncomment if you want to see latency measurements.
18     # callback_latency_measurement=lambda latency: print(f"Latency: {latency}ms"),
19 )

We are using the DefaultAudioInterface which uses the default system audio input/output devices for the conversation. You can also implement your own audio interface by subclassing elevenlabs.conversational_ai.conversation.AudioInterface.

Now we can start the conversation:

1 conversation.start_session()

To get a clean shutdown when the user presses Ctrl+C we can add a signal handler which will call end_session():

1 signal.signal(signal.SIGINT, lambda sig, frame: conversation.end_session())

And lastly we wait for the conversation to end and print out the conversation ID (which can be used for reviewing the conversation history and debugging):

1 conversation_id = conversation.wait_for_session_end()
2 print(f"Conversation ID: {conversation_id}")

All that is left is to run the script and start talking to the agent:

$ # For public agents:
> AGENT_ID=youragentid python demo.py
> 
> # For private agents:
> AGENT_ID=youragentid ELEVENLABS_API_KEY=yourapikey python demo.py

$	pip install "elevenlabs[pyaudio]"
>	# or
>	poetry add "elevenlabs[pyaudio]"

1	import os
2	import signal
3
4	from elevenlabs.client import ElevenLabs
5	from elevenlabs.conversational_ai.conversation import Conversation
6	from elevenlabs.conversational_ai.default_audio_interface import DefaultAudioInterface

1	agent_id = os.getenv("AGENT_ID")
2	api_key = os.getenv("ELEVENLABS_API_KEY")

1	conversation = Conversation(
2	# API client and agent ID.
3	client,
4	AGENT_ID,
5
6	# Assume auth is required when API_KEY is set.
7	requires_auth=bool(API_KEY),
8
9	# Use the default audio interface.
10	audio_interface=DefaultAudioInterface(),
11
12	# Simple callbacks that print the conversation to the console.
13	callback_agent_response=lambda response: print(f"Agent: {response}"),
14	callback_agent_response_correction=lambda original, corrected: print(f"Agent: {original} -> {corrected}"),
15	callback_user_transcript=lambda transcript: print(f"User: {transcript}"),
16
17	# Uncomment if you want to see latency measurements.
18	# callback_latency_measurement=lambda latency: print(f"Latency: {latency}ms"),
19	)

1	conversation_id = conversation.wait_for_session_end()
2	print(f"Conversation ID: {conversation_id}")

$	# For public agents:
>	AGENT_ID=youragentid python demo.py
>
>	# For private agents:
>	AGENT_ID=youragentid ELEVENLABS_API_KEY=yourapikey python demo.py