A Sume Format is a saved production recipe for one kind of video: a house style, an output contract, and a playbook the agent follows. Your backend calls it by handle and slug with one HTTP request. Sume runs it in a fresh sandbox with the generation tools and returns finished media on media.sume.com, plus a JSON object in a shape you define when you ask for one.
This post explains where a Format comes from, what one run does, and how to call it. Every API detail below comes from the Format API docs.
Where does a Format come from?
You author a Format in the Agents tab. Brief the agent, review the draft, iterate until the output is right, then tell it to save the recipe: “Save this as a Format called product-promo.” The saved Format is a SKILL.md body plus reference files, addressable by your handle and the slug you chose.
The chat thread is where a person stays in the loop. The Format is what your systems call once the recipe is settled.
What does one Format run do?
A run is one unattended agent turn with the Format attached. It does not stop to ask a person anything; approvals a chat-authored recipe would request are pre-granted, and the run carries on within its spend cap.
- Your request is accepted with
202and a receipt that carriesstatus_url,result_url,events_url, andcancel_url. - A fresh sandbox boots and the Format's package lands on disk.
- The agent follows the recipe and calls generation tools: host takes, B-roll, voiceover, captions, timeline assembly.
- Media is mirrored to media.sume.com. The URLs are durable and public, so you can store them.
- You get the terminal receipt by a signed webhook (
format.run.terminal) or by polling.
How do I call a Format from my backend?
Create an API key with the formats:read and formats:write scopes at API keys, keep it server-side, then create a run. Send an Idempotency-Key derived from the thing being made (an order id plus a version), not a fresh UUID per request, so a retry never starts a second run.
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, 15 seconds. Use the product page as the brief.",
"input": { "product_url": "https://shop.example.com/p/8823" },
"generation_spend_cap_usd": 20,
"communication": { "webhook_url": "https://acme.example.com/hooks/sume" }
}'What can a request control?
| Field | What it does |
|---|---|
instruction | The task in your words, up to 8,000 characters. Omit it to run the Format's default instruction. |
input | Caller data as a JSON object: at most 64 top-level keys and 2 MiB. |
output_schema | Bind a JSON Schema and output comes back in that shape. See Structured output. |
generation_spend_cap_usd | This run's generation ceiling, up to the platform maximum of $500. Omit it to inherit the Format's cap. |
communication.webhook_url | Public HTTPS URL that receives one signed POST when the run completes or fails. |
previous_run_id | Continue an earlier run of this Format as another turn instead of starting fresh. |
Can I get typed JSON back instead of a paragraph?
Yes. By default a completed run returns media and some text. Bind output_schema (or its OpenAI-shaped alias response_format) and the run's output is projected onto your schema, so you can write it straight into your own records. Media fields reference a SumeMediaFile with the durable URL. The supported keywords and every failure mode are on the Structured output page.
How do I run a Format many times?
Use a bulk queue. One request carries 1 to 100 items, each the same body as a single run, and a concurrency window of 1 to 16 runs in flight at once. A bulk request is a server-side queue of ordinary runs, not a different engine. Details: Bulk runs.
Format, Agent Completion, or Scheduled?
All three run the same agent and return the same receipt shape. They differ in where the instruction comes from and what Sume has saved for you.
| Surface | Use it when | Start with |
|---|---|---|
| Format | You have a saved workflow and only the inputs change. | POST /v1/formats/{handle}/{slug}/runs |
| Scheduled | You need a schedule or trigger on a saved automation. | POST /v1/actions/{handle}/{slug}/runs |
| Agent Completion | The task itself changes on every call. | POST /v1/agent/completions |
What does it cost, and who can use it?
Formats are included on paid plans. A run draws from your workspace's one balance at each model's published rate, and it can never spend past its effective cap; the receipt reports both the cap and what the run actually spent. Plans are on Pricing and per-model rates on API pricing.
Runs that make video take minutes, not seconds, so design for the asynchronous path from the start: take the webhook, or poll the status_url on the receipt.