---
name: elevenlabs
description: Make voice-overs, narration, sound effects and music with ElevenLabs. Use when the user wants text read aloud, a character voice, a sound effect or a short instrumental. Needs ELEVENLABS_API_KEY.
---

# ElevenLabs

Key: `ELEVENLABS_API_KEY`. Get one at https://elevenlabs.io/app/settings/api-keys

Every call uses the header `xi-api-key: $ELEVENLABS_API_KEY` and returns the audio itself, so save it with `--output`.

## Pick a voice

```bash
curl -s "https://api.elevenlabs.io/v2/voices?page_size=100&search=narrator" -H "xi-api-key: $ELEVENLABS_API_KEY"
```

Each voice has a `voice_id` and a `name`. `JBFqnCBsd6RMkjVDRZzb` (George) works on every account.

## Speech

```bash
curl -s -X POST "https://api.elevenlabs.io/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
  -d '{"text":"Welcome back. Tonight, we cook with fire.","model_id":"eleven_v4"}' \
  --output voice.mp3
```

`eleven_v4` sounds best. `eleven_flash_v2_5` is half the price and faster.

## Sound effect

```bash
curl -s -X POST https://api.elevenlabs.io/v1/sound-generation \
  -H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
  -d '{"text":"Heavy wooden door creaking open in a stone hall","duration_seconds":4}' \
  --output door.mp3
```

## Music

```bash
curl -s -X POST https://api.elevenlabs.io/v1/music \
  -H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
  -d '{"prompt":"Warm lo-fi beat with vinyl crackle","music_length_ms":30000,"model_id":"music_v2_5","force_instrumental":true}' \
  --output beat.mp3
```

## Notes

- Sound effects and music aren't on the free plan. A 401 or 402 on them means the account needs a paid plan or a top-up.
- A JSON reply instead of audio is an error. Read its `detail.message`.