ElevenLabs API Reference

Detailed API documentation for ElevenLabs audio generation services.

Authentication

from elevenlabs.client import ElevenLabs
client = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY"))

Text-to-Speech Models

Voice Settings

Output Formats

Long-form Audio (Stitching)

For continuity across multiple generations:

result1 = client.text_to_speech.convert_with_timestamps(
    text="First paragraph...",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    model_id="eleven_multilingual_v2"
)
request_id_1 = result1.request_id

result2 = client.text_to_speech.convert(
    text="Second paragraph...",
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    model_id="eleven_multilingual_v2",
    previous_request_ids=[request_id_1]
)

Professional Voice Cloning (PVC)

Requires Creator plan+. Creates a fine-tuned model (3-6 hours training).

Requirements:

• 30 min minimum, 2-3 hours optimal audio
• Professional XLR mic recommended
• Pop filter, ~20cm distance
• Peak levels: -6dB to -3dB
• Consistent performance style

Workflow:

# 1. Create PVC with samples
pvc = client.voices.create_professional_voice_clone(
    name="My Pro Voice",
    files=["recording1.mp3", "recording2.mp3", ...],
)

# 2. Get verification captcha
captcha = client.voices.get_pvc_verification_captcha(voice_id=pvc.voice_id)
# Read the captcha text aloud and record

# 3. Submit verification
client.voices.verify_pvc(
    voice_id=pvc.voice_id,
    recording=open("captcha_reading.mp3", "rb")
)

# 4. Start training
client.voices.start_pvc_training(voice_id=pvc.voice_id)

Sound Effects Parameters

Billing: 100 chars/generation (auto) or 25 chars/second (fixed duration)

Example prompts:

• Environmental: "Rain on a tin roof, steady and rhythmic"
• Action: "Sword being drawn from sheath, metallic ring"
• Mechanical: "Old car engine struggling to start then roaring to life"

Music Parameters

*Either prompt or composition_plan required, not both.

Effective prompts include:

1. Genre/Style: "indie rock", "lo-fi hip hop", "orchestral"
2. Mood: "uplifting", "melancholic", "tense"
3. Instruments: "acoustic guitar", "synth pads", "strings"
4. Tempo/Energy: "slow", "upbeat", "driving"
5. Context: "for a travel vlog", "podcast intro"

Rate Limits by Tier

Voice Management

# List voices
voices = client.voices.get_all()
for voice in voices.voices:
    print(f"{voice.name}: {voice.voice_id}")

# Delete voice
client.voices.delete(voice_id="your_voice_id")

Error Handling

from elevenlabs.core.api_error import ApiError

try:
    audio = client.text_to_speech.convert(...)
except ApiError as e:
    if e.status_code == 429:
        print("Rate limited - wait and retry")
    elif e.status_code == 401:
        print("Invalid API key")