> 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).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://whitepaper.aitech.io/agentforge/tools/elevenlabs.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.