Repeatable holiday ads with Sume Formats: read the io profile first

For a repeatable ad, call a catalog Format and check its io profile first: GET /v1/formats/sume/{slug} returns what input it takes (url, text, image or product) and what it makes (video, image or text). A Format is a saved recipe that an agent applies to a run, so a production workflow can be one HTTP call instead of a prompt you maintain. Any key with formats:write can call the first-party catalog at the reserved sume handle.

This matters in Q4 because a batch built on the wrong input kind fails 100 items at once. A free read is cheaper than a bad queue.

What the catalog lists today

The docs list these slugs as callable: sume-product-commercial, sume-product-usage-demo, sume-close-camera-ugc, sume-mobile-app-ugc, sume-before-after, sume-slideshow, sume-video-hook, sume-recreate, sume-restyle and others, including beauty, fashion and splash product sets. A slug not on the list answers 404 format_not_found at sume/{slug}.

Read, then call

First read the Format. Then post a run to POST /v1/formats/sume/{slug}/runs with an Idempotency-Key and an input that matches the profile. The run, its media and its spend belong to your key; the catalog Format stays shared. To change a catalog Format, fork it in the Format library and call your copy at {your_handle}/{slug}.

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

From one run to a batch

Do the read once, run one SKU, check the output, and only then submit a bulk queue of up to 100 items. Each Format also has a generation spend cap, and one that names no cap reports the platform default of $400, so set a tighter cap on your own Formats before an overnight batch.

Each Format has a share page on the docs site with its scopes, curl and poll sections at docs.sume.com/formats/{handle}/{slug}, which is a handy link for a teammate who will run the batch.

• Read the io profile before you build the sheet.
• Run one SKU as a trial.
• Then queue up to 100 per bulk request.

Choosing a slug for a holiday ad

Match the Format to your input. If you have a product page URL and want a commercial, a Format whose profile says input_kind: url and output_kind: video fits. If you have a product image, look for input_kind: image. If your sheet has a text script for each SKU, look for text. Read three candidates, compare their profiles and descriptions, and choose by the input you really have, not by the name.

Then test one SKU. Check the run receipt: status moves from queued to processing to completed, and a completed run has output, artifacts[] and primary_output_url. A failed run still keeps artifacts[] for any media it made. Watch the video, and only if it is right put the rest of the sheet in a queue.

Think of the Format as the part of the ad that stays fixed, and the input as the part that changes per SKU. A good Black Friday setup changes only the input row. If you find yourself rewriting the instruction for every SKU, the recipe is probably wrong, and a fork of the Format with the instruction baked in will be steadier.