Generations

Every queued request — an image, a clip, a skybox, stored speech, a transcription — is a generation with a gen_… id. Each capability has its own poll (GET /v1/images/{id} and so on); /v1/generations is the one place that reads them all.

Use it to:

• Recover an id you lost — a crash between the 202 and storing the id, say.
• Reconcile — find everything still running, or everything that failed, since you last looked.
• Show a history across capabilities in one list.

curl

curl "https://api.lumavox.ai/v1/generations?status=running" \
  -H "Authorization: Bearer $API_KEY"

Response (abridged)

{
  "data": [
    {
      "id": "gen_a1B2c3D4e5F6g7H8",
      "status": "running",
      "capability": "video",
      "prompt": "Waves rolling onto a black sand beach at dusk",
      "duration": 5,
      "resolution": "hd",
      "credits_micros": 25000000,
      "video": null,
      "error": null,
      "created_at": "2026-10-24T09:20:11.502Z",
      "finished_at": null
    }
  ],
  "next_cursor": null
}

Each item is the same object the capability’s own poll answers, with every field — Images shows them all, and Queued jobs the statuses.

List generations

GET /v1/generations returns your organisation’s generations newest first, in flight or finished.

Query	What it does
limit	Page size, 1–100. Default 30.
cursor	The next_cursor from the previous page.
capability	Only one capability: image, video, tts (stored speech), stt (transcription) or skybox. Anything else is a 422.
status	Only one state: queued, submitted, running, succeeded, failed or moderated.

The answer is a page: pass each response’s next_cursor back as cursor until it comes back null (Conventions). A cursor this list did not give is a 422.

curl

curl "https://api.lumavox.ai/v1/generations?capability=image&status=failed&limit=100" \
  -H "Authorization: Bearer $API_KEY"

Finished items carry a short-lived link to their file, made fresh on each response — as on every poll. The file itself stays in your asset library.

What a key sees

The list shows only the capabilities your key holds. A key with the image scope sees images; one with tts sees stored speech; the master key sees everything. Asking for a capability the key does not hold gives an empty page, not a 403 — and so does a key with no generation scope at all.

The scopes behind each capability:

capability	Scope
image	image
video	video
skybox	skybox
tts	tts
stt	stt

Read one generation

GET /v1/generations/{generation_id} reads any capability’s generation by id, in exactly the shape that capability’s poll answers.

curl

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

It is useful when you hold an id but not its capability. A generation made under a scope this key does not hold, one that belongs to another organisation, and one that does not exist are all the same 404.

Reconciling

The pattern for a service that submits work and must not lose track of it:

1. Store the gen_… id from every 202 before doing anything else.
2. Poll each one on its capability’s endpoint until it is terminal.
3. On start-up, or on a schedule, list ?status=queued, ?status=submitted and ?status=running to pick up anything your process dropped, and ?status=failed or ?status=moderated to see what was refunded.

Every generation records what was asked for — prompt, size, seed, folder_id, template_id and the rest — and credits_micros, what was debited when it was accepted, as an integer of micro-credits (Conventions). A failed or moderated generation is refunded in full, and error says why.

See also

• Queued jobs — the statuses and the polling loop.
• Assets — the files the generations produced.
• Credits and usage — what was spent.
• The generations reference — every field.