UGC-style gift set ad: one sume-close-camera-ugc run with a credit cap

sume-close-camera-ugc is one of the first-party Formats that answer at the reserved sume handle, so a key with the formats:write scope can call it today with no fork or install. One POST /v1/formats/sume/sume-close-camera-ugc/runs starts a run; the run, its media and its credits belong to the key that made the call. This post shows the call for a holiday gift set and the three settings that keep the cost known before you start.

Read the Format before you call it. GET /v1/formats/sume/sume-close-camera-ugc returns its description and an io profile (input_kind, output_kind), which is the only declared contract for what input should hold. input itself is free-form JSON; the Format reads the keys it knows, so put plain product facts there, not prompt prose.

What to send

These are the fields from the Sume Format call docs that matter for a one-off gift-set ad.

The call

The run is asynchronous: you get 202 with status_url, result_url and events_url. Store the run id before you do anything else.

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: giftset-2026-11-a" \
  -d '{
    "instruction": "Vertical 9:16, about 8 seconds. Handheld close-up of hands opening the gift set on a kitchen table. No on-screen price.",
    "input": {
      "product_name": "Winter Spice Candle Trio",
      "contents": ["3 soy candles", "1 box of matches", "gift tag"],
      "product_image_urls": ["https://example.com/candle-trio.jpg"]
    },
    "generation_spend_cap_credits": 600,
    "communication": {"webhook_url": "https://hooks.example.com/sume/format-run"}
  }'

Then label it correctly

A close-camera UGC clip is made with a synthetic presenter, not a customer who bought the product. Present it as an ad from the brand, and do not caption it as a customer reaction or add a star rating. The FTC rule on fake testimonials explains why that line matters.

If you need many versions, move to the bulk-runs endpoint, which takes up to 100 items; the Black Friday testimonial-variants post shows that pattern.

• Put the price in a caption you add afterwards, not in the generated scene.
• Pick a cap that covers one re-run so one failure does not block the launch.
• Write down the run id and the idempotency key together.