Sume catalog Formats for ads: which of 27 slugs to read first

The Formats by Sume catalog lists 27 slugs you can call at the reserved sume handle, and the page does not say what each one does. For an ad project, group them by what the slug name suggests, read each candidate with GET /v1/formats/sume/{slug}, and only then write a call. The read returns a description and an io profile: input_kind is one of url, text, image or product, and output_kind is one of video, image or text. Any slug that is not on the list answers 404 format_not_found.

Grouping by name

This table is a reading order, not a statement of what each Format does. The Sume page gives slugs only, so every row says what the name suggests and what to check.

The read, then the call

The read needs formats:read, and the call needs formats:write. The run, its media and its spend belong to the key that made the call, and you do not need to fork or install anything first. To change a catalog Format, fork it in the Format library, and your copy is then addressed as {your_handle}/{slug}.

curl -sS "https://api.sume.com/v1/formats/sume/sume-product-commercial" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  | jq '.data | {slug, description, io, showcase: .showcase.media_url}'

Use the showcase before you spend

The read also returns showcase, a worked example that the Format really produced during registration. Sume verifies it against the generated-media ledger before it stores it, so it is output from a real run of that Format and not a picture someone attached. Look at it for each candidate: it is the cheapest way to see the style a slug makes. Both io and showcase are null for Formats saved before registration existed, and null means not declared, not takes no input.

A short evaluation plan

Pick three slugs for one product. Send the same photos to each as attachments, with the same short instruction, a spend cap of your choosing, and a separate Idempotency-Key per slug, because the scope of a key is one Format and the same key on two Formats starts two runs. Poll each receipt and record usage.billable_amount_usd_micros. Choose by the result and the number on the receipt, and keep the receipts.

When you have chosen, move the work to a bulk queue. Each catalog Format also answers POST /v1/formats/sume/{slug}/bulk-runs, with up to 100 items in one queue.

Keep the choice in config, not in code. The catalog page lists slugs today and says that any slug not on the list answers 404 format_not_found, so a typo and a removed slug fail the same way. Check 404 explicitly in your client and log the slug, so you find the cause in a minute and not an hour.

Two reading habits save time. First, read the page of the Format on this site, because every Format with a handle and a slug has a call sheet at https://docs.sume.com/formats/{handle}/{slug} with scopes, curl, spend cap, poll and cancel sections, and the page never shows the Format's body. Second, treat the examples in any blog post as shapes and not contracts: input is a free-form object, and Sume publishes no field list for it, so the description of the Format you chose is the only source for key names.