ElevenLabs API

Use the ElevenLabs API via direct curl calls to generate realistic AI speech from text.

Official docs: https://elevenlabs.io/docs/api-reference

When to Use

Use this skill when you need to:

Convert text to speech with high-quality AI voices
List available voices to find the right voice for your use case
Stream audio output for real-time playback
Generate voiceovers for videos, podcasts, or accessibility

Prerequisites

Sign up at ElevenLabs and create an account
Go to your profile settings and generate an API key
Store your API key in the environment variable ELEVENLABS_API_KEY

export ELEVENLABS_API_KEY="your-api-key"

API Limits

Free tier: limited characters per month
API key is passed via the xi-api-key header

Important: When using $VAR in a command that pipes to another command, wrap the command containing $VAR in bash -c '...'. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.
bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"' | jq .

How to Use

All examples below assume you have ELEVENLABS_API_KEY set.

The base URL for the ElevenLabs API is:

https://api.elevenlabs.io/v1

1. List Available Voices

Get all voices available to your account:

bash -c 'curl -s -X GET "https://api.elevenlabs.io/v1/voices" --header "xi-api-key: ${ELEVENLABS_API_KEY}"' | jq '.voices[] | {voice_id, name, category}

This returns voice IDs needed for text-to-speech. Common voice categories:

premade: ElevenLabs default voices
cloned: Your cloned voices
generated: AI-designed voices

2. Get Voice Details

Get detailed information about a specific voice:

VOICE_ID="21m00Tcm4TlvDq8ikWAM"

bash -c 'curl -s -X GET "https://api.elevenlabs.io/v1/voices/${VOICE_ID}" --header "xi-api-key: ${ELEVENLABS_API_KEY}"' | jq .

3. List Available Models

Get all available TTS models:

bash -c 'curl -s -X GET "https://api.elevenlabs.io/v1/models" --header "xi-api-key: ${ELEVENLABS_API_KEY}"' | jq '.[] | {model_id, name, can_do_text_to_speech}

Common models:

eleven_multilingual_v2: Best quality, supports 29 languages
eleven_flash_v2_5: Low latency, good for real-time
eleven_v3: Latest model (alpha)

4. Text to Speech (Save to File)

Convert text to speech and save as MP3:

VOICE_ID="21m00Tcm4TlvDq8ikWAM"

curl -s -X POST "https://api.elevenlabs.io/v1/text-to-speech/${VOICE_ID}" --header "xi-api-key: ${ELEVENLABS_API_KEY}" --header "Content-Type: application/json" --header "Accept: audio/mpeg" -d '{
  "text": "Hello! This is a test of the ElevenLabs text to speech API.",
  "model_id": "eleven_multilingual_v2",
  "voice_settings": {
  "stability": 0.5,
  "similarity_boost": 0.75
  }
}' --output speech.mp3

Voice settings:

stability (0.0-1.0): Higher = more consistent, lower = more expressive
similarity_boost (0.0-1.0): Higher = closer to original voice

5. Text to Speech with Streaming

Stream audio for real-time playback:

VOICE_ID="21m00Tcm4TlvDq8ikWAM"

curl -s -X POST "https://api.elevenlabs.io/v1/text-to-speech/${VOICE_ID}/stream" --header "xi-api-key: ${ELEVENLABS_API_KEY}" --header "Content-Type: application/json" --header "Accept: audio/mpeg" -d '{
  "text": "This audio is being streamed in real-time.",
  "model_id": "eleven_flash_v2_5"
}' --output streamed.mp3

6. Get User Subscription Info

Check your usage and character limits:

bash -c 'curl -s -X GET "https://api.elevenlabs.io/v1/user/subscription" --header "xi-api-key: ${ELEVENLABS_API_KEY}"' | jq '{character_count, character_limit, tier}

Output Formats

You can specify different output formats via the output_format query parameter:

curl -s -X POST "https://api.elevenlabs.io/v1/text-to-speech/${VOICE_ID}?output_format=pcm_16000" --header "xi-api-key: ${ELEVENLABS_API_KEY}" --header "Content-Type: application/json" -d '{"text": "Hello world", "model_id": "eleven_multilingual_v2"}' --output speech.pcm

Available formats:

mp3_44100_192 (default): MP3 at 44.1kHz, 192kbps
mp3_44100_128: MP3 at 44.1kHz, 128kbps
pcm_16000: PCM at 16kHz
pcm_22050: PCM at 22.05kHz
pcm_24000: PCM at 24kHz

Guidelines

Choose the right model: Use eleven_flash_v2_5 for low latency, eleven_multilingual_v2 for best quality
Monitor usage: Check subscription endpoint to avoid exceeding character limits
Experiment with voice settings: Adjust stability and similarity_boost for different effects
Use streaming for long text: Stream endpoint is better for real-time applications
Cache voice IDs: Store frequently used voice IDs to avoid repeated API calls

elevenlabs