{"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":"python","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":"Before 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]`.","message":"The `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.","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,"search_vec":"'activ':52 'advanc':21 'ai':22,48,75,89 'api':16,72 'applic':27 'audio':76 'capabl':24 'chang':74 'client':11 'clone':41 'convers':47,88 'develop':18 'driven':64 'elevenlab':1,5,15 'enabl':17 'featur':34 'fern':66 'frequent':56 'generat':83 'includ':35 'integr':20 'latest':71 'librari':12,50 'maintain':53 'multipl':59 'offici':10 'often':58 'python':2,6 'rang':32 'reflect':69 'regener':67 'releas':57 'schema':73 'sdk':3,7 'speech':39,43,80,85 'speech-to-text':42,84 'support':29 'text':37,45,78,87 'text-to-speech':36,77 'time':60 'tts':81 'typic':63 'voic':23,40,82 'week':62 'wide':31","created_at":"2026-04-09T03:49:22.321105+00:00","updated_at":"2026-04-16T14:48:11.150789+00:00","problems":[{"fix":"Ensure 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')`.","cause":"This error occurs when the ElevenLabs API key provided is incorrect, expired, or has insufficient permissions, leading to unauthorized access.","error":"ApiError: status_code: 401, body: {'detail': {'status': 'invalid_api_key', 'message': 'Invalid API key.'}}"},{"fix":"Initialize 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='...')`.","cause":"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.","error":"AttributeError: module 'elevenlabs' has no attribute 'generate'"},{"fix":"Update your `elevenlabs` library to the latest version using `pip install --upgrade elevenlabs` to ensure the `client` submodule is available for import.","cause":"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.","error":"ModuleNotFoundError: No module named 'elevenlabs.client'"},{"fix":"Verify 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.","cause":"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.","error":"ApiError: status_code: 400, body: {'detail': {'status': 'voice_not_found', 'message': 'A voice for the voice_id XXXXXXXX was not found.'}}"},{"fix":"Reduce 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.","cause":"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.","error":"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.'}}"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.52.0","cli_name":"elevenlabs","cli_version":"sh: 1: elevenlabs: not found","type":"library","homepage":"https://elevenlabs.io","github":"https://github.com/elevenlabs/elevenlabs-python","docs":null,"changelog":null,"pypi":"https://pypi.org/project/elevenlabs/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["llm-agents","ai-ml"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":"verified"}}