Reference

run_template

Run a template

POST /api/v2/run_template

Runs one of the ready-made recipes from GET /templates (product ad, video template, talking head, podcast) as one job. Use dry_run: true for the price. Needs the generate scope.

Auth: API key (Authorization: Bearer)
Key scope needed: generate
Raw spec: https://app.diffusr.ai/api/v2/openapi.json

Headers

Name	Type	Required	Description
`Idempotency-Key`	string	no	1-255 visible ASCII characters you make up for this request (a UUID is fine). Send the same key to retry safely: you get the first job back instead of paying twice. Reusing a key for a different request answers 409 IDEMPOTENCY_CONFLICT. Wins over `idempotency_key` in the body.

Request body (JSON)

Name	Type	Required	Description
`template`	string	yes	The template’s id, from list_templates.
`mode`	“remix” \| “recast”	no	Video templates only. “remix” (default) = make a new video like the template, from your pictures and prompt. “recast” = keep the template’s moves and swap who is in it for your image_urls.
`prompt`	string	no	Product ads: an optional change to the ad (“make it a winter sale”). Video templates: remix = your version of the template’s prompt (leave out to use the template’s own); recast = what to change.
`pictures`	map of string	no	Video template remix: one picture per slot, keyed by the slot name from list_templates (e.g. {“him”: “https://…”}).
`image_urls`	string[]	no	Video template recast: photos of who should appear in the clip.
`product_image_url`	string	no	Product ads: a photo of your product, uploaded with upload_asset. Talking head: optional, shows the product on camera.
`script`	string	no	Talking head: what the person says, word for word. Podcast: one line per turn, written “Name: what they say”, the names exactly as in people. Everything must fit one 30 s take.
`place`	string	no	Talking head: where they are, in a few words, e.g. “a small Paris hotel room with a tall window”.
`people`	object[]	no	Talking head: one person. Podcast: two hosts, the first sits on the left.
`people[].name`	string	yes	What the script calls them, e.g. “Mia”. Plain first names work best.
`people[].image_url`	string	yes	A clear photo of their face. A public link — upload_asset gives one for a local file.
`people[].look`	string	no	Optional. Age, hair and outfit in a few words, e.g. ”30s, short dark hair, green jacket”. Leave out to keep what the photo shows.
`setup`	“selfie” \| “propped” \| “friend”	no	Talking head on the plain template: how it is filmed — “selfie” (default), “propped” or “friend”.
`resolution`	“480p” \| “720p”	no	Leave out for the template’s own default. 480p costs less.
`dry_run`	boolean	no	true = only check the request and return the price in credits. Nothing is made, nothing is spent.
`idempotency_key`	string	no	A unique string you make up for this request. Retry with the same key and you get the first result back instead of paying again.
`callback_url`	string	no	Optional. A public https:// link. When the job finishes (done, failed or canceled) we POST the finished result here, signed. See the docs for checking the signature. Polling get_result still works.

Example

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"
    }
  ]
}'

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",
    },
  ],
});
const result = await d.waitFor(job.id);
console.log(result.output?.url);

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",
        },
    ],
)
result = d.wait_for(job["id"])
print(result["output"]["url"])

The same call as a dry run (the price, nothing made, nothing spent):

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

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

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

Response

200 ApiDryRun

dry_run was true: the price, nothing made, nothing spent.

Name	Type	Required	Description
`dry_run`	true	yes
`test`	true	no	true when a test key made the call: the price is real, nothing real ran. Absent for live keys.
`credits_estimated`	number	yes
`price`	object	no
`price.credits`	number	yes	The most this call costs, in whole credits (1 credit = $0.01).
`price.usd`	string	yes	The same price in US dollars, e.g. “0.0336”.
`price.tariff`	“direct” \| “outcome”	yes	“direct” = your prompt goes to the model as sent; “outcome” = a result we shape (Recast, creator video).
`price.tariff_version`	string	yes
`price.expires_at`	string	yes	The quoted price holds until then (ISO time).
`duration_sec`	number	no
`warnings`	string[]	no
`note`	string	yes

202 ApiStarted

The job started. Poll GET /results/{id}.

Name	Type	Required	Description
`id`	string	yes	The job id. Poll GET /results/{id} with it, or wait for the callback.
`status`	string	yes	“PENDING” on a new start; the run’s current status when a retried Idempotency-Key replays the first job.
`credits_estimated`	number	yes	The most this job can cost, in credits.
`idempotent_replay`	true	no	true when this is the FIRST job again, answering a retried Idempotency-Key.
`test`	true	no	true when a test key made the call: the price is real, nothing real ran. Absent for live keys.
`price`	object	no	The price, locked in at start.
`price.credits`	number	yes	The most this call costs, in whole credits (1 credit = $0.01).
`price.usd`	string	yes	The same price in US dollars, e.g. “0.0336”.
`price.tariff`	“direct” \| “outcome”	yes	“direct” = your prompt goes to the model as sent; “outcome” = a result we shape (Recast, creator video).
`price.tariff_version`	string	yes
`price.expires_at`	string	yes	The quoted price holds until then (ISO time).
`duration_sec`	number	no
`warnings`	string[]	no	Heads-ups that did not stop the call.
`next`	string	yes	What to do next, in words.

Errors

Every error body is { error, code, request_id, ... }. All codes and what to do.

401: Missing, wrong, revoked or expired API key (code UNAUTHORIZED, KEY_REVOKED, KEY_EXPIRED).
402: Not enough credits, or an API budget would be passed (INSUFFICIENT_CREDITS, BUDGET_EXCEEDED).
403: The key may not do this (SCOPE_DENIED, MODEL_NOT_ALLOWED, TEST_MODE_UNSUPPORTED, ACCOUNT_BLOCKED, allowance_exceeded).
409: IDEMPOTENCY_CONFLICT or CALLBACK_NOT_RETRYABLE.
413: The request or file is too large (TOO_LARGE, REFERENCE_TOO_LARGE).
422: The request is not valid (VALIDATION_FAILED, INVALID_JSON, PREFLIGHT_FAILED, CALLBACK_URL_INVALID, REFERENCE_*). `issues` lists each problem. Nothing was charged.
429: Too many requests or jobs (RATE_LIMITED, CONCURRENCY_LIMIT, UPLOAD_QUOTA, …). Wait Retry-After seconds, then retry.
500: Our fault (INTERNAL_ERROR). Quote request_id to support.
503: Paused or busy (API_PAUSED, MODEL_PAUSED, PROVIDER_PAUSED, PROVIDER_BUSY, UNAVAILABLE). Wait Retry-After seconds, then retry.

Charges

Costs credits (1 credit = $0.01). Send `dry_run: true` first: it answers with the price and spends nothing. You are charged when the result is delivered and never more than the quoted price. Work that fails, is canceled before it runs, or is never delivered is not charged. A test key quotes the same price and charges nothing. It is priced at the outcome rate: a result we shape for you, so the rate is higher than the model prices on the Prices page. Use `dry_run: true` for the exact price.