Format catalog

A Format is a saved authoring recipe an Agent applies to a run. Sume ships a first-party catalog of them, so a production workflow can be one HTTP call rather than a prompt you maintain.

These pages are written for the caller. They cover what the Format does, what to send, and how to read the result — not how to author one.

FormatUse it whenPage
Product promoYou have a product or brand URL and want ad images or a promo video in a fixed house style.Product promo
Avatar UGC videoYou have a script and want a talking-head creator-style video, captions and soundtrack included.Avatar UGC video

Discover what a Format takes

GET /v1/formats and GET /v1/formats/{format_id} return two fields that describe the Format rather than the call:

io is the Format's declared IO profile. input_kind is one of url, text, image or product; output_kind is one of video, image or text. Use it to pick a Format out of a list without calling it, and to know what shape of input it expects — the run body's input is a free-form object by design, so this profile is the only declared contract between a Format's author and its callers.

showcase is a worked example the Format actually produced during registration. It is verified against the generated-media ledger before it is stored, so it is output from a real run of this Format rather than a picture someone attached.

Both are null for Formats saved before registration existed. That means "not declared", not "takes no input" — fall back to the Format's description and its page.

Call the catalog directly

The catalog differs in what the Format knows. The wire contract is the one on Calling a Format, unchanged.

Formats by Sume are addressed at the reserved sume handle — POST /v1/formats/sume/{slug}/runs — and any key carrying formats:write may call one. The run, its media and its spend belong to the calling key; the catalog Format itself stays shared and unowned, so there is nothing to fork, install, or copy first.

Fork one in the Format library when you want to change it. Your copy is then addressed as {your_handle}/{slug}, and Formats you author yourself are called exactly the same way.

Call sheet for any Format

Every Format with a handle and a slug also has a page on this site at the address the API uses:

It carries the same sections as the pages above — scopes, curl, spend cap, poll and cancel — addressed to that Format. These are share and handoff links rather than nav, so they are not listed in the sidebar. They render for any well-formed address and never show the Format's body, so passing one to a partner reveals nothing beyond how to call it.

Where to go next