How to automate AI video generation from code

To automate AI video generation, save the brief that already gives you the video you want as a reusable recipe, start that recipe from code, and collect each finished video through a webhook instead of watching a screen. What starts each run depends on the work: an event in your product, a list to work through, or a clock.

The Sume details below come from the Format API docs and the pages on creating a run, bulk runs and Scheduled, read on 2026-09-27.

What does an automated video pipeline need?

Five parts, whatever service makes the video:

• A fixed recipe. The style, length and rules stay the same on every run; only the data changes.
• A trigger: your backend when something happens, a batch job for a list, or a schedule.
• A spend limit per run, because nobody is there to approve an expensive step.
• A result channel: a webhook that tells your system a video is ready, with polling as the backup.
• A retry rule. A network timeout must never start a second paid video; an idempotency key makes a retried create return the first run.

How do I turn a working prompt into something code can call?

In Sume the recipe is a Format: a saved production recipe your backend calls by name. You author it in the Agents chat, where a person inspects the drafts, and ask the Agent to save the recipe once the output is right. From then on, one POST /v1/formats/{handle}/{slug}/runs starts a run with your data in input, a per-run spend cap, and a webhook. What is a Sume Format? explains the object itself.

Two other entry points fit narrower cases. If the task changes on every call and nothing is worth saving, an Agent Completion (POST /v1/agent/completions) runs the same agent on an instruction you send each time. If you need one clip from one model and nothing else, POST /v1/videos is a single asynchronous model call.

curl -sS -X POST "https://api.sume.com/v1/formats/acme/product-promo/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8823-v1" \
  -d '{
    "instruction": "Vertical 9:16 promo for this product.",
    "input": { "product_url": "https://example.com/p/8823" },
    "generation_spend_cap_usd": 20,
    "communication": { "webhook_url": "https://example.com/hooks/sume" }
  }'

Which trigger should start each video?

Pick by what starts the work. The docs draw the line between events and clocks: call a Format from your backend when your user does something, and reach for a schedule when nothing triggers the work except the clock.

What happens when nobody is watching the run?

A recipe written in chat may pause for a person, for example to approve stills before paying for the video. Over the API nobody is there, so the run is told those approvals are already granted and carries on to the paid step within its spend cap.

A run that truly cannot finish without a person comes back failed with the code unattended_blocked, never as a half-finished completed. Fix the input or the brief, then retry with a new Idempotency-Key. A Format run can never spend past its effective cap, so set generation_spend_cap_usd on every create; spend caps for unattended AI agents covers sizing.

How do I get each finished video without polling?

Send communication.webhook_url on the create. Sume POSTs the terminal receipt once, when the run completes or fails, signed with HMAC-SHA256 over the timestamp and the raw body. The receipt's primary_output_url is the one thing to show, and media URLs are durable media.sume.com HTTPS URLs that don't expire.

Keep a read of result_url as the backup for the day your endpoint is down, and remember that canceled and skipped runs never send a webhook. Signed webhooks for video runs walks through verification.

What can't be automated this way?

• Creating or editing a schedule. The Developer API can list schedules, start runs and monitor them, but it cannot create or edit one; that happens in the dashboard or by asking the Agent in chat.
• Live progress. There is no push channel for progress; a Format run's events_url is a polled phase timeline, not agent output.
• Judging the video. A non-null primary_output_url tells you the deliverable exists, not that it is right. Review samples before you scale a recipe up; verifying run output lists what Sume checks.
• Instant results. Runs that make video take minutes, not seconds, and long-form host video typically finishes in 15 to 30 minutes.