# Templates

> run_template makes a whole ad, template video, talking head or podcast as one job. List what is runnable, price it, run it.

## The three calls

1. `GET /templates` (`list_templates` in MCP) lists what you can run, the inputs each takes, and an approximate price.
2. `POST /run_template` with `dry_run: true` gives the exact price. The price in the list is only a hint.
3. The same call without `dry_run` starts it. It is **one job**: poll `GET /results/{id}` or use a [callback](https://diffusr.ai/docs/callbacks), like any other tool.

**cURL**

```bash
curl "https://app.diffusr.ai/api/v2/templates" \
  -H "Authorization: Bearer $DIFFUSR_KEY"
```

**TypeScript**

```ts
import { Diffusr } from "diffusr";

const d = new Diffusr(); // reads DIFFUSR_KEY
const { templates } = await d.listTemplates();
console.log(templates.map((t) => t.id));
```

**Python**

```python
from diffusr import Diffusr

d = Diffusr()  # reads DIFFUSR_KEY
data = d.list_templates()
print([t["id"] for t in data["templates"]])
```

## What can be run

| Kind | What it makes | What it needs |
| --- | --- | --- |
| Product ad | A 20 to 30 second ad from a product photo | `template`, `product_image_url` (your own file from `upload_asset`); `prompt` optional |
| Video template (Remix) | A new video in the style of a published template | `template`; `pictures` for its slots; `prompt` optional |
| Video template (Recast) | The template's moves with your people in them | `template`, `mode: "recast"`, `image_urls`, `prompt` (what to change) |
| Talking head | One person saying your script to camera, one take | `template`, `script`, `place`, `people` (one); `setup` optional |
| Podcast | Two hosts in a studio, one take | `template`, `script`, `people` (two) |

Talking head and podcast are a single take of up to 30 seconds (15 seconds for the "propped" setup). Everything the script says must fit.

A field a template does not take is refused by name, and nothing is charged. `GET /templates` shows each template's inputs; a Remix picture slot appears as `pictures.<slot>`.

## Fields

Only `template` is required for every call. The full list, with types, is on the [run_template](https://diffusr.ai/docs/reference/run_template) page; in short:

- `template`: the id from `GET /templates`.
- `mode`: `"remix"` (default) or `"recast"`. Video templates only.
- `prompt`: product ad, an optional change ("make it a winter sale"). Remix, your version of the template's prompt (leave out to use the template's own). Recast, what to change.
- `pictures`: Remix. One picture per slot, keyed by slot name.
- `image_urls`: Recast. Photos of who should appear.
- `product_image_url`: product ad (required) or talking head (optional, shows the product on camera).
- `script`: talking head, the words exactly as said. Podcast, one line per turn written `Name: what they say`, names exactly as in `people`.
- `place`: talking head. Where they are, in a few words.
- `people`: `[{ name, image_url, look? }]`. One for a talking head, two for a podcast (the first sits on the left).
- `setup`: plain talking head only. `"selfie"` (default), `"propped"` or `"friend"`.
- `resolution`: `"480p"` or `"720p"`. 480p costs less.
- `dry_run`, `idempotency_key`, `callback_url`: as on every make call.

There is no `duration_sec`: the template or the script sets the length.

**cURL**

```bash
curl -X POST https://app.diffusr.ai/api/v2/run_template \
  -H "Authorization: Bearer $DIFFUSR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "template": "tpl-talking-head",
  "script": "I tried this for a week and I am not going back.",
  "place": "a small Paris hotel room with a tall window",
  "people": [
    {
      "name": "Mia",
      "image_url": "https://example.com/mia.jpg"
    }
  ],
  "dry_run": true
}'
```

**TypeScript**

```ts
import { Diffusr } from "diffusr";

const d = new Diffusr(); // reads DIFFUSR_KEY
const job = await d.runTemplate({
  template: "tpl-talking-head",
  script: "I tried this for a week and I am not going back.",
  place: "a small Paris hotel room with a tall window",
  people: [
    {
      name: "Mia",
      image_url: "https://example.com/mia.jpg",
    },
  ],
  dry_run: true,
});
console.log(job); // the price, nothing was made
```

**Python**

```python
from diffusr import Diffusr

d = Diffusr()  # reads DIFFUSR_KEY
job = d.run_template(
    template="tpl-talking-head",
    script="I tried this for a week and I am not going back.",
    place="a small Paris hotel room with a tall window",
    people=[
        {
            "name": "Mia",
            "image_url": "https://example.com/mia.jpg",
        },
    ],
    dry_run=True,
)
print(job)  # the price, nothing was made
```

## Price

`run_template` runs at the **outcome rate**, which is higher than the per-model rates on [Prices](https://diffusr.ai/docs/prices), because we plan and run the whole recipe for you. Always `dry_run` first.

## Other looks

Animation looks (claymation, LEGO and others) and the multi-take talking-head chain are not `run_template` kinds. They are recipes you follow with the direct tools: with MCP, each is a prompt and a resource (`diffusr://templates/...`) that lists the exact `make_image` and `make_video` calls. See [MCP and skills](https://diffusr.ai/docs/mcp-and-skills).

Test keys cannot run video templates (`TEST_MODE_UNSUPPORTED`).

Source: https://diffusr.ai/docs/templates