Format run, schedule or Agent Completion for repeatable holiday ads

Use a Format when you have a saved recipe and only the inputs change, such as a product URL per SKU. Use Scheduled when a cadence starts the work, and Agent Completions when the task is different on every call. For a holiday ad batch, that nearly always means a Format.

The three share one run engine and one receipt shape, so the choice is about where the instruction lives, not about what the agent can do.

The three surfaces

Sume's Agent Completions docs put it in one table. A Format stores how to do the work. A schedule stores what to do and when. An Agent Completion stores nothing, and you send the task each time.

Why a Format fits ad batches

A Format is a saved production recipe: a house style, an output contract and a playbook for one kind of video. Your backend calls it by name, Sume runs it in a fresh sandbox with the generation tools, and you get media on media.sume.com. If you ask for it, you also get JSON in a shape you define.

That is the repeatable part. The recipe is set before your instruction, so you do not re-send a system prompt on every call and hope it holds. For ads, the inputs are things like a product URL, a host image and a language. The Format catalog lists ready-made first-party Formats at the sume handle that any key with formats:write can call without forking.

Runs, queues and caps

A Format run is one unattended turn. It does not stop to ask questions, and approvals that a chat-authored recipe would ask for are pre-granted within the spend cap. That makes it right for a backend and wrong for a person who wants to steer.

For many items, a bulk request is a server-side queue of ordinary runs: concurrency from 1 to 16 and 1 to 100 items, per the bulk runs docs. The queue has no webhook, so each item carries its own, or you poll. completed on the queue means every item is terminal, not that all succeeded, so branch on the failed count.

Plan for minutes, not seconds

Runs that make video take minutes. The Format API docs say long-form host video usually completes in 15 to 30 minutes, so design for the asynchronous path from the start.

When not to use a Format

If your holiday work is a one-off, such as a single brand film, an Agent Completion is simpler: send the brief, poll the receipt, collect the media. generation_spend_cap_usd has no default there, so a request without it fails. If it is a cadence, such as a countdown post every day from a given date, a schedule is the fit. Schedules can be listed, read and started through the API, but they are created in the Agents dashboard or by asking the Agent in chat, not through the API.

Pick one and write the cap down. Whichever surface you choose, the cap is the number the finance team will ask about.

A rule for choosing

A short decision rule helps when a team argues about this. Count how many times the instruction will be the same. If the answer is 'every time except the product', you want a Format, since you pay once to write the recipe and then only send inputs. If the answer is 'never the same', you want an Agent Completion. If the answer is 'same, on a clock', you want a schedule.

Holiday work usually starts as the third case and turns into the first. The first week of November is a pile of one-off asks. By the second week you have noticed that eight of them are the same ad with a different product. That is when you stop sending free-form prompts and save the recipe.

What the receipt and keys look like

Each surface returns the same receipt: a status URL, a result URL, an events URL and a cancel URL. A Format run also accepts an output_schema, which projects the run output onto your own shape, so your code can read headline text, caption lines or a file list from known fields and not parse prose. That is the difference between a demo and an integration.

Whichever surface you pick, the keys need the right scopes: formats:read and formats:write for Formats, and agent_completions:read and agent_completions:write for Agent Completions. Keys created before those features shipped do not carry them, and scopes cannot be added to an existing key, so create a new one. Service-account keys cannot create Format runs or Agent Completions.

One more caution: a team-owned Format needs a key issued in that team workspace. A personal key from a team member is refused with 403 workspace_key_required. Agencies running Black Friday for several clients will hit this on day one.