{"id":1471,"library":"elevenlabs","title":"ElevenLabs Python SDK","description":"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.","status":"active","version":"2.42.0","language":"en","source_language":"en","source_url":"https://github.com/elevenlabs/elevenlabs-python","tags":["AI","audio","text-to-speech","TTS","voice generation","speech-to-text","conversational AI"],"install":[{"cmd":"pip install elevenlabs","lang":"bash","label":"Core library"},{"cmd":"pip install elevenlabs[pyaudio]","lang":"bash","label":"With audio playback support (PyAudio)"}],"dependencies":[{"reason":"HTTP client for API requests.","package":"httpx","optional":false},{"reason":"Data validation.","package":"pydantic","optional":false},{"reason":"Pydantic core functionality.","package":"pydantic-core","optional":false},{"reason":"HTTP library.","package":"requests","optional":false},{"reason":"Type hints support.","package":"typing_extensions","optional":false},{"reason":"WebSocket support for real-time features.","package":"websockets","optional":false},{"reason":"Required for the `elevenlabs.play.play()` function to output audio.","package":"pyaudio","optional":true},{"reason":"Recommended for loading API keys from .env files, though `os.environ` works directly.","package":"python-dotenv","optional":true}],"imports":[{"symbol":"ElevenLabs","correct":"from elevenlabs.client import ElevenLabs"},{"note":"Used for playing generated audio directly, requires `pyaudio` extra.","symbol":"play","correct":"from elevenlabs.play import play"},{"note":"The top-level `generate` function has been removed or deprecated; use `client.text_to_speech.convert` instead.","wrong":"from elevenlabs import generate","symbol":"generate"}],"quickstart":{"code":"import os\nfrom elevenlabs.client import ElevenLabs\nfrom elevenlabs.play import play\n\n# Initialize the client. It automatically picks up ELEVENLABS_API_KEY from environment variables.\n# You can also pass it explicitly: ElevenLabs(api_key=\"YOUR_API_KEY\")\nelevenlabs = ElevenLabs(api_key=os.environ.get(\"ELEVENLABS_API_KEY\", \"\"))\n\nif not elevenlabs.api_key:\n    print(\"Error: ELEVENLABS_API_KEY environment variable not set.\")\n    print(\"Please set your ElevenLabs API key before running this example.\")\nelse:\n    print(\"Generating speech...\")\n    try:\n        audio = elevenlabs.text_to_speech.convert(\n            text=\"The quick brown fox jumps over the lazy dog.\",\n            voice_id=\"21m00Tz activations\", # A common pre-made voice ID (e.g., 'Rachel')\n            model_id=\"eleven_v3\", # Recommended model, or \"eleven_multilingual_v2\", \"eleven_flash_v2.5\", etc.\n            output_format=\"mp3_44100_128\",\n        )\n        print(\"Speech generated. Playing audio (requires pyaudio installed)...\")\n        play(audio)\n        print(\"Audio played.\")\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n        print(\"Ensure 'elevenlabs[pyaudio]' is installed if you want to play audio directly.\")\n        print(\"Also check your API key and subscription plan for model/voice access.\")","lang":"python","description":"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."},"warnings":[{"fix":"Refer to the official v2 upgrade guide and documentation for updated method names and API usage patterns.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Install the library with the `pyaudio` extra: `pip install elevenlabs[pyaudio]`.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Use the client's specific methods, such as `client.text_to_speech.convert()`, for generating audio.","message":"The top-level `generate` function (e.g., `from elevenlabs import generate`) has been removed or deprecated. Attempts to import or use it will fail.","severity":"deprecated","affected_versions":"Likely >=2.0.0 (exact version unclear from sources)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions, especially with frequent updates"},{"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.","message":"Exceeding character quotas, concurrency limits, or using an invalid API key are common reasons for API errors (e.g., HTTP 400, 401, 429).","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<2.41.0"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}