Slideshow ad API: call the sume-slideshow Format from code

To make a slideshow ad from code, POST to /v1/formats/sume/sume-slideshow/runs with a key that carries the formats:write scope. sume-slideshow is a first-party Sume Format that builds a finished slideshow ad from brand DNA. The call returns a receipt at once, and you collect the finished video by webhook or by polling.

What is the sume-slideshow Format for?

The Format's own description reads: create a finished Fastlane slideshow Blitz from brand DNA, for requests such as a slideshow, carousel stills or a Fastlane slideshow ad. It also says what it is not for: custom generated scenes, social posting and the editor. So use it when you want a stills-led ad that follows a brand. Pick another Format, such as sume-product-commercial, when you want generated scenes.

It sits in the first-party catalog beside sume-wall-of-text, sume-green-screen and sume-video-hook. All of them answer at the reserved sume handle, so you do not fork or install anything before the first call.

How do you call it?

Read the Format first with GET /v1/formats/sume/sume-slideshow. The io profile and the showcase example tell you what to put in input. If both are null, the Format was saved before registration existed, and the description is the only contract. Then send the run. The Idempotency-Key makes a retry safe, and generation_spend_cap_usd caps what one run may spend.

curl -sS -X POST "https://api.sume.com/v1/formats/sume/sume-slideshow/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: brand-launch-slideshow-v1" \
  -d '{
    "instruction": "Vertical 9:16, no voice-over.",
    "generation_spend_cap_usd": 10,
    "communication": { "webhook_url": "https://example.com/hooks/sume" }
  }'

What happens after the 202?

A run does not return the file in the 202. It returns a receipt with status queued, then moves to processing, and ends as completed, failed, canceled or skipped. On completed, the receipt carries artifacts[] and primary_output_url. On failed, artifacts[] still lists any media the run made. Send a webhook URL, or poll GET /v1/format-runs/{run_id} and double the gap up to one minute, because a poll every second gains nothing.

What changes when you need many of them?

A bulk request is a server-side queue of ordinary Format runs, up to 100 per queue, so a list of slideshow ads can render overnight without your laptop driving the fan-out. Each item is the same unit of work as a single run, with its own receipt.

Check the key before you queue anything. A key needs formats:write to create runs and formats:read to poll a queue, and a key made before the Format API trigger shipped lacks both scopes, so create a new one. Service-account keys cannot create Format runs and fail with 403 insufficient_scope. If a team workspace owns the Format, use a key issued in that workspace.

• Give every item its own Idempotency-Key, built from the item and a version number.
• Set generation_spend_cap_usd on each run, not only on the account.
• Cancel a single child with POST /v1/format-runs/{run_id}/cancel; there is no cancel-queue endpoint.

How do the four Fastlane Formats differ?

Sume describes four sibling Formats in the same catalog. Pick by the ad you want, not by the name.