Which Sume catalog Formats make ad creative: the slugs by ad type

Sume's first-party Format catalog has 27 slugs at the reserved sume handle, and you can call any of them with POST /v1/formats/sume/{slug}/runs using a key that carries formats:write. The slugs themselves say what they are for. Before you call one, read it with GET /v1/formats/sume/{slug}, which returns its description and an io profile that names the input kind and the output kind, so you do not have to guess what to send.

The slugs grouped by what their names say

The grouping below is by name only. The catalog page lists the slugs but not a description for each one, so treat the grouping as a reading aid and confirm with the Format's own description. We did not run these Formats for this article.

Read before you run

GET /v1/formats/sume/{slug} returns the Format with an io profile, for example input_kind of url, text, image or product and output_kind of video, image or text, and a showcase that Sume verified against its generated-media ledger. Both can be null for older Formats, which means not declared, not takes no input. In that case use the description.

This one read tells you whether a Format wants a product URL, a photo or free text. That is the difference between a run that works first time and a 400 you pay time for.

curl -sS https://api.sume.com/v1/formats/sume/sume-product-commercial \
  -H "Authorization: Bearer $SUME_API_KEY"

Calling a catalog Format

The wire contract is the same as for any Format. Send an instruction, an input object, or both, an Idempotency-Key, and optionally a generation_spend_cap_usd and a webhook. The run, its media and its spend belong to the key that made the call. The catalog Format stays shared and unowned, and if you want to change one you fork it in the Format library and call your copy at your own handle.

The same Format with different instructions is how you produce variants. For a batch, send the items to the bulk-runs endpoint of that Format, up to 100 at a time.

Choosing for a test

For an A/B test, pick one Format and vary only the instruction. Two different Formats differ in structure and look, so they test the Format, not the hook. Once you know which structure suits the product, test hooks inside it.

• Read the Format before the first run.
• Set generation_spend_cap_usd on every run.
• Use one Format per test.

A practical shortlist for a first ad test

If you have a product page and no footage, start with sume-product-commercial and sume-video-hook. If you have a person-in-frame idea, try sume-close-camera-ugc. If your product is a skincare item, the pour, drip, squeeze and splash slugs read as single-moment shots, which suits a short hook. These are guesses from the names, so read each Format's description and io profile before you spend, and compare the showcase against what you actually want.

Run one slug on a single item first. If the output is what you hoped for, send the full list to the bulk endpoint, where each item has the same body as a single run and the queue takes up to 100 items.

Keys and scopes

Reading a Format needs a key that can read Formats, and calling one needs formats:write. Polling the run needs formats:read. A key that has only the write scope can start a run and then fail to poll it, so mint a key with both. Service-account keys cannot create bulk queues at all.

The catalog page lists slugs and nothing else, so prices, durations and what each Format produces are not on it. Get those from the Format's own read and showcase, and set a spend cap on the first run.