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

1. Sign up at ElevenLabs and create an account
2. Go to your profile settings and generate an API key
3. 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"

Write to /tmp/elevenlabs_request.json:

{
  "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
  }
}

Then run:

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 @/tmp/elevenlabs_request.json --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"

Write to /tmp/elevenlabs_request.json:

{
  "text": "This audio is being streamed in real-time.",
  "model_id": "eleven_flash_v2_5"
}

Then run:

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 @/tmp/elevenlabs_request.json --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:

Write to /tmp/elevenlabs_request.json:

{
  "text": "Hello world",
  "model_id": "eleven_multilingual_v2"
}

Then run:

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 @/tmp/elevenlabs_request.json --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

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