Sume's 27 catalog Formats: slugs, 404 rule and the io profile

What is in the catalog

Sume's own Formats live under the handle sume, and as of 2026-10-08 the catalog has 27 slugs, all starting sume-. You can run one without forking it. A slug not on the list answers 404 format_not_found, so a typo or an old name fails fast, before any spend.

Call one by POST /v1/formats/sume/{slug}/runs. The run, the spend, the media and the receipt all belong to your key and your workspace, not to Sume.

Read the io profile first

GET /v1/formats/sume/{slug} returns a description and an io profile. io.input_kind is url, text, image or product, and io.output_kind is video, image or text. That is 4 by 3, or 12, possible combinations. On older Formats io can be null, so handle that case.

Use it to route work. A product URL goes to a Format whose input_kind is url or product; a request for a still goes to one whose output_kind is image. Matching the profile before the run avoids paying for a Format that wants input you do not have.

When to fork

A catalog Format cannot be edited in place. To change its instructions, fork it in the Format library. The fork lives in your handle or your team's and has its own slug, so later calls use POST /v1/formats/{handle}/{slug}/runs with your handle.

Version pinning follows you: each receipt records the format.version that ran, so a fork you edit later does not alter past receipts.

• Unlisted slug: 404, no charge.
• Team forks need a key from that workspace, else 403 workspace_key_required.
• Catalog runs still need Idempotency-Key.

A routing function

A small router makes the profile useful. Read the io pair once per slug, cache it for the day, and select slugs by input_kind and output_kind. For example, a product URL and a video result narrows the 27 slugs to the ones whose profile says so. If io is null, skip the slug or send it to a human, because the profile is the only machine-readable hint.

Re-read the list when you deploy. The catalog can grow, and your cache should not hide a new slug or keep a removed one.

• Cache profiles, not receipts.
• Log the slug and the format.version of every run.
• Treat a 404 as a config error, not a retry.

Cost awareness

Catalog Formats do not change what a run can cost. Spend is still capped by generation_spend_cap_usd, and the Format's own default of $400 applies when you send nothing. Set a smaller cap for small jobs such as a single still.

Keep a written record

Document the decision in the repository next to the code that makes the call, so the next engineer sees why the choice was made and which docs page it came from. Re-read that page when you upgrade a client or change a key, since gates and limits are the parts most likely to differ from what you remember.

A short note of the date you last verified the behaviour, such as 2026-10-08, is enough for a reviewer to know how fresh the claim is.