Images and video

Templates

Run a generation someone has already designed — fill in a picture or a prompt, pay the price quoted up front, and poll the result like any other.

A template is a generation that is already designed: the prompt, the size, the style and every other parameter are fixed by its author. It leaves a few inputs open for you — usually a picture or two, sometimes the prompt — and because everything else is decided, its price is known before you run it.

Templates make images, video or skyboxes. Running one is an ordinary generation: it answers with a gen_… id that you poll on the capability’s own endpoint, and the result lands in your asset library.

Find a template

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

{
  "data": [
    {
      "id": "tpl_a1B2c3D4e5F6g7H8",
      "name": "Studio product shot",
      "description": "Your product on a seamless backdrop, softbox lighting.",
      "capability": "image",
      "inputs": [
        {
          "slot": "reference_1",
          "kind": "image",
          "label": "Your product",
          "hint": "A clear photo on any background",
          "required": true,
          "example_url": "https://…",
          "example": null
        }
      ],
      "example_url": "https://…",
      "credits_micros": 4000000,
      "fixed_megapixels": 0,
      "parameters": { "aspect_ratio": "1:1", "megapixels": 1, "output_format": "jpeg" },
      "exposed": ["aspect_ratio"],
      "created_at": "2026-10-01T12:00:00.000Z",
      "updated_at": "2026-10-01T12:00:00.000Z"
    }
  ],
  "next_cursor": null
}

Any valid key can read the gallery. GET /v1/templates/{template_id} reads one. Every published template is in one page: next_cursor is always null (Conventions).

What each field tells you:

Field	Meaning
`capability`	What it makes — `image`, `video` or `skybox`. It decides which scope your key needs and which endpoint you poll.
`inputs`	The slots you fill, in the order to show them. Each has a `slot` name, a `kind`, a `label` and maybe a `hint`.
`inputs[].kind`	`image` takes an `ast_…` id from your library; `text` takes your words — usually the prompt.
`inputs[].required`	Whether you must fill it.
`inputs[].example_url`, `inputs[].example`	What the example output was made from — a picture for an `image` input, text for a `text` one.
`example_url`	A real output, made from those example inputs.
`credits_micros`	What one run costs your organisation, at the template’s defaults, in micro-credits (Conventions). `null` if the platform has no price for that capability.
`fixed_megapixels`	On an image template, the megapixels of the pictures the template sends itself, already counted in `credits_micros`. `0` on video and skybox templates, whose price no picture changes.
`parameters`	The request the template fixed, minus the prompt.
`exposed`	The parameters you may override, by name.

Run it

POST /v1/templates/{template_id}/generate with each input you are filling, by slot name:

curl https://api.lumavox.ai/v1/templates/tpl_a1B2c3D4e5F6g7H8/generate \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": { "reference_1": "ast_Z9y8X7w6V5u4T3s2" },
    "parameters": { "aspect_ratio": "16:9" },
    "folder_id": "fld_a1B2c3D4e5F6g7H8"
  }'

The answer is a 202 with a generation, exactly as POST /v1/images (or /v1/videos, /v1/skybox) would give, with template_id set:

{
  "id": "gen_Q9r8S7t6U5v4W3x2",
  "status": "queued",
  "capability": "image",
  "aspect_ratio": "16:9",
  "folder_id": "fld_a1B2c3D4e5F6g7H8",
  "credits_micros": 4000000,
  "template_id": "tpl_a1B2c3D4e5F6g7H8",
  "image": null,
  "error": null,
  "created_at": "2026-10-24T10:02:44.310Z",
  "finished_at": null
}

Then poll it on the endpoint for the template’s capability:

`capability`	Poll
`image`	`GET /v1/images/{id}` — see Images
`video`	`GET /v1/videos/{id}` — see Video
`skybox`	`GET /v1/skybox/{id}` — see Skyboxes

The body

Field	What it is
`inputs`	Slot name → value: an `ast_…` asset id for an `image` input, text for a `text` one. Every `required` input must be present.
`parameters`	Overrides for the parameters listed in `exposed`, by name, as the capability’s own route takes them — for example `{"megapixels": 2}` on an image template.
`folder_id`	The `fld_…` folder in your library the result goes in. Omit it for the root.

Scope

The key needs the template’s capability scope, not a scope of its own: a key that may make images may run image templates. Running a video template with an image-only key is a 403.

Reference images are sized for you

An image template shares a 9-megapixel budget between its output, any pictures the template fixes and your references. If your photo is too large to fit, a smaller stored copy of it is sent instead, so you never pick the size. Only when even the smallest copies do not fit is the run refused, with a 422.

Price

Charged when accepted, at the price the listing showed. credits_micros on the 202 is what was charged.
An exposed size, duration or resolution changes the price. The listing quotes the template’s defaults; override megapixels, duration or resolution and the 202 tells you the new figure.
Your pictures are charged on top, on an image template. The listing includes the pictures the template fixes; each of yours is charged at the output’s per-megapixel rate, on the copy sent, and the 202 includes them.
To estimate an image run before you send it, price it per megapixel: credits_micros divided by the default output’s megapixels (at least 1) plus fixed_megapixels is your rate. A run costs that rate times the output’s megapixels (at least 1), plus fixed_megapixels, plus your own pictures’ megapixels at the size they are sent.
Refunded in full if the generation fails.
Nothing is charged for a request refused with a 4xx.

Example images

Use example_url and inputs[].example_url as given rather than building them. They point either at public storage or at the API’s own GET /v1/templates/{template_id}/files/{name} — a path you prefix with https://api.lumavox.ai when it does not start with https://.

That route needs no key: every customer sees the same templates. name is example for the example output, or input-<slot> for the example beside one input. Its v query parameter makes the response safe to cache forever, so keep it on the link.

Errors

Status	When
400	The body is not valid JSON.
422	An input names an asset that is missing, is not yours, is not an image, or is still being processed; or `folder_id` is not one of your folders.
402	Your organisation has run out of credits, or this job’s estimate would take its balance past the grace buffer. Nothing is charged.
403	The key does not hold the template’s capability scope.
404	No published template with that id.
422	A required input is missing, an input the template does not open was sent, an `image` slot was given something that is not an asset id, or `parameters` names one the template does not expose — or a value the capability itself refuses.
429	Too many requests, or too many generations of that capability already running. Nothing was charged.

Every refusal comes before anything is charged. See Errors and limits for the error shape.