Voice narration

The narration endpoint turns text into speech and tells you when each word is spoken. It exists for tools that record a demo and need the voice lined up with what is on screen: you know the second a phrase is said, so you can start the matching click at that second.

It needs a token granted the narration:synthesize scope, which is an OAuth path today. That scope covers spending your organization’s included narration and nothing else. It is separate from content:write, so an uploader has not been given the allowance to draw on, and a client that only wants a voice has no way to upload.

Who can use it

Anyone who could put a guide or a video in front of a reviewer, or in the library. Concretely, the person behind the token needs one of guide.create, video.create or content-review.create, which every member of an organization has except external users. The permission is checked on every request, so someone whose access is removed stops being able to narrate on their next call rather than when the token expires.

Synthesize

POST /v1/narration/synthesize

{
  "text": "Invoices now has a New invoice button at the top of the list.",
  "voiceId": "nPczCjzI2devNBz1zQrb"
}

text is trimmed, then must be 1 to 1,000 characters. The trimmed length is what counts against your allowance.

voiceId is optional and must be one of the catalog voices below. It defaults to the first one. Other ElevenLabs voice ids are refused, because this spends Mereon’s account.

Voice	`voiceId`
Brian	`nPczCjzI2devNBz1zQrb`
Matilda	`XrExE9yKIg1WjnnlVkGX`
Daniel	`onwK4e9ZLuTAKqWW03F9`
Jessica	`cgSgspJ2msm6clMCkdW9`
Adam	`pNInz6obpgDQGcFmaJgB`
Lily	`pFZP5JQG7iQjIQuC4Bku`

{
  "audio": {
    "base64": "SUQzBAAAAAAA…",
    "format": "mp3_44100_128",
    "mimeType": "audio/mpeg"
  },
  "words": [
    { "word": "Invoices", "start": 0.0, "end": 0.62 },
    { "word": "now", "start": 0.7, "end": 0.88 },
    { "word": "list.", "start": 3.41, "end": 3.9 }
  ],
  "characters": 61
}

The audio is MP3 at 44.1 kHz and 128 kbps. Times are seconds from the start of the audio.

How words are split

words lists each word of the text you sent, in order. A word is a run of characters without whitespace, so punctuation stays attached to the word it touches: list. is one word, not two. The words are taken from the text you sent and not from the spoken form, so a number you wrote as 3 is 3 here even though it is said as “three”.

Your allowance

Every organization has an allowance of 100,000 characters of narration per UTC month, shared by everyone in it. That is roughly a hundred one-minute demos. Nothing limits how much of it one person uses, so a client that keeps retrying can use it up for everyone; cache what you synthesize, and stop on errors rather than looping.

A request reserves its characters before speech is generated. If the provider then produces nothing, the reservation is given back, so a failed request costs nothing and retrying it is safe. In the rare case that it produces audio whose word timings cannot be read, the characters stay counted, because the provider charged for them, and the response is still a 503 that says so.

When the month’s allowance is used up the request is refused with 429 and the code NARRATION_QUOTA_EXCEEDED. The Retry-After header holds the number of seconds until the allowance resets at the start of the next UTC month. This is a wait, not a fault, so a client can say so and offer to carry on with its own speech provider in the meantime.

Errors

Status	Meaning
`400`	`text` is empty or longer than 1,000 characters, or `voiceId` is not a catalog voice.
`401`	The token is missing, invalid or expired.
`403`	The token lacks `narration:synthesize`, or the person behind it no longer holds a permission that allows narration.
`429` with `NARRATION_QUOTA_EXCEEDED`	The organization has used its allowance this month. See `Retry-After`.
`429` without an error code	Too many requests too quickly. Wait a moment and retry.
`503` with `NARRATION_PROVIDER_FAILED`	The speech provider could not produce usable audio. Try again shortly. Nothing was counted unless the message says otherwise.

What we keep

The endpoint stores neither your text nor the audio. It records that a request happened and how many characters it used, against the token, so an administrator can see what a connection spent. The text you send is passed to our speech provider to be spoken.