Product photo to holiday video ad: attach the photo to a Format run

To turn a product photo into a holiday video ad, call a Format from the Sume catalog and attach the photo to the run. The catalog includes sume-product-commercial, and the call is POST /v1/formats/sume/sume-product-commercial/runs with an instruction and an attachments array of input_image entries. The run returns a receipt with an arun_ id right away, and the finished video appears at primary_output_url once the run is completed.

What you can attach

A run can carry up to 30 images the agent can look at, each as a public HTTPS image_url or as an asset_id from the Assets API. Sume fetches a URL when the run is created, so it must be reachable without a login. Media URLs placed inside input share the same budget of 30 files per run.

Steps

The run is a single request, but a few habits keep it cheap and repeatable.

• Pick a clean photo with the product fully visible, and host it at a public URL or upload it to get an asset_id.
• Write an instruction that names the offer and the mood, such as a calm gift-box reveal, and keep promo text out of the photo prompt if you will burn it in later.
• Send the request with an Idempotency-Key and a generation_spend_cap_usd so a bad run has a ceiling.
• Poll the receipt until the status is terminal, then read primary_output_url and the artifacts list.

curl -X POST https://api.sume.com/v1/formats/sume/sume-product-commercial/runs \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: gift-box-hero-001" \
  -d '{
    "instruction": "Calm gift-box reveal, warm light, 9:16.",
    "attachments": [
      {"type": "input_image", "image_url": "https://example.com/gift-box.jpg"}
    ],
    "generation_spend_cap_usd": 20
  }'

What Sume does not do

The Format catalog page lists the slug, but the exact look and the input fields vary by Format, so read the Format with GET /v1/formats/sume/{slug} before you depend on a field. Sume does not promise that the product in the video matches the photo to the pixel; check the result before it goes into an ad account.

A replay of the same idempotency key with a different image list returns 409 idempotency_conflict, while a true replay does not fetch your images again. That protects you from a double charge, and it also means a changed photo needs a new key.

Shot list for a seasonal ad

For a holiday offer, the photo carries most of the result, so spend your effort there. Use a sharp shot on a plain background, avoid heavy text on the packaging if you can, and send a second angle as another attachment when the product has a back or a label that matters. More images give the agent more to work from, up to the 30 allowed, but each extra file is another thing that must be fetchable, and one unreachable image fails the attachment step with its index in the error.

Keep the promotional words, such as a percentage or a code, out of the prompt if they must be exact, and burn them in afterwards with a caption job using cues. That way a wrong digit is caught in text you wrote and not in text a model drew.