Which Sume Format for a UGC ad? Read io, then call by name

To pick a Sume Format for a UGC ad, read the candidate with GET /v1/formats/sume/{slug} first. The catalog lists sume-close-camera-ugc, sume-mobile-app-ugc, sume-product-usage-demo, sume-before-after, sume-virtual-try-on and sume-recreate among its callable slugs (read 2026-10-08). The response carries the Format's description and io profile, which tells you whether it wants a URL, text, an image or a product and returns video, image or text.

What the catalog documents

A Format is a saved recipe that an Agent applies in a fresh sandbox. The catalog Formats answer at the reserved sume handle, any key with formats:write can call them, and the run, its media and its spend belong to the key that made the call. You do not fork anything first. To change one, fork it in the Format library and call your copy at {your_handle}/{slug}.

Any slug not on the list answers 404 format_not_found at sume/{slug}, so a typo fails fast.

Sending the run

A run takes your data in input, an optional instruction, up to 30 image attachments, and a per-run generation_spend_cap_usd of up to $500. Set the cap lower than the platform maximum so a bad prompt cannot spend a whole balance. Send an Idempotency-Key, and use a webhook_url or poll the receipt. Long-form host video usually completes in 15 to 30 minutes, so build for the asynchronous path.

The slug names above are from the docs list; the read-before-call step is how you confirm that a Format fits your input rather than guessing from its name.

curl -sS -X POST "https://api.sume.com/v1/formats/sume/sume-close-camera-ugc/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ugc-test-001" \
  -d '{
    "instruction": "Vertical 9:16 UGC ad for the attached product. One hook, one benefit, one call to action.",
    "attachments": [ { "type": "input_image", "image_url": "https://cdn.example.com/packshot.png" } ],
    "generation_spend_cap_usd": 15
  }'

From one run to a batch

Once one run looks right, queue variants with POST /v1/formats/sume/sume-close-camera-ugc/bulk-runs: 1 to 100 items and a concurrency of 1 to 16. Each item is an ordinary Format run, with its own generation_spend_cap_usd and its own webhook. The queue itself has no webhook, so poll GET /v1/format-run-queues/{id} and read counts.failed once the queue is completed.