# Generations

> Every generation across every capability, in one list — the way back to an id you lost, and the reconciliation loop.

Every generation across every capability, in one list — the way back to an id you lost, and the reconciliation loop.

When and why to call these: the [generations guide](https://docs.lumavox.ai/library/generations.md).

## List generations

`GET /v1/generations`

Everything your organisation has asked any capability for, newest first, in flight or finished — filtered to the capabilities this key holds. `capability` narrows to one; `status` to one state. Paginated by cursor.

```bash title="curl"
curl "https://api.lumavox.ai/v1/generations" \
  -H "Authorization: Bearer $API_KEY"
```

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `limit` | integer |  | How many to answer, 1 to 100. 1–100. Default `30`. |
| `cursor` | string |  | The `next_cursor` of the page before. At least 1 characters. |
| `capability` | `"tts"`, `"image"`, `"video"`, `"stt"`, `"skybox"` |  | Only generations of this capability |
| `status` | `"queued"`, `"submitted"`, `"running"`, `"succeeded"`, `"failed"`, `"moderated"` |  | Only generations in this state |

**Responses**

| Status | Description |
|---|---|
| `200` | `application/json` — One page of generations, newest first |
| `400` | The request could not be read: malformed JSON |
| `401` | Missing or invalid credentials |
| `422` | The request failed validation |
| `429` | Rate limit exceeded |

**`200` response body**

| Field | Type | Description |
|---|---|---|
| `data` | array of GenerationInfo |  |
| `data[].id` | string | `gen_…`. Poll this. |
| `data[].status` | `"queued"`, `"submitted"`, `"running"`, `"succeeded"`, `"failed"`, `"moderated"` | `queued`, `submitted` and `running` mean keep polling. `succeeded`, `failed` and `moderated` are terminal — stop. |
| `data[].capability` | `"tts"`, `"image"`, `"video"`, `"stt"`, `"skybox"` |  |
| `data[].model` | string or null |  |
| `data[].prompt` | string or null |  |
| `data[].aspect_ratio` | string or null |  |
| `data[].width` | integer or null |  |
| `data[].height` | integer or null |  |
| `data[].output_format` | string or null |  |
| `data[].seed` | integer or null |  |
| `data[].megapixels` | number or null |  |
| `data[].safety_tolerance` | integer or null |  |
| `data[].enhance_prompt` | boolean or null |  |
| `data[].folder_id` | string or null | `fld_…` the result lands in, or null for the root. |
| `data[].duration` | integer or null | Seconds asked for. Video only. |
| `data[].resolution` | string or null | `hd` or `fhd`. Video only. |
| `data[].generate_audio` | boolean or null |  |
| `data[].start_frame` | string or null |  |
| `data[].end_frame` | string or null |  |
| `data[].negative_text` | string or null |  |
| `data[].style_id` | integer or null |  |
| `data[].init_image` | string or null |  |
| `data[].init_strength` | number or null |  |
| `data[].voice_id` | string or null |  |
| `data[].speech` | TTSOptions or null | The voice and model a speech generation ran with. |
| `data[].speech.voice_id` | string | An id from `GET /v1/voices` — the built-in voice, a platform voice, or one your organisation uploaded. |
| `data[].speech.model` | string | Which model speaks: one of the voice's `models` in `GET /v1/voices` — `eleven_flash_v2_5` (the fastest, and the default), `eleven_multilingual_v2` or `eleven_v3`. A model the voice does not list is refused. |
| `data[].speech.provider_options` | ProviderVoiceSettingsInfo or null | The provider's voice settings sent on top of the voice's own; `null` took theirs. |
| `data[].speech.format` | `"wav"`, `"pcm"` |  |
| `data[].speech.sample_rate` | `8000`, `16000`, `22050`, `24000`, `44100` or null | Hz of the returned audio — one of 8000, 16000, 22050, 24000, 44100, each served natively by the provider. Unset means 24000. `POST /v1/tts` says what it produced in the `X-Sample-Rate` header. Queued speech (`POST /v1/audio`) does not take it: each of its formats has its own rate. |
| `data[].credits_micros` | integer or null | What was debited when this was accepted, in micro-credits (1 credit is 1,000,000). A failure refunds it in full; a transcription's is corrected to the measured length when it finishes. |
| `data[].template_id` | string or null |  |
| `data[].image` | GenerationImage or null |  |
| `data[].image.asset_id` | string or null | The library entry this generation produced. |
| `data[].image.url` | string or null | A short-lived link to the file. Minted per response and not stored — fetch the asset again for a fresh one. |
| `data[].image.width` | integer or null |  |
| `data[].image.height` | integer or null |  |
| `data[].image.content_type` | string or null |  |
| `data[].image.size_bytes` | integer or null |  |
| `data[].video` | GenerationVideo or null |  |
| `data[].video.asset_id` | string or null | The library entry this generation produced. |
| `data[].video.url` | string or null | A short-lived link to the file. Minted per response and not stored — fetch the asset again for a fresh one. |
| `data[].video.width` | integer or null |  |
| `data[].video.height` | integer or null |  |
| `data[].video.duration_seconds` | number or null |  |
| `data[].video.content_type` | string or null |  |
| `data[].video.size_bytes` | integer or null |  |
| `data[].video.has_thumbnail` | boolean or null |  |
| `data[].audio` | GenerationAudio or null |  |
| `data[].audio.asset_id` | string or null | The library entry this generation produced. |
| `data[].audio.url` | string or null | A short-lived link to the file. Minted per response and not stored — fetch the asset again for a fresh one. |
| `data[].audio.duration_seconds` | number or null |  |
| `data[].audio.content_type` | string or null |  |
| `data[].audio.size_bytes` | integer or null |  |
| `data[].audio.peaks` | array of integer or null | Waveform magnitudes, 0-100, for a mirrored strip; null when never computed. |
| `data[].transcript` | GenerationTranscript or null |  |
| `data[].transcript.text` | string or null | The transcript, as one string. |
| `data[].transcript.language_code` | string or null |  |
| `data[].transcript.language_probability` | number or null |  |
| `data[].transcript.duration_seconds` | number or null |  |
| `data[].transcript.word_count` | integer or null |  |
| `data[].transcript.asset_id` | string or null | The library entry holding the full JSON. |
| `data[].transcript.content_type` | string or null |  |
| `data[].transcript.size_bytes` | integer or null |  |
| `data[].transcript.url` | string or null |  |
| `data[].skybox` | GenerationSkybox or null |  |
| `data[].skybox.asset_id` | string or null | The library entry this generation produced. |
| `data[].skybox.url` | string or null | A short-lived link to the file. Minted per response and not stored — fetch the asset again for a fresh one. |
| `data[].skybox.preview_url` | string or null | A short-lived link to the 2K WebP, which is what to load in a 360 viewer. |
| `data[].skybox.width` | integer or null |  |
| `data[].skybox.height` | integer or null |  |
| `data[].skybox.content_type` | string or null |  |
| `data[].skybox.size_bytes` | integer or null |  |
| `data[].skybox.has_thumbnail` | boolean or null |  |
| `data[].skybox.files` | array of SkyboxFile | Every file the environment was stored as, in plan order. |
| `data[].error` | string or null |  |
| `data[].created_at` | string (date-time) |  |
| `data[].finished_at` | string (date-time) or null |  |
| `next_cursor` | string or null | Pass as `cursor` for the next page; `null` when this is the last. |

## Read one generation

`GET /v1/generations/{generation_id}`

Any capability's generation by its `gen_…` id, in the shape the capability's own poll answers. One made under a scope this key does not hold is a 404.

```bash title="curl"
curl "https://api.lumavox.ai/v1/generations/$GENERATION_ID" \
  -H "Authorization: Bearer $API_KEY"
```

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `generation_id` | string | yes |  |

**Responses**

| Status | Description |
|---|---|
| `200` | `application/json` — The generation |
| `400` | The request could not be read: malformed JSON |
| `401` | Missing or invalid credentials |
| `404` | No such generation |
| `422` | The request failed validation |
| `429` | Rate limit exceeded |

**`200` response body**

| Field | Type | Description |
|---|---|---|
| `id` | string | `gen_…`. Poll this. |
| `status` | `"queued"`, `"submitted"`, `"running"`, `"succeeded"`, `"failed"`, `"moderated"` | `queued`, `submitted` and `running` mean keep polling. `succeeded`, `failed` and `moderated` are terminal — stop. |
| `capability` | `"tts"`, `"image"`, `"video"`, `"stt"`, `"skybox"` |  |
| `model` | string or null |  |
| `prompt` | string or null |  |
| `aspect_ratio` | string or null |  |
| `width` | integer or null |  |
| `height` | integer or null |  |
| `output_format` | string or null |  |
| `seed` | integer or null |  |
| `megapixels` | number or null |  |
| `safety_tolerance` | integer or null |  |
| `enhance_prompt` | boolean or null |  |
| `folder_id` | string or null | `fld_…` the result lands in, or null for the root. |
| `duration` | integer or null | Seconds asked for. Video only. |
| `resolution` | string or null | `hd` or `fhd`. Video only. |
| `generate_audio` | boolean or null |  |
| `start_frame` | string or null |  |
| `end_frame` | string or null |  |
| `negative_text` | string or null |  |
| `style_id` | integer or null |  |
| `init_image` | string or null |  |
| `init_strength` | number or null |  |
| `voice_id` | string or null |  |
| `speech` | TTSOptions or null | The voice and model a speech generation ran with. |
| `speech.voice_id` | string | An id from `GET /v1/voices` — the built-in voice, a platform voice, or one your organisation uploaded. |
| `speech.model` | string | Which model speaks: one of the voice's `models` in `GET /v1/voices` — `eleven_flash_v2_5` (the fastest, and the default), `eleven_multilingual_v2` or `eleven_v3`. A model the voice does not list is refused. |
| `speech.provider_options` | ProviderVoiceSettingsInfo or null | The provider's voice settings sent on top of the voice's own; `null` took theirs. |
| `speech.provider_options.stability` | number or null | Low is more expressive and less consistent between generations; high is flatter and more repeatable. |
| `speech.provider_options.similarity_boost` | number or null | How closely to cling to the original voice. High can reproduce artefacts in the source. |
| `speech.provider_options.style` | number or null | Style exaggeration. Costs latency; leave unset on anything conversational. |
| `speech.provider_options.use_speaker_boost` | boolean or null | Similarity at the cost of latency. |
| `speech.provider_options.speed` | number or null | 1.0 is the voice's own pace. |
| `speech.format` | `"wav"`, `"pcm"` |  |
| `speech.sample_rate` | `8000`, `16000`, `22050`, `24000`, `44100` or null | Hz of the returned audio — one of 8000, 16000, 22050, 24000, 44100, each served natively by the provider. Unset means 24000. `POST /v1/tts` says what it produced in the `X-Sample-Rate` header. Queued speech (`POST /v1/audio`) does not take it: each of its formats has its own rate. |
| `credits_micros` | integer or null | What was debited when this was accepted, in micro-credits (1 credit is 1,000,000). A failure refunds it in full; a transcription's is corrected to the measured length when it finishes. |
| `template_id` | string or null |  |
| `image` | GenerationImage or null |  |
| `image.asset_id` | string or null | The library entry this generation produced. |
| `image.url` | string or null | A short-lived link to the file. Minted per response and not stored — fetch the asset again for a fresh one. |
| `image.width` | integer or null |  |
| `image.height` | integer or null |  |
| `image.content_type` | string or null |  |
| `image.size_bytes` | integer or null |  |
| `video` | GenerationVideo or null |  |
| `video.asset_id` | string or null | The library entry this generation produced. |
| `video.url` | string or null | A short-lived link to the file. Minted per response and not stored — fetch the asset again for a fresh one. |
| `video.width` | integer or null |  |
| `video.height` | integer or null |  |
| `video.duration_seconds` | number or null |  |
| `video.content_type` | string or null |  |
| `video.size_bytes` | integer or null |  |
| `video.has_thumbnail` | boolean or null |  |
| `audio` | GenerationAudio or null |  |
| `audio.asset_id` | string or null | The library entry this generation produced. |
| `audio.url` | string or null | A short-lived link to the file. Minted per response and not stored — fetch the asset again for a fresh one. |
| `audio.duration_seconds` | number or null |  |
| `audio.content_type` | string or null |  |
| `audio.size_bytes` | integer or null |  |
| `audio.peaks` | array of integer or null | Waveform magnitudes, 0-100, for a mirrored strip; null when never computed. |
| `transcript` | GenerationTranscript or null |  |
| `transcript.text` | string or null | The transcript, as one string. |
| `transcript.language_code` | string or null |  |
| `transcript.language_probability` | number or null |  |
| `transcript.duration_seconds` | number or null |  |
| `transcript.word_count` | integer or null |  |
| `transcript.asset_id` | string or null | The library entry holding the full JSON. |
| `transcript.content_type` | string or null |  |
| `transcript.size_bytes` | integer or null |  |
| `transcript.url` | string or null |  |
| `skybox` | GenerationSkybox or null |  |
| `skybox.asset_id` | string or null | The library entry this generation produced. |
| `skybox.url` | string or null | A short-lived link to the file. Minted per response and not stored — fetch the asset again for a fresh one. |
| `skybox.preview_url` | string or null | A short-lived link to the 2K WebP, which is what to load in a 360 viewer. |
| `skybox.width` | integer or null |  |
| `skybox.height` | integer or null |  |
| `skybox.content_type` | string or null |  |
| `skybox.size_bytes` | integer or null |  |
| `skybox.has_thumbnail` | boolean or null |  |
| `skybox.files` | array of SkyboxFile | Every file the environment was stored as, in plan order. |
| `skybox.files[].name` | string | `hdr-4k`, `hdr-2k`, `png-8k`, `png-4k`, `png-2k`, `preview-2k`, `depth-2k`. |
| `skybox.files[].content_type` | string |  |
| `skybox.files[].url` | string or null | Short-lived link. Minted per response and not stored. |
| `skybox.files[].width` | integer or null |  |
| `skybox.files[].height` | integer or null |  |
| `skybox.files[].size_bytes` | integer or null |  |
| `error` | string or null |  |
| `created_at` | string (date-time) |  |
| `finished_at` | string (date-time) or null |  |