> For the complete documentation index, see [llms.txt](https://whitepaper.aitech.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://whitepaper.aitech.io/agentforge/tools/elevenlabs.md).

# elevenlabs

[ElevenLabs](https://elevenlabs.io/) is a state-of-the-art text-to-speech (TTS) platform with lifelike, expressive voices. Use it to turn agent outputs into natural audio for assistants, IVRs, demos, accessibility features, and more.

## Quick Setup

{% stepper %}
{% step %}

### Get your API key

1. Sign in at [**elevenlabs.io**](https://elevenlabs.io/).
2. In the **left sidebar**, open the **Developers** tab.
3. Go to **API Keys** → **Create / View**.
4. **Copy your API key** and store it securely (you’ll paste this into the block’s `apiKey`).
   {% endstep %}

{% step %}

### Find your Voice ID

There are two easy ways:

* **From the ElevenLabs UI**
  1. In the **left sidebar**, open the **Voices** tab.
  2. Click a voice from your library or the VoiceLab.
  3. Copy the **Voice ID** shown in the voice details panel (or from the voice URL/details modal if available).
* **From the API (optional)**
  * Call the “List Voices” endpoint to retrieve available voices and copy the `voice_id` you want to use.

> Make sure the voice you pick is **included in your current plan** (premium/pro voices may require higher tiers).
> {% endstep %}
> {% endstepper %}

## Usage Instructions

Use the **ElevenLabs** block to generate speech from text. Provide:

* `text` — the content you want spoken
* `voiceId` — a voice available to your plan
* `apiKey` — your ElevenLabs API key
* *(optional)* `modelId` — defaults to `eleven_monolingual_v1`

The block returns an `audioUrl` pointing to the generated audio.

## Tools

### `elevenlabs_tts`

Convert text to speech using an ElevenLabs voice.

#### Input

| Parameter | Type   | Required | Description                                     |
| --------- | ------ | -------- | ----------------------------------------------- |
| `text`    | string | Yes      | The text to convert to speech.                  |
| `voiceId` | string | Yes      | The target voice ID (must be available to you). |
| `modelId` | string | No       | Model to use. Default: `eleven_monolingual_v1`. |
| `apiKey`  | string | Yes      | Your ElevenLabs API key.                        |

#### Output

| Parameter  | Type   | Description                      |
| ---------- | ------ | -------------------------------- |
| `audioUrl` | string | URL of the generated audio file. |

## Troubleshooting

### Common error

**`Error generating speech: Request failed with status 400`**

**Likely causes**

* The **voice is not available** on your **current plan** (e.g., premium/proprietary voice requiring a higher tier).
* **Insufficient credits** in your ElevenLabs account.
* A required input is missing or malformed (`text`, `voiceId`, or `apiKey`).
* The `modelId` is invalid for your account/region.
* The text violates provider content rules or exceeds internal limits.

**How to fix**

* **Check plan & credits:** In ElevenLabs, confirm your subscription tier and remaining credits. Either switch to a voice your plan supports or upgrade your plan.
* **Validate inputs:** Ensure `text` is non-empty, `voiceId` is correct, and the **API key** is valid.
* **Try default model:** Omit `modelId` (use default) or switch back to `eleven_monolingual_v1`.
* **Shorten or sanitize text:** Trim very long inputs or remove problematic characters.
* **Test another voice:** Pick a standard voice you know your plan includes from the Voices tab.

> If errors persist, re-copy the **API key** from **Developers → API Keys** and test with a known supported voice from **Voices**.

## Best Practices

* **Keep text concise:** Very long inputs can increase latency and cost.
* **Choose voices by use case:** Narration vs. assistant voices, multilingual needs, etc.
* **Cache stable audio:** If you reuse the same text/voice often, store the generated audio to save credits.
* **Handle fallbacks:** If a preferred voice fails, retry with a standard voice available to all tiers.

## Notes

* **Category:** `tools`
* **Type:** `elevenlabs`
* Requires a valid **API key** (Developers tab) and a **Voice ID** (Voices tab).