ElevenLabs Python SDK

Warnings

• breaking Version 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.
  Fix: Refer to the official v2 upgrade guide and documentation for updated method names and API usage patterns.
• gotcha Directly 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.
  Fix: Always 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.
• gotcha The `play()` function, used to play audio directly, requires the optional `pyaudio` dependency. If not installed, calling `play()` will result in an error or silence.
  Fix: Install the library with the `pyaudio` extra: `pip install elevenlabs[pyaudio]`.
• deprecated The top-level `generate` function (e.g., `from elevenlabs import generate`) has been removed or deprecated. Attempts to import or use it will fail.
  Fix: Use the client's specific methods, such as `client.text_to_speech.convert()`, for generating audio.
• gotcha Frequent 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.
  Fix: Be 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.
• gotcha Exceeding character quotas, concurrency limits, or using an invalid API key are common reasons for API errors (e.g., HTTP 400, 401, 429).
  Fix: Verify 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.
• gotcha Prior 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.
  Fix: Upgrade 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.

Install

• pip install elevenlabs Core library
• pip install elevenlabs[pyaudio] With audio playback support (PyAudio)

Imports

• ElevenLabs

  from elevenlabs.client import ElevenLabs

• play

  from elevenlabs.play import play

  Used for playing generated audio directly, requires `pyaudio` extra.
• generate
  The top-level `generate` function has been removed or deprecated; use `client.text_to_speech.convert` instead.

Quickstart

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.")