Skincare product stills by API: sume-water-splash-hero

For a skincare hero image with a dramatic water splash, call Sume's sume-water-splash-hero Format: POST /v1/formats/sume/sume-water-splash-hero/runs. It creates a finished beauty product hero image with suspended droplets and premium package focus, and its description says it is not for animated or motion deliverables. It returns an image, not a video.

Which still Formats are in the catalog?

The Sume catalog has a family of finished beauty stills. Each one has a plain use case in its own description. sume-water-splash-hero is for hydrating or freshness-led skincare. The siblings cover texture and set: sume-formula-texture-hero (macro cream, gel, oil, foam or serum around an accurate package), sume-cream-squeeze (a ribbon of product from the package), sume-sunscreen-splash (bright daylight and frozen water motion with SPF packaging) and sume-editorial-product-set (a coordinated collection or gift set).

How do you call one?

Read the Format with GET /v1/formats/sume/sume-water-splash-hero. The io profile has output_kind: image when the Format declares it, so you know the receipt will hold an image artifact. Then send the run with a spend cap. The still Formats use the same run contract as the video Formats.

curl -sS -X POST "https://api.sume.com/v1/formats/sume/sume-water-splash-hero/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: serum-hydra-hero-v1" \
  -d '{
    "instruction": "Square 1:1, keep the label legible.",
    "generation_spend_cap_usd": 10,
    "communication": { "webhook_url": "https://example.com/hooks/sume" }
  }'

What does the receipt give you?

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 product stills 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 beauty still Formats differ?

Pick by the look the product needs, then check the Format's description before the first run.