Green screen ad API: run the sume-green-screen Format

To make a green-screen ad from code, POST to /v1/formats/sume/sume-green-screen/runs. sume-green-screen is a first-party Sume Format that creates a finished green-screen ad from brand DNA, for requests such as a green screen or a talking-head overlay. You send one call with a spend cap, then read the receipt for the video.

When should you use it instead of a UGC Format?

Sume's catalog also has sume-close-camera-ugc, which makes a handheld selfie-style video with direct eye contact. The green-screen Format is a different shape: its description names a green screen or a talking-head overlay, and it works from brand DNA. The Format description lists what it is not for: custom generated scenes, social posting and the editor. If you want a generated scene, choose a different Format.

Read GET /v1/formats/sume/sume-green-screen before you build the integration. It returns the description and the io profile, which says whether input is a url, text, image or product.

What does the call look like?

The body below carries an instruction, a spend cap and a webhook. The cap is per run, so one bad input cannot spend without limit. Any key with the formats:write scope can call a catalog Format, and the run and its media belong to that key.

curl -sS -X POST "https://api.sume.com/v1/formats/sume/sume-green-screen/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: creator-greenscreen-v1" \
  -d '{
    "instruction": "Vertical 9:16, plain background, captions on.",
    "generation_spend_cap_usd": 10,
    "communication": { "webhook_url": "https://example.com/hooks/sume" }
  }'

How do you collect the video?

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 green-screen 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.