The `elevenlabs` Python SDK is the official client library for the ElevenLabs API, enabling developers to integrate advanced AI voice capabilities into their applications. It supports a wide range of features including text-to-speech, voice cloning, speech-to-text, and conversational AI. The library is actively maintained with very frequent releases (often multiple times a week), typically driven by 'Fern Regeneration' to reflect the latest API schema changes.
Install & Compatibility
Where this runs
tested against v2.52.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
6/12 runs
6/12 runs
py 3.11
6/12 runs
6/12 runs
py 3.12
6/12 runs
6/12 runs
py 3.13
6/12 runs
6/12 runs
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ElevenLabs
✓ from elevenlabs.client import ElevenLabs
play
✓ from elevenlabs.play import play
Used for playing generated audio directly, requires `pyaudio` extra.
generate
✓
✗ from elevenlabs import generate
The top-level `generate` function has been removed or deprecated; use `client.text_to_speech.convert` instead.
This quickstart demonstrates how to initialize the ElevenLabs client and convert text to speech. It automatically attempts to load the API key from the `ELEVENLABS_API_KEY` environment variable. The generated audio can be played directly using the `play` function, which requires the `pyaudio` optional dependency.
import os
from elevenlabs.client import ElevenLabs
from elevenlabs.play import play
# Initialize the client. It automatically picks up ELEVENLABS_API_KEY from environment variables.
# You can also pass it explicitly: ElevenLabs(api_key="YOUR_API_KEY")
elevenlabs = ElevenLabs(api_key=os.environ.get("ELEVENLABS_API_KEY", ""))
if not elevenlabs.api_key:
print("Error: ELEVENLABS_API_KEY environment variable not set.")
print("Please set your ElevenLabs API key before running this example.")
else:
print("Generating speech...")
try:
audio = elevenlabs.text_to_speech.convert(
text="The quick brown fox jumps over the lazy dog.",
voice_id="21m00Tz activations", # A common pre-made voice ID (e.g., 'Rachel')
model_id="eleven_v3", # Recommended model, or "eleven_multilingual_v2", "eleven_flash_v2.5", etc.
output_format="mp3_44100_128",
)
print("Speech generated. Playing audio (requires pyaudio installed)...")
play(audio)
print("Audio played.")
except Exception as e:
print(f"An error occurred: {e}")
print("Ensure 'elevenlabs[pyaudio]' is installed if you want to play audio directly.")
print("Also check your API key and subscription plan for model/voice access.")
elevenlabs --version
Debug
Known issues
breakingVersion 2 (v2) of the SDK introduced significant breaking changes, including renaming of many methods and simplification of the API surface. Code written for v1 will likely not work with v2 without modifications.fixRefer to the official v2 upgrade guide and documentation for updated method names and API usage patterns.
affects: >=2.0.0
gotchaDirectly embedding your ElevenLabs API key in source code is a significant security risk. Anyone with access to your code could use your key, potentially incurring unexpected costs or unauthorized access.fixAlways store your `ELEVENLABS_API_KEY` in environment variables (e.g., in a `.env` file and loaded with `python-dotenv`) or a secure secrets management system. The `ElevenLabs` client will automatically pick it up.
affects: All
gotchaThe `play()` function, used to play audio directly, requires the optional `pyaudio` dependency. Installation of `elevenlabs[pyaudio]` often fails due to missing system-level build tools (like a C compiler) and audio development headers (like PortAudio). Without `pyaudio`, calling `play()` will result in an error or silence, or the installation of the extra will fail.fixBefore installing `elevenlabs[pyaudio]`, ensure you have a C compiler (e.g., `gcc`) and the PortAudio development libraries installed on your system. For Alpine Linux (as used in this test), use `apk add portaudio-dev gcc`. For Debian/Ubuntu, use `sudo apt-get install portaudio19-dev gcc`. Then install with `pip install elevenlabs[pyaudio]`.
affects: All
deprecatedThe top-level `generate` function (e.g., `from elevenlabs import generate`) has been removed or deprecated. Attempts to import or use it will fail.fixUse the client's specific methods, such as `client.text_to_speech.convert()`, for generating audio.
affects: Likely >=2.0.0 (exact version unclear from sources)
gotchaFrequent API schema updates, often indicated by 'Fern Regeneration' in release notes, can introduce subtle breaking changes even in minor SDK versions if your code relies on specific response structures or optional parameters becoming required.fixBe prepared for occasional updates to parameter requirements or response structures. Follow the changelog closely and implement robust error handling (e.g., `try-except` blocks) and graceful degradation for unexpected API responses.
affects: All versions, especially with frequent updates
gotchaExceeding character quotas, concurrency limits, or using an invalid API key are common reasons for API errors (e.g., HTTP 400, 401, 429).fixVerify your API key is correct and active. Monitor your usage and subscription tier on the ElevenLabs dashboard to ensure you are within limits. Implement retry logic for transient rate limit errors.
affects: All
gotchaPrior to v2.41.0, the `audio_interface` parameter for `Conversation` class in `conversational_ai` might have been implicitly required or caused runtime errors in text-only chat modes.fixUpgrade to `elevenlabs` v2.41.0 or newer to ensure `audio_interface` is correctly handled as optional for text-only conversations. If using older versions, explicitly provide an `audio_interface` or ensure it's not omitted where expected.
affects: <2.41.0
Errors
Common errors & fixes
ApiError: status_code: 401, body: {'detail': {'status': 'invalid_api_key', 'message': 'Invalid API key.'}}
This error occurs when the ElevenLabs API key provided is incorrect, expired, or has insufficient permissions, leading to unauthorized access.
fixEnsure your `ELEVEN_API_KEY` environment variable is correctly set with a valid and active API key from your ElevenLabs account. You can also explicitly pass the API key when initializing the client: `client = ElevenLabs(api_key='YOUR_API_KEY')`.
AttributeError: module 'elevenlabs' has no attribute 'generate'
This error indicates that you are trying to call `generate` as a top-level function directly from the `elevenlabs` module, which is incorrect in newer versions of the SDK. The `generate` function is now a method of the `ElevenLabs` client object.
fixInitialize the `ElevenLabs` client and then call the `generate` method on the client instance: `from elevenlabs.client import ElevenLabs; client = ElevenLabs(); audio = client.generate(text='...', voice='...')`.
ModuleNotFoundError: No module named 'elevenlabs.client'
This error typically occurs when the `elevenlabs` package installed is an older version that does not expose the `client` submodule, or if there's a typo in the import statement.
fixUpdate your `elevenlabs` library to the latest version using `pip install --upgrade elevenlabs` to ensure the `client` submodule is available for import.
ApiError: status_code: 400, body: {'detail': {'status': 'voice_not_found', 'message': 'A voice for the voice_id XXXXXXXX was not found.'}}
This error happens when the provided `voice_id` does not correspond to an existing voice in your ElevenLabs account, or if your API key lacks the necessary permissions to access that specific voice. This can also occur if the API key is older and doesn't have access to newer voices or features.
fixVerify that the `voice_id` is correct and belongs to your account. You might need to generate a new API key from your ElevenLabs dashboard with the appropriate scopes, or use a voice that is publicly available or cloned within your account.
ApiError: status_code: 400, body: {'detail': {'status': 'max_character_limit_exceeded', 'message': 'This request\'s text has XXX characters and exceeds the character limit of XXX characters for non signed in accounts.'}}
This error occurs when the input text provided for text-to-speech generation exceeds the maximum character limit allowed by your ElevenLabs subscription plan or for the specific API endpoint.
fixReduce the length of the input text to be within the character limit specified in your ElevenLabs plan. For longer content, break the text into smaller segments and concatenate the generated audio.
Audit
Dependencies
httpxrequiredHTTP client for API requests.
pydanticrequiredData validation.
pydantic-corerequiredPydantic core functionality.
requestsrequiredHTTP library.
typing_extensionsrequiredType hints support.
websocketsrequiredWebSocket support for real-time features.
pyaudiooptionalRequired for the `elevenlabs.play.play()` function to output audio.
python-dotenvoptionalRecommended for loading API keys from .env files, though `os.environ` works directly.