Async Client

Using AsyncElevenLabs for asynchronous API operations

Overview

The AsyncElevenLabs client allows you to make API calls asynchronously using Python’s asyncio framework. This is particularly useful when you need to make multiple API calls concurrently or integrate with async web frameworks.

Installation

The async client is included in the standard ElevenLabs package:

pip install elevenlabs

Basic Usage

Here’s how to use the async client to list available models:

import asyncio
from elevenlabs.client import AsyncElevenLabs

elevenlabs = AsyncElevenLabs(
    api_key="MY_API_KEY"
)

async def print_models() -> None:
    models = await elevenlabs.models.list()
    print(models)

asyncio.run(print_models())

Configuration

The AsyncElevenLabs client accepts the same configuration parameters as the synchronous client:

api_key · str · required

Your ElevenLabs API key. Defaults to the ELEVENLABS_API_KEY environment variable.

base_url · str

The base URL for API requests. Override this for testing or custom endpoints.

environment · ElevenLabsEnvironment · default: "PRODUCTION"

The environment to use for requests from the client.

timeout · float · default: 240

The timeout in seconds for requests. Default is 240 seconds (4 minutes).

httpx_client · httpx.AsyncClient

A custom async httpx client for advanced configuration.

Common Async Operations

Text-to-Speech Generation

import asyncio
from elevenlabs.client import AsyncElevenLabs

client = AsyncElevenLabs(api_key="YOUR_API_KEY")

async def generate_speech():
    # Generate audio asynchronously
    audio = await client.text_to_speech.convert(
        text="Hello from the async client!",
        voice_id="JBFqnCBsd6RMkjVDRZzb",
        model_id="eleven_multilingual_v2"
    )
    
    # Save to file
    with open("output.mp3", "wb") as f:
        f.write(audio)

asyncio.run(generate_speech())

Listing Voices

async def list_voices():
    response = await client.voices.search()
    for voice in response.voices:
        print(f"{voice.name}: {voice.voice_id}")

asyncio.run(list_voices())

Working with Pronunciation Dictionaries

from elevenlabs.pronunciation_dictionaries import (
    BodyAddAPronunciationDictionaryV1PronunciationDictionariesAddFromRulesPostRulesItem_Alias,
)

async def create_dictionary():
    dictionary = await client.pronunciation_dictionaries.create_from_rules(
        rules=[
            BodyAddAPronunciationDictionaryV1PronunciationDictionariesAddFromRulesPostRulesItem_Alias(
                string_to_replace="AI",
                case_sensitive=True,
                word_boundaries=True,
                alias="Artificial Intelligence",
            )
        ],
        name="Tech Abbreviations",
        description="Common technology abbreviations"
    )
    print(f"Created dictionary: {dictionary.id}")

asyncio.run(create_dictionary())

Concurrent Operations

One of the main benefits of the async client is the ability to run multiple operations concurrently:

import asyncio
from elevenlabs.client import AsyncElevenLabs

client = AsyncElevenLabs(api_key="YOUR_API_KEY")

async def generate_multiple_speeches():
    texts = [
        "First message",
        "Second message",
        "Third message"
    ]
    
    # Run all conversions concurrently
    tasks = [
        client.text_to_speech.convert(
            text=text,
            voice_id="JBFqnCBsd6RMkjVDRZzb",
            model_id="eleven_multilingual_v2"
        )
        for text in texts
    ]
    
    # Wait for all to complete
    results = await asyncio.gather(*tasks)
    
    # Save all results
    for i, audio in enumerate(results):
        with open(f"output_{i}.mp3", "wb") as f:
            f.write(audio)

asyncio.run(generate_multiple_speeches())

Integration with Web Frameworks

The async client integrates seamlessly with async web frameworks like FastAPI:

from fastapi import FastAPI, HTTPException
from elevenlabs.client import AsyncElevenLabs
from pydantic import BaseModel

app = FastAPI()
client = AsyncElevenLabs(api_key="YOUR_API_KEY")

class TextToSpeechRequest(BaseModel):
    text: str
    voice_id: str = "JBFqnCBsd6RMkjVDRZzb"

@app.post("/tts")
async def text_to_speech(request: TextToSpeechRequest):
    try:
        audio = await client.text_to_speech.convert(
            text=request.text,
            voice_id=request.voice_id,
            model_id="eleven_multilingual_v2"
        )
        return {"success": True, "message": "Audio generated"}
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

Best Practices

Use context managers for resource cleanup

When working with the async client, ensure proper cleanup of resources:

async with AsyncElevenLabs(api_key="YOUR_API_KEY") as client:
    result = await client.models.list()

Handle errors appropriately

Always wrap async operations in try-except blocks to handle potential errors:

try:
    result = await client.text_to_speech.convert(...)
except Exception as e:
    print(f"Error: {e}")

Use asyncio.gather for concurrent operations

When you need to perform multiple operations, use asyncio.gather to run them concurrently:

results = await asyncio.gather(
    client.voices.search(),
    client.models.list(),
    return_exceptions=True  # Continue even if one fails
)

The async client provides the same functionality as the synchronous client. All methods that perform I/O operations are awaitable.

Next Steps

Error Handling

Learn how to handle errors in async operations

Pronunciation Dictionaries

Create custom pronunciation rules