# 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](https://docs.lumavox.ai/library/assets.md).

## Find a template

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

```json title="Response"
{
  "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](https://docs.lumavox.ai/conventions.md#lists-and-pages)).

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](https://docs.lumavox.ai/conventions.md#credits)). `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:

```bash title="curl"
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:

```json title="Response — 202 Accepted (abridged)"
{
  "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](https://docs.lumavox.ai/media/images.md) |
| `video` | `GET /v1/videos/{id}` — see [Video](https://docs.lumavox.ai/media/videos.md) |
| `skybox` | `GET /v1/skybox/{id}` — see [Skyboxes](https://docs.lumavox.ai/media/skyboxes.md) |

### 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](https://docs.lumavox.ai/errors.md) for the error shape.

## See also

- [Generations](https://docs.lumavox.ai/library/generations.md) — template runs appear there with their `template_id`.
- [The templates reference](https://docs.lumavox.ai/reference/templates.md) — every field.