The product usage demo Format: a person using your product, by API

sume-product-usage-demo is a catalog Format for the clip a marketer asks for first in Q4: a person applying or using the product, in vertical, from a single product still. Call it at POST /v1/formats/sume/sume-product-usage-demo/runs with a key that has formats:write. Its catalog example builds the first frame with Sume Auto, then animates one clear action with Sume Auto.

What does it take and return?

How do I write the brief?

The shipped example asks for one action: a person applies one pump of a facial serum and reacts to the texture. Keep to that shape. A single, clear motion is easier to animate than a routine. Put the product's real name, the setting and the ratio in instruction, which is capped at 8000 characters (about 4000 are carried into the run).

curl -X POST https://api.sume.com/v1/formats/sume/sume-product-usage-demo/runs \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: usage-demo-001" \
  -d '{
    "instruction": "9:16 casual demo: a person squeezes one pump of the attached hand cream and rubs it in, smiling",
    "attachments": [{ "type": "input_image", "image_url": "https://example.com/cream.jpg" }],
    "generation_spend_cap_usd": 15,
    "communication": { "webhook_url": "https://example.com/hooks/sume" }
  }'

How do I know it finished?

Either poll the run or take the format.run.terminal webhook, which is signed with x-sume-webhook-signature over <timestamp>.<raw_body>. A webhook verifier must refuse an empty secret. If a delivery is lost, POST /v1/format-runs/{run_id}/webhook/redeliver sends it again.

When is it the wrong Format?

Pick another catalog slug when the shot is not a person using the product. sume-product-commercial is the polished studio spot with no presenter. sume-before-after is for a matched transformation. sume-close-camera-ugc is a close, handheld creator style. If you are unsure, GET /v1/formats/sume/{slug} returns a short description and the io profile for each, and costs nothing, so compare two or three before you spend on a run.

For a holiday push, a sensible order is to run the usage demo for the hero SKU only, read the result, adjust the brief once, and then queue the rest. The same call works as an item inside a bulk run.

What are the limits?

• The catalog example is a skincare serum. Other products work by changing the brief, but check the first clip before you scale; hands, packaging text and labels are where generated video most often drifts.
• You cannot pause for approval over the API. If the run cannot finish it returns failed with unattended_blocked.
• A claim the clip makes on screen, such as results from using the product, is yours to substantiate and disclose.