Formats

curl https://vidlab.ai/v1/formats

import requests

for f in requests.get("https://vidlab.ai/v1/formats").json()["data"]:
    print(f["id"], [i["name"] for i in f["inputs"]])

const { data: formats } = await (await fetch("https://vidlab.ai/v1/formats")).json();
for (const f of formats) console.log(f.id, f.inputs.map((i) => i.name));

{
  "object": "format",
  "id": "talking-head-ugc",
  "name": "Talking Head UGC",
  "description": "A creator talks to camera about your product, shot like a phone video.",
  "kind": "video",
  "minutes": 6,
  "inputs": [
    { "name": "product_image", "type": "image", "required": false, "description": "A clear photo of the product." },
    { "name": "brief", "type": "text", "required": false, "description": "What the ad should say, in a sentence or two.", "max_length": 2000 },
    { "name": "length_seconds", "type": "choice", "required": false, "options": ["15", "30", "45", "60"], "default": "30" },
    { "name": "hooks", "type": "choice", "required": false, "description": "How many opening hooks to make, one video each.", "options": ["1", "3", "5"], "default": "3" }
  ],
  "price": { "rule": "quoted_per_run", "from_usd": 7.07, "note": "Every run is quoted for its own inputs before it starts." },
  "questions_it_may_ask": [
    { "id": "brief", "text": "What is the ad about? Name the product and the one thing the creator should say.", "type": "text", "required": true },
    { "id": "confirm_price", "text": "This video costs $X. Start it?", "type": "choice", "options": ["approve", "cancel"], "required": true }
  ]
}

curl -X POST https://vidlab.ai/v1/formats/talking-head-ugc/runs \
  -H "Authorization: Bearer $VIDLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-talking-head" \
  -d '{ "inputs": { "length_seconds": "15", "hooks": "1" } }'

import os, requests

H = {"Authorization": f"Bearer {os.environ['VIDLAB_API_KEY']}"}
run = requests.post(
    "https://vidlab.ai/v1/formats/talking-head-ugc/runs",
    headers={**H, "Idempotency-Key": "order-1042-talking-head"},
    json={"inputs": {"length_seconds": "15", "hooks": "1"}},
).json()

const res = await fetch("https://vidlab.ai/v1/formats/talking-head-ugc/runs", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VIDLAB_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "order-1042-talking-head",
  },
  body: JSON.stringify({ inputs: { length_seconds: "15", hooks: "1" } }),
});
let run = await res.json();

{
  "object": "format_run",
  "run_id": "fmtrun_6f1c2a7d9b3e4f50a1c2d3e4f5a6b7c8",
  "format": { "id": "talking-head-ugc", "name": "Talking Head UGC" },
  "status": "needs_input",
  "questions": [
    { "id": "brief", "text": "What is the ad about? Name the product and the one thing the creator should say.", "type": "text", "required": true }
  ],
  "inputs": { "length_seconds": "15", "hooks": "1" },
  "price": { "quoted_usd": null, "max_price_usd": null, "charged_usd": null },
  "progress": null,
  "output": null,
  "error": null,
  "next_action": "Answer the questions with POST answers_url.",
  "created_at": "2026-11-01T18:20:04.112Z",
  "updated_at": "2026-11-01T18:20:04.131Z",
  "completed_at": null,
  "status_url": "/v1/formats/runs/fmtrun_6f1c2a7d9b3e4f50a1c2d3e4f5a6b7c8",
  "answers_url": "/v1/formats/runs/fmtrun_6f1c2a7d9b3e4f50a1c2d3e4f5a6b7c8/answers",
  "cancel_url": "/v1/formats/runs/fmtrun_6f1c2a7d9b3e4f50a1c2d3e4f5a6b7c8/cancel"
}

{ "id": "confirm_price", "text": "This video costs $X. Start it?", "type": "choice", "options": ["approve", "cancel"], "required": true }

curl -X POST https://vidlab.ai/v1/formats/runs/fmtrun_6f1c2a7d9b3e4f50a1c2d3e4f5a6b7c8/answers \
  -H "Authorization: Bearer $VIDLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "answers": { "brief": "Sleep gummies: asleep in 20 minutes, no grogginess." } }'

run = requests.post(
    f"https://vidlab.ai/v1/formats/runs/{run['run_id']}/answers",
    headers=H,
    json={"answers": {"brief": "Sleep gummies: asleep in 20 minutes, no grogginess."}},
).json()

run = await (
  await fetch(`https://vidlab.ai/v1/formats/runs/${run.run_id}/answers`, {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.VIDLAB_API_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({ answers: { brief: "Sleep gummies: asleep in 20 minutes, no grogginess." } }),
  })
).json();

curl https://vidlab.ai/v1/formats/runs/fmtrun_6f1c2a7d9b3e4f50a1c2d3e4f5a6b7c8 \
  -H "Authorization: Bearer $VIDLAB_API_KEY"

import time

while run["status"] in ("queued", "running"):
    time.sleep(15)
    run = requests.get(f"https://vidlab.ai/v1/formats/runs/{run['run_id']}", headers=H).json()
print(run["status"], [v["url"] for v in (run.get("output") or {}).get("videos", [])])

while (run.status === "queued" || run.status === "running") {
  await new Promise((r) => setTimeout(r, 15000));
  run = await (await fetch(`https://vidlab.ai/v1/formats/runs/${run.run_id}`, { headers: { Authorization: `Bearer ${process.env.VIDLAB_API_KEY}` } })).json();
}
console.log(run.status, run.output?.videos.map((v) => v.url));

"output": {
  "videos": [
    {
      "kind": "video",
      "url": "https://...",
      "mime_type": "video/mp4",
      "duration_seconds": 15.2,
      "label": "Hook A",
      "expires_at": "2026-11-02T00:31:10.000Z"
    }
  ],
  "duration_seconds": 15.2
}

POST https://example.com/vidlab-hook
Content-Type: application/json
X-Vidlab-Event: format_run.succeeded

{ "event": "format_run.succeeded", "run": { "object": "format_run", "run_id": "fmtrun_...", "status": "succeeded" } }