Skip to main content

​
Getting Your API Key

To use the ElevenLabs Python SDK, you need an API key from your ElevenLabs account.
1

Sign Up or Log In

Visit ElevenLabs and create an account or log in to your existing account.
2

Access Your Profile

Navigate to your profile settings by clicking on your avatar in the top-right corner.
3

Generate API Key

Go to the API section and generate a new API key. Copy this key and store it securely.
Keep your API key secret! Never commit it to version control or share it publicly.

​
Configuration Methods

There are three ways to configure authentication with the ElevenLabs SDK: The most secure and convenient method is using environment variables.
1

Create a .env file

Create a .env file in your project root:
.env
ELEVENLABS_API_KEY=your_api_key_here
2

Install python-dotenv

Install the python-dotenv package to load environment variables:
pip install python-dotenv
3

Load in your code

Load the environment variables and initialize the client:
from dotenv import load_dotenv
from elevenlabs.client import ElevenLabs

load_dotenv()

# The client automatically reads ELEVENLABS_API_KEY
elevenlabs = ElevenLabs()
The client automatically looks for the ELEVENLABS_API_KEY environment variable. You don’t need to pass it explicitly.

​
Method 2: Direct API Key Parameter

Pass the API key directly when initializing the client: 
from elevenlabs.client import ElevenLabs

elevenlabs = ElevenLabs(
    api_key="your_api_key_here"
)
Avoid hardcoding API keys in your source code. Use this method only for testing or when reading the key from a secure source.

​
Method 3: System Environment Variable

Set the API key as a system environment variable: 
export ELEVENLABS_API_KEY="your_api_key_here"
Then initialize the client without parameters: 
from elevenlabs.client import ElevenLabs

elevenlabs = ElevenLabs()

​
Client Configuration Options

The ElevenLabs client accepts several configuration parameters: 
from elevenlabs.client import ElevenLabs
from elevenlabs.environment import ElevenLabsEnvironment
import httpx

elevenlabs = ElevenLabs(
    api_key="your_api_key_here",           # API key for authentication
    base_url="https://api.elevenlabs.io",   # Custom base URL (optional)
    environment=ElevenLabsEnvironment.PRODUCTION,  # Environment (default: PRODUCTION)
    timeout=240.0,                          # Request timeout in seconds (default: 240)
    httpx_client=httpx.Client()             # Custom httpx client (optional)
)

​
Configuration Parameters

​
api_key
str
Your ElevenLabs API key. If not provided, the client reads from the ELEVENLABS_API_KEY environment variable.
​
base_url
str
Custom base URL for API requests. Useful for enterprise deployments or testing.
​
environment
ElevenLabsEnvironment
default:"PRODUCTION"
The environment to use for requests. Defaults to ElevenLabsEnvironment.PRODUCTION.
​
timeout
float
default:"240"
Request timeout in seconds. Default is 240 seconds (4 minutes).
​
httpx_client
httpx.Client
Custom pre-configured httpx client. Useful for advanced HTTP configurations like proxies or custom SSL certificates.

​
Async Client Authentication

The async client (AsyncElevenLabs) uses the same authentication methods: 
from elevenlabs.client import AsyncElevenLabs

# Using environment variable
elevenlabs = AsyncElevenLabs()

# Using direct API key
elevenlabs = AsyncElevenLabs(
    api_key="your_api_key_here"
)

​
Async Client Configuration

The async client accepts the same parameters, but with an async httpx client: 
import httpx
from elevenlabs.client import AsyncElevenLabs
from elevenlabs.environment import ElevenLabsEnvironment

elevenlabs = AsyncElevenLabs(
    api_key="your_api_key_here",
    base_url="https://api.elevenlabs.io",
    environment=ElevenLabsEnvironment.PRODUCTION,
    timeout=240.0,
    httpx_client=httpx.AsyncClient()  # Note: AsyncClient for async usage
)

​
Testing Your Authentication

Verify your authentication is working correctly: 
from elevenlabs.client import ElevenLabs

try:
    elevenlabs = ElevenLabs()
    
    # List available voices to test authentication
    response = elevenlabs.voices.search()
    print(f"✓ Authentication successful! Found {len(response.voices)} voices.")
except Exception as e:
    print(f"✗ Authentication failed: {e}")

​
Security Best Practices

Add .env to your .gitignore file:
.gitignore
.env
*.env
Create separate API keys for development, staging, and production:
# .env.development
ELEVENLABS_API_KEY=dev_key_here

# .env.production
ELEVENLABS_API_KEY=prod_key_here
Generate new API keys periodically and revoke old ones through your ElevenLabs dashboard.
If available, use API keys with limited scopes for specific use cases.
Regularly check your API usage in the ElevenLabs dashboard to detect any unauthorized access.

​
Custom HTTP Client Configuration

For advanced use cases, configure a custom httpx client:

​
Proxy Configuration

import httpx
from elevenlabs.client import ElevenLabs

# Configure proxy
httpx_client = httpx.Client(
    proxies={
        "http://": "http://proxy.example.com:8030",
        "https://": "http://proxy.example.com:8031",
    }
)

elevenlabs = ElevenLabs(
    api_key="your_api_key_here",
    httpx_client=httpx_client
)

​
Custom Timeouts

import httpx
from elevenlabs.client import ElevenLabs

# Set custom timeouts
httpx_client = httpx.Client(
    timeout=httpx.Timeout(10.0, connect=5.0)
)

elevenlabs = ElevenLabs(
    api_key="your_api_key_here",
    httpx_client=httpx_client
)

​
SSL Certificate Verification

import httpx
from elevenlabs.client import ElevenLabs

# Custom SSL configuration
httpx_client = httpx.Client(
    verify="/path/to/custom/ca-bundle.crt"
)

elevenlabs = ElevenLabs(
    api_key="your_api_key_here",
    httpx_client=httpx_client
)

​
Troubleshooting

​
Common Authentication Errors

Cause: Invalid or missing API key.Solution:
  • Verify your API key is correct
  • Check that the environment variable is set correctly
  • Ensure you’re using the latest SDK version
Cause: The .env file is not being loaded or is in the wrong location.Solution:
  • Ensure .env is in the same directory where you run your script
  • Verify load_dotenv() is called before creating the client
  • Check that python-dotenv is installed
Cause: API key doesn’t have permission for the requested operation.Solution:
  • Check your subscription plan limits
  • Verify the API key has the necessary permissions
  • Contact ElevenLabs support if the issue persists
Cause: Request taking longer than the configured timeout.Solution:
  • Increase the timeout parameter when initializing the client
  • Check your internet connection
  • Verify the ElevenLabs API status

​
Next Steps

Now that you’ve configured authentication, you’re ready to:

Quickstart Guide

Generate your first text-to-speech audio

API Reference

Explore all available API methods

Build docs developers (and LLMs) love

Get started for freeTalk to us