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.
List generations
Section titled “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.
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
Section titled “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.
curl "https://api.lumavox.ai/v1/generations/$GENERATION_ID" \ -H "Authorization: Bearer $API_KEY"Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
generation_id | string | Required |
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 |