Run a ready-made recipe

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, like any other tool.

cURL

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

TypeScript

import { Diffusr } from "diffusr";

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

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 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

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

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

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, 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.

Test keys cannot run video templates (TEST_MODE_UNSUPPORTED).