Format catalog

A Format is a saved authoring recipe that an Agent applies to a run. Sume ships a first-party catalog of Formats. Thus, a production workflow can be one HTTP call, not a prompt that you maintain.

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

The catalog answers at the reserved sume handle. You can call these slugs today:

sume-close-camera-ugc, sume-virtual-try-on, sume-product-usage-demo, sume-mobile-app-ugc, sume-before-after, sume-product-commercial, sume-beauty-studio, sume-logo-motion-design, sume-cinematic-studio-commercial, sume-fashion-editorial, sume-virtual-fitting, sume-water-splash-hero, sume-model-product-portrait, sume-magazine-cover-campaign, sume-formula-texture-hero, sume-sunscreen-splash, sume-cream-squeeze, sume-serum-drip, sume-toner-pour, sume-editorial-product-set, sume-slideshow, sume-wall-of-text, sume-green-screen, sume-video-hook, sume-fruits-drama, sume-recreate, sume-restyle.

Before you call a Format, read it with GET /v1/formats/sume/{slug}. This call returns its description and the io profile that the next section describes. Any slug not on this list answers 404 format_not_found at sume/{slug}.

Discover what a Format takes

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

{
  "io": { "profile": "url_to_video", "input_kind": "url", "output_kind": "video" },
  "showcase": {
    "kind": "video",
    "media_url": "https://media.sume.com/...",
    "thumbnail_url": "https://media.sume.com/...",
    "created_at": "2026-08-01T00:00:00.000Z"
  }
}

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 select a Format from a list without a call, and to know the shape of input that the Format expects. By design, the run body's input is a free-form object, so this profile is the only declared contract between a Format's author and its callers.

showcase is a worked example that the Format really produced during registration. Before Sume stores it, Sume verifies it against the generated-media ledger. Thus, it is output from a real run of this Format, not a picture that someone attached.

Both are null for Formats saved before registration existed. That means "not declared", not "takes no input". In that case, use the Format's description and its page.

Call the catalog directly

The catalog is different in what the Format knows. The wire contract is the same as on Calling a Format, with no changes.

Formats by Sume answer at the reserved sume handle — POST /v1/formats/sume/{slug}/runs — and any key carrying formats:write can call one. The run, its media and its credits belong to the key that made the call. The catalog Format itself stays shared and unowned. Thus, you do not have to fork, install, or copy anything first.

To change a catalog Format, fork it in the Format library. Then the address of your copy is {your_handle}/{slug}. You call Formats that you author yourself in 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 that the API uses:

https://docs.sume.com/formats/{handle}/{slug}

The page has the scopes, curl, spend cap, poll and cancel sections for that Format. These pages are share and handoff links, not nav. Thus, the sidebar does not list them. They render for any well-formed address and never show the Format's body. Thus, if you give one to a partner, the partner learns only how to call the Format.

Where to go next

• Format API — what a Format is, and how the instruction is composed
• Calling a Format — the full invoke contract and every error
• Bulk runs — queue many calls to the same Format
• Structured output — bind a schema and get typed JSON back
• Runs and results — polls, receipts, cancelation
• OpenAPI — accurate request and response schemas