# Narration with ElevenLabs

agh can narrate audio requests with your ElevenLabs account: voice-overs, trailers and pitch videos, and game voice lines. It sends the script to ElevenLabs in the voice you choose, including voices you cloned, and delivers the MP3 for review like any other file. Narration comes with the **Studio** and **Enterprise** plans. ElevenLabs bills the characters to your own account.

## Connect ElevenLabs

1. In ElevenLabs, open **Developers > API Keys** and create a key. Allow **Text to Speech** and **Voices (read)**, and **Sound Effects** and **Music** if you'll [make those too](/docs/sound). Allow **User (read)** too if you want agh to show the credits you have left.
2. In agh, open **Settings › Connectors**. Paste the key under **ElevenLabs audio** and choose **Connect**.

agh checks the key by listing your voices, then keeps it in its secret store and shows only its last four characters. Admins can replace the key, set a **monthly cap** on the credits agh may use (a narrated character is a credit, and the cap covers sound effects and music too), or disconnect. Admins and developers can see the account's voices and credits.

## Ask for a narration

An audio request is narrated when its path ends in `.mp3`, `.ogg` or `.opus` and its spec says what to say and who says it. A path ending in `.ogg` or `.opus` gets an Ogg Opus file; `.mp3` gets an MP3.

| Spec | What it does |
| --- | --- |
| `script` | The id of a text asset whose accepted file is the script, such as `marketing.pitch.script`. Markdown headings are skipped. |
| `line` | The words to say, for a short line such as a voice line (up to 256 characters). Used when there's no `script`. |
| `voice` | A voice on the connected account, by name or id, such as `Matthew`. |
| `pronounce` | Words to say differently, such as `agh=A.G.H.; Virandel=Vee-ran-del`. Whole words, any case. |
| `model` | `eleven_v3` (or `v3`) or `eleven_multilingual_v2` (the default). |
| `stability` | 0 to 1. Lower is more expressive. Eleven v3 rounds it to 0 (Creative), 0.5 (Natural) or 1 (Robust). |
| `similarity` | 0 to 1: how closely to keep to the voice. |
| `style` | 0 to 1: how much to exaggerate the voice's style. |
| `speed` | 0.7 to 1.2. |
| `speaker_boost` | `on` or `off`. |

Settings you leave out use the voice's own, as set in ElevenLabs.

### Audio tags

Eleven v3 takes directions in square brackets, such as `[whispers]`, `[laughs]` or `[shouts]`, written in the script where they apply: `[whispers] Don't order the stew.` They cost characters like any other text. Multilingual v2 would read them aloud, so agh leaves them out of what it sends that model, and the dialog shows them struck through.

A coding agent can ask for narration like any other asset, but only a person can spend the credits.

## Narrate

Open requests that can be narrated have **Narrate with ElevenLabs…** for admins and developers. It shows the voice, the model and voice settings (filled in from the spec, and yours to change), the script's lines, how many characters it costs, the file it delivers, and what your account and the project's cap have left. Nothing is spent until you choose **Narrate**. If the script changed after you looked, agh stops and shows the new cost.

The file is delivered to the request with provenance `ai`, made by ElevenLabs, with the model, the voice and its settings. Under the player, the review card lists each line with the time it's spoken. Click a line to play from there.

## Retake a line

When one line comes out wrong, you don't have to narrate the whole script again. In review, each line has **Retake**. Change its words if you like, for example to add a tag or fix a slip, adjust the model or settings for this line, and choose **Retake**. It costs that line's characters only.

agh joins the new take into the file where the line was, keeping the pauses around it, and the lines after it move to match. Every version of the line is kept: the line shows **Original**, **Retake 1** and so on, each with a play button, and the one you pick is the one in the file. Accept when you're happy with every line.

You can also retake a line of an accepted narration from its page in the Library. That delivers a new version for review, and the accepted file stays until you accept the new one.

## Plans

Narration keeps your key and calls ElevenLabs from agh's servers, so it's part of the Studio and Enterprise plans. Retaking a line is part of narration. On other plans, **Settings › Connectors**, the open request and a narrated file's lines show what it does and link here. To upgrade, [ask us](/support).