Speech

Stored audio

Queue speech with POST /v1/audio for mp3, Opus or WAV files up to 5,000 characters, kept in your asset library.

POST /v1/audio turns text into an audio file: it is queued, spoken, stored in your asset library, and you poll for it. Use it when you want mp3 or Opus, longer text, or a file to keep.

curl https://api.lumavox.ai/v1/audio \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Welcome to the tour. Let us begin in the east wing.", "format": "mp3"}'

It answers 202 straight away with a generation to poll:

{
  "id": "gen_a1B2c3D4e5F6g7H8",
  "status": "queued",
  "capability": "tts",
  "model": "eleven_flash_v2_5",
  "prompt": "Welcome to the tour. Let us begin in the east wing.",
  "output_format": "mp3",
  "voice_id": "default",
  "credits_micros": 125000,
  "audio": null,
  "error": null,
  "created_at": "2026-10-24T09:30:00.000Z",
  "finished_at": null
}

The text you sent is the generation’s prompt, and the format its output_format. Every other field of a generation is there too, null where it does not apply to speech; the full shape is in the reference.

When to use it instead of `/v1/tts`

	`POST /v1/tts`	`POST /v1/audio`
Answer	the audio, in the response	a generation id, then poll
Formats	`wav`, `pcm`	`mp3` (default), `opus`, `wav`
Text	up to 2,000 characters	up to 5,000 characters
Streaming	yes, `pcm`	no
Stored	no	yes, in your asset library

Use text to speech for anything someone is waiting to hear. Use this for files: narration, downloads, anything you would otherwise have to encode and upload yourself.

The request

It takes the same voice fields as POST /v1/tts, plus a destination folder.

Field	Default	What it does
`text`	—	What to say. 1 to 5,000 characters.
`voice_id`	`default`	An `id` from `GET /v1/voices`.
`model`	`eleven_flash_v2_5`	One of the voice’s `models`.
`format`	`mp3`	`mp3`, `opus` or `wav`.
`provider_options`	`null`	Voice settings for this request — see tuning the voice.
`folder_id`	root	`fld_…`, the library folder the file is filed under. A folder that is not yours is a 422.

What each format is:

`format`	File
`mp3`	MPEG audio, 44.1 kHz, 128 kbps (`audio/mpeg`)
`opus`	Opus in an Ogg container, 48 kHz, 64 kbps (`audio/ogg`)
`wav`	16-bit mono PCM at 24 kHz, with a WAV header (`audio/wav`)

sample_rate has no effect on this endpoint: each format is produced at the rate in the table.

The key needs the tts scope — the same scope as /v1/tts.

Polling

Poll GET /v1/audio/{generation_id} every couple of seconds until status is terminal.

curl https://api.lumavox.ai/v1/audio/gen_a1B2c3D4e5F6g7H8 \
  -H "Authorization: Bearer $API_KEY"

`status`	Meaning
`queued`, `submitted`, `running`	Still working. Keep polling.
`succeeded`	Done. The file is on `audio`.
`failed`	Nothing was produced. `error` says why.
`moderated`	Refused by the provider’s safety filter.

When it has succeeded, audio describes the file:

{
  "id": "gen_a1B2c3D4e5F6g7H8",
  "status": "succeeded",
  "capability": "tts",
  "audio": {
    "asset_id": "ast_x9Y8z7W6v5U4t3S2",
    "url": "https://…",
    "duration_seconds": 3.9,
    "content_type": "audio/mpeg",
    "size_bytes": 62853,
    "peaks": [12, 40, 87, 63]
  },
  "error": null,
  "created_at": "2026-10-24T09:30:00.000Z",
  "finished_at": "2026-10-24T09:30:03.218Z"
}

url is a short-lived link. It is minted for each response and not stored: fetch the generation, or the asset, again for a fresh one.
asset_id is the file’s permanent home in your asset library.
duration_seconds and peaks (a waveform for drawing) are measured after the file is stored, and can be null when a file could not be measured.

Polling is free and does not count against your rate limit — it is the intended pattern. See Queued jobs for the general rules, and Generations to find an id you lost.

Cost

Charged when accepted, not when finished, per thousand characters at the rate of the model you chose. The charge is on the generation as credits_micros, an integer of micro-credits (Conventions). A generation that fails is refunded in full. See Credits and usage.

Errors

The common envelope is described in Errors and limits. The ones specific to this endpoint:

Status	When
400	The body is not valid JSON.
422	`folder_id` is not one of your folders.
402	The organisation is out of credits, or this job’s estimate would take its balance past the grace buffer. Nothing is charged.
404	`voice_id` is unknown or not usable; or, when polling, the generation id is unknown, not yours, or not a speech generation.
422	The body failed validation: `text` empty or over 5,000 characters, an unknown `format` or field, or a `model` that is not one of the voice’s `models`. `issues` names the field.
429	Over your organisation’s rate limit. Nothing was charged.
503	Speech is not set up on this deployment.

Text to speech — speech in the response, and streaming.
Queued jobs — how every queued capability works.
Reference: audio