| Name | elevenlabs JSON |
| Version |
2.20.1
JSON |
| download |
| home_page | None |
| Summary | None |
| upload_time | 2025-10-23 14:33:12 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <4.0,>=3.8 |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# ElevenLabs Python Library
[](https://buildwithfern.com/?utm_source=fern-elevenlabs/elevenlabs-python/readme)
[](https://discord.gg/elevenlabs)
[](https://twitter.com/elevenlabsio)
[](https://pypi.org/project/elevenlabs/)
[](https://pepy.tech/project/elevenlabs)
The official Python SDK for [ElevenLabs](https://elevenlabs.io/). ElevenLabs brings the most compelling, rich and lifelike voices to creators and developers in just a few lines of code.
## 📖 API & Docs
Check out the [HTTP API documentation](https://elevenlabs.io/docs/api-reference).
## Install
```bash
pip install elevenlabs
```
## Usage
### Main Models
1. **Eleven Multilingual v2** (`eleven_multilingual_v2`)
- Excels in stability, language diversity, and accent accuracy
- Supports 29 languages
- Recommended for most use cases
2. **Eleven Flash v2.5** (`eleven_flash_v2_5`)
- Ultra-low latency
- Supports 32 languages
- Faster model, 50% lower price per character
2. **Eleven Turbo v2.5** (`eleven_turbo_v2_5`)
- Good balance of quality and latency
- Ideal for developer use cases where speed is crucial
- Supports 32 languages
For more detailed information about these models and others, visit the [ElevenLabs Models documentation](https://elevenlabs.io/docs/models).
```py
from dotenv import load_dotenv
from elevenlabs.client import ElevenLabs
from elevenlabs.play import play
load_dotenv()
client = ElevenLabs()
audio = client.text_to_speech.convert(
text="The first move is what sets everything in motion.",
voice_id="JBFqnCBsd6RMkjVDRZzb",
model_id="eleven_multilingual_v2",
output_format="mp3_44100_128",
)
play(audio)
```
<details> <summary> Play </summary>
🎧 **Try it out!** Want to hear our voices in action? Visit the [ElevenLabs Voice Lab](https://elevenlabs.io/voice-lab) to experiment with different voices, languages, and settings.
</details>
## Voices
List all your available voices with `voices()`.
```py
from elevenlabs.client import ElevenLabs
client = ElevenLabs(
api_key="YOUR_API_KEY",
)
response = client.voices.search()
print(response.voices)
```
For information about the structure of the voices output, please refer to the [official ElevenLabs API documentation for Get Voices](https://elevenlabs.io/docs/api-reference/get-voices).
Build a voice object with custom settings to personalize the voice style, or call
`client.voices.get_settings("your-voice-id")` to get the default settings for the voice.
</details>
## Clone Voice
Clone your voice in an instant. Note that voice cloning requires an API key, see below.
```py
from elevenlabs.client import ElevenLabs
from elevenlabs.play import play
client = ElevenLabs(
api_key="YOUR_API_KEY",
)
voice = client.voices.ivc.create(
name="Alex",
description="An old American male voice with a slight hoarseness in his throat. Perfect for news", # Optional
files=["./sample_0.mp3", "./sample_1.mp3", "./sample_2.mp3"],
)
```
## Streaming
Stream audio in real-time, as it's being generated.
```py
from elevenlabs import stream
from elevenlabs.client import ElevenLabs
client = ElevenLabs()
audio_stream = client.text_to_speech.stream(
text="This is a test",
voice_id="JBFqnCBsd6RMkjVDRZzb",
model_id="eleven_multilingual_v2"
)
#Â option 1: play the streamed audio locally
stream(audio_stream)
#Â option 2: process the audio bytes manually
for chunk in audio_stream:
if isinstance(chunk, bytes):
print(chunk)
```
## Async Client
Use `AsyncElevenLabs` if you want to make API calls asynchronously.
```python
import asyncio
from elevenlabs.client import AsyncElevenLabs
eleven = AsyncElevenLabs(
api_key="MY_API_KEY"
)
async def print_models() -> None:
models = await eleven.models.list()
print(models)
asyncio.run(print_models())
```
## Conversational AI
Build interactive AI agents with real-time audio capabilities using ElevenLabs Conversational AI.
### Basic Usage
```python
from elevenlabs.client import ElevenLabs
from elevenlabs.conversational_ai.conversation import Conversation, ClientTools
from elevenlabs.conversational_ai.default_audio_interface import DefaultAudioInterface
client = ElevenLabs(api_key="YOUR_API_KEY")
# Create audio interface for real-time audio input/output
audio_interface = DefaultAudioInterface()
# Create conversation
conversation = Conversation(
client=client,
agent_id="your-agent-id",
requires_auth=True,
audio_interface=audio_interface,
)
# Start the conversation
conversation.start_session()
# The conversation runs in background until you call:
conversation.end_session()
```
### Custom Event Loop Support
For advanced use cases involving context propagation, resource reuse, or specific event loop management, `ClientTools` supports custom asyncio event loops:
```python
import asyncio
from elevenlabs.conversational_ai.conversation import ClientTools
async def main():
# Get the current event loop
custom_loop = asyncio.get_running_loop()
# Create ClientTools with custom loop to prevent "different event loop" errors
client_tools = ClientTools(loop=custom_loop)
# Register your tools
async def get_weather(params):
location = params.get("location", "Unknown")
# Your async logic here
return f"Weather in {location}: Sunny, 72°F"
client_tools.register("get_weather", get_weather, is_async=True)
# Use with conversation
conversation = Conversation(
client=client,
agent_id="your-agent-id",
requires_auth=True,
audio_interface=audio_interface,
client_tools=client_tools
)
asyncio.run(main())
```
**Benefits of Custom Event Loop:**
- **Context Propagation**: Maintain request-scoped state across async operations
- **Resource Reuse**: Share existing async resources like HTTP sessions or database pools
- **Loop Management**: Prevent "Task got Future attached to a different event loop" errors
- **Performance**: Better control over async task scheduling and execution
**Important:** When using a custom loop, you're responsible for its lifecycle
Don't close the loop while ClientTools are still using it.
### Tool Registration
Register custom tools that the AI agent can call during conversations:
```python
client_tools = ClientTools()
# Sync tool
def calculate_sum(params):
numbers = params.get("numbers", [])
return sum(numbers)
# Async tool
async def fetch_data(params):
url = params.get("url")
# Your async HTTP request logic
return {"data": "fetched"}
client_tools.register("calculate_sum", calculate_sum, is_async=False)
client_tools.register("fetch_data", fetch_data, is_async=True)
```
## Languages Supported
Explore [all models & languages](https://elevenlabs.io/docs/models).
## Contributing
While we value open-source contributions to this SDK, this library is generated programmatically. Additions made directly to this library would have to be moved over to our generation code, otherwise they would be overwritten upon the next generated release. Feel free to open a PR as a proof of concept, but know that we will not be able to merge it as-is. We suggest opening an issue first to discuss with us!
On the other hand, contributions to the README are always very welcome!
Raw data
{
"_id": null,
"home_page": null,
"name": "elevenlabs",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/75/76/0b27ddb7aa9b323e807c991746710c9c105305a324fe6e2807c88db3e6ee/elevenlabs-2.20.1.tar.gz",
"platform": null,
"description": "# ElevenLabs Python Library\n\n\n\n[](https://buildwithfern.com/?utm_source=fern-elevenlabs/elevenlabs-python/readme)\n[](https://discord.gg/elevenlabs)\n[](https://twitter.com/elevenlabsio)\n[](https://pypi.org/project/elevenlabs/)\n[](https://pepy.tech/project/elevenlabs)\n\nThe official Python SDK for [ElevenLabs](https://elevenlabs.io/). ElevenLabs brings the most compelling, rich and lifelike voices to creators and developers in just a few lines of code.\n\n## \ud83d\udcd6 API & Docs\n\nCheck out the [HTTP API documentation](https://elevenlabs.io/docs/api-reference).\n\n## Install\n\n```bash\npip install elevenlabs\n```\n\n## Usage\n\n### Main Models\n\n1. **Eleven Multilingual v2** (`eleven_multilingual_v2`)\n\n - Excels in stability, language diversity, and accent accuracy\n - Supports 29 languages\n - Recommended for most use cases\n\n2. **Eleven Flash v2.5** (`eleven_flash_v2_5`)\n\n - Ultra-low latency\n - Supports 32 languages\n - Faster model, 50% lower price per character\n\n2. **Eleven Turbo v2.5** (`eleven_turbo_v2_5`)\n\n - Good balance of quality and latency\n - Ideal for developer use cases where speed is crucial\n - Supports 32 languages\n\nFor more detailed information about these models and others, visit the [ElevenLabs Models documentation](https://elevenlabs.io/docs/models).\n\n```py\nfrom dotenv import load_dotenv\nfrom elevenlabs.client import ElevenLabs\nfrom elevenlabs.play import play\n\nload_dotenv()\n\nclient = ElevenLabs()\n\naudio = client.text_to_speech.convert(\n text=\"The first move is what sets everything in motion.\",\n voice_id=\"JBFqnCBsd6RMkjVDRZzb\",\n model_id=\"eleven_multilingual_v2\",\n output_format=\"mp3_44100_128\",\n)\n\nplay(audio)\n```\n\n<details> <summary> Play </summary>\n\n\ud83c\udfa7 **Try it out!** Want to hear our voices in action? Visit the [ElevenLabs Voice Lab](https://elevenlabs.io/voice-lab) to experiment with different voices, languages, and settings.\n\n</details>\n\n## Voices\n\nList all your available voices with `voices()`.\n\n```py\nfrom elevenlabs.client import ElevenLabs\n\nclient = ElevenLabs(\n api_key=\"YOUR_API_KEY\",\n)\n\nresponse = client.voices.search()\nprint(response.voices)\n```\n\nFor information about the structure of the voices output, please refer to the [official ElevenLabs API documentation for Get Voices](https://elevenlabs.io/docs/api-reference/get-voices).\n\nBuild a voice object with custom settings to personalize the voice style, or call\n`client.voices.get_settings(\"your-voice-id\")` to get the default settings for the voice.\n\n</details>\n\n## Clone Voice\n\nClone your voice in an instant. Note that voice cloning requires an API key, see below.\n\n```py\nfrom elevenlabs.client import ElevenLabs\nfrom elevenlabs.play import play\n\nclient = ElevenLabs(\n api_key=\"YOUR_API_KEY\",\n)\n\nvoice = client.voices.ivc.create(\n name=\"Alex\",\n description=\"An old American male voice with a slight hoarseness in his throat. Perfect for news\", # Optional\n files=[\"./sample_0.mp3\", \"./sample_1.mp3\", \"./sample_2.mp3\"],\n)\n```\n\n## Streaming\n\nStream audio in real-time, as it's being generated.\n\n```py\nfrom elevenlabs import stream\nfrom elevenlabs.client import ElevenLabs\n\nclient = ElevenLabs()\n\naudio_stream = client.text_to_speech.stream(\n text=\"This is a test\",\n voice_id=\"JBFqnCBsd6RMkjVDRZzb\",\n model_id=\"eleven_multilingual_v2\"\n)\n\n#\u00a0option 1: play the streamed audio locally\nstream(audio_stream)\n\n#\u00a0option 2: process the audio bytes manually\nfor chunk in audio_stream:\n if isinstance(chunk, bytes):\n print(chunk)\n\n```\n\n## Async Client\n\nUse `AsyncElevenLabs` if you want to make API calls asynchronously.\n\n```python\nimport asyncio\n\nfrom elevenlabs.client import AsyncElevenLabs\n\neleven = AsyncElevenLabs(\n api_key=\"MY_API_KEY\"\n)\n\nasync def print_models() -> None:\n models = await eleven.models.list()\n print(models)\n\nasyncio.run(print_models())\n```\n\n## Conversational AI\n\nBuild interactive AI agents with real-time audio capabilities using ElevenLabs Conversational AI.\n\n### Basic Usage\n\n```python\nfrom elevenlabs.client import ElevenLabs\nfrom elevenlabs.conversational_ai.conversation import Conversation, ClientTools\nfrom elevenlabs.conversational_ai.default_audio_interface import DefaultAudioInterface\n\nclient = ElevenLabs(api_key=\"YOUR_API_KEY\")\n\n# Create audio interface for real-time audio input/output\naudio_interface = DefaultAudioInterface()\n\n# Create conversation\nconversation = Conversation(\n client=client,\n agent_id=\"your-agent-id\",\n requires_auth=True,\n audio_interface=audio_interface,\n)\n\n# Start the conversation\nconversation.start_session()\n\n# The conversation runs in background until you call:\nconversation.end_session()\n```\n\n### Custom Event Loop Support\n\nFor advanced use cases involving context propagation, resource reuse, or specific event loop management, `ClientTools` supports custom asyncio event loops:\n\n```python\nimport asyncio\nfrom elevenlabs.conversational_ai.conversation import ClientTools\n\nasync def main():\n # Get the current event loop\n custom_loop = asyncio.get_running_loop()\n\n # Create ClientTools with custom loop to prevent \"different event loop\" errors\n client_tools = ClientTools(loop=custom_loop)\n\n # Register your tools\n async def get_weather(params):\n location = params.get(\"location\", \"Unknown\")\n # Your async logic here\n return f\"Weather in {location}: Sunny, 72\u00b0F\"\n\n client_tools.register(\"get_weather\", get_weather, is_async=True)\n\n # Use with conversation\n conversation = Conversation(\n client=client,\n agent_id=\"your-agent-id\",\n requires_auth=True,\n audio_interface=audio_interface,\n client_tools=client_tools\n )\n\nasyncio.run(main())\n```\n\n**Benefits of Custom Event Loop:**\n- **Context Propagation**: Maintain request-scoped state across async operations\n- **Resource Reuse**: Share existing async resources like HTTP sessions or database pools\n- **Loop Management**: Prevent \"Task got Future attached to a different event loop\" errors\n- **Performance**: Better control over async task scheduling and execution\n\n**Important:** When using a custom loop, you're responsible for its lifecycle\nDon't close the loop while ClientTools are still using it.\n\n### Tool Registration\n\nRegister custom tools that the AI agent can call during conversations:\n\n```python\nclient_tools = ClientTools()\n\n# Sync tool\ndef calculate_sum(params):\n numbers = params.get(\"numbers\", [])\n return sum(numbers)\n\n# Async tool\nasync def fetch_data(params):\n url = params.get(\"url\")\n # Your async HTTP request logic\n return {\"data\": \"fetched\"}\n\nclient_tools.register(\"calculate_sum\", calculate_sum, is_async=False)\nclient_tools.register(\"fetch_data\", fetch_data, is_async=True)\n```\n\n## Languages Supported\n\nExplore [all models & languages](https://elevenlabs.io/docs/models).\n\n## Contributing\n\nWhile we value open-source contributions to this SDK, this library is generated programmatically. Additions made directly to this library would have to be moved over to our generation code, otherwise they would be overwritten upon the next generated release. Feel free to open a PR as a proof of concept, but know that we will not be able to merge it as-is. We suggest opening an issue first to discuss with us!\n\nOn the other hand, contributions to the README are always very welcome!\n",
"bugtrack_url": null,
"license": "MIT",
"summary": null,
"version": "2.20.1",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "71079871b59b58df1ca775276343ef97344740e7cec74e725ecc5d7870ff758e",
"md5": "d1fd182ac4f0727311611679a3899280",
"sha256": "9ac7eb2ecc57e2a6e7dfb491f3b57ec9e36deb8eff54c35ab1c5fb92f1e80ec8"
},
"downloads": -1,
"filename": "elevenlabs-2.20.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d1fd182ac4f0727311611679a3899280",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 1087629,
"upload_time": "2025-10-23T14:33:10",
"upload_time_iso_8601": "2025-10-23T14:33:10.216463Z",
"url": "https://files.pythonhosted.org/packages/71/07/9871b59b58df1ca775276343ef97344740e7cec74e725ecc5d7870ff758e/elevenlabs-2.20.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "75760b27ddb7aa9b323e807c991746710c9c105305a324fe6e2807c88db3e6ee",
"md5": "4c4c7f61b1caa13dc25720466c3a9572",
"sha256": "321a5b5425899738af41530b6fe1e9982a6b22c9d82e1e7fe3df8f6dfcc56d50"
},
"downloads": -1,
"filename": "elevenlabs-2.20.1.tar.gz",
"has_sig": false,
"md5_digest": "4c4c7f61b1caa13dc25720466c3a9572",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 404610,
"upload_time": "2025-10-23T14:33:12",
"upload_time_iso_8601": "2025-10-23T14:33:12.122951Z",
"url": "https://files.pythonhosted.org/packages/75/76/0b27ddb7aa9b323e807c991746710c9c105305a324fe6e2807c88db3e6ee/elevenlabs-2.20.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-23 14:33:12",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "elevenlabs"
}
