---
title: Format catalog
description: Ready-made Sume Formats you can call from your own backend, with the scopes, curl, and run lifecycle for each.
---

A [Format](/formats) 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.

| Format | Use it when | Page |
|---|---|---|
| Product promo | You have a product or brand URL and want ad images or a promo video in a fixed house style. | [Product promo](/formats/product-promo) |
| Avatar UGC video | You have a script and want a talking-head creator-style video, captions and soundtrack included. | [Avatar UGC video](/formats/avatar-ugc) |

## 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:

```json
{
  "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 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](/formats/call), 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](https://www.sume.com/agents/format) 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:

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

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

- [Format API](/formats) — what a Format is, and how the instruction is composed
- [Calling a Format](/formats/call) — the full invoke contract and every error
- [Bulk runs](/formats/bulk-runs) — queue many calls to the same Format
- [Structured output](/formats/structured-output) — bind a schema and get typed JSON back
- [Runs and results](/formats/runs) — polling, receipts, cancelation
- [OpenAPI](https://api.sume.com/reference) — exact request and response schemas