Generate marketing assets from one product photo via Formats

To generate several marketing assets from one product photo with the Sume API, start one catalog Format run per asset and send the same packshot URL in each run's attachments: for example sume-water-splash-hero for a hero still and sume-product-commercial for a video. Give each run its own Idempotency-Key and spend cap, and read each asset from its own receipt.

The facts below come from Sume's Format catalog, Create a run, Runs and results, and Structured output docs, read on 2026-09-27. Each Format's description is quoted from its catalog entry. The whole catalog is listed in Ready-made Formats for product video.

Which Formats make which asset?

Pick each Format by its description, which also tells stills from video: the image Formats below end theirs with "Not for: animated or motion deliverables", the video ones with "Not for: static campaign deliverables". The three image Formats here name skincare jobs, so this kit is for a skincare product. Descriptions state each Format's aim; they do not promise a result, and the recipes behind them stay private.

How do I start one run per asset?

Send one POST /v1/formats/sume/{slug}/runs per Format, with a key that has formats:write. A bulk request queues many calls to the same Format, so a mixed kit is separate creates. Sume fetches the attachment at each create and copies it into durable storage; a URL already on media.sume.com is not re-copied.

• Keys are scoped to one Format: the same Idempotency-Key sent to two Formats starts two runs. Derive each key from the product, the Format, and a version, as below. A uuidgen per request makes the header decorative.
• Workspace generation concurrency still applies to the jobs the runs start, and a job can wait in queued until a slot opens; see video job concurrency and queueing.
• The run, its media, and its spend belong to the key that called.

for SLUG in sume-water-splash-hero sume-product-commercial sume-close-camera-ugc; do
  curl -sS -X POST "https://api.sume.com/v1/formats/sume/$SLUG/runs" \
    -H "Authorization: Bearer $SUME_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: sku-4411-$SLUG-v1" \
    -d '{
      "instruction": "Campaign asset for the attached moisturizer.",
      "attachments": [
        { "type": "input_image", "image_url": "https://example.com/sku-4411.png", "filename": "packshot.png" }
      ],
      "generation_spend_cap_usd": 20,
      "communication": { "webhook_url": "https://example.com/hooks/sume" }
    }'
done

How do I read each asset back?

Leave output_schema off and each run's output uses the built-in sume/action-run-output/v1 shape: text plus images, videos, audio, and files arrays, filled deterministically from the run's generated media. primary_output_url falls back through videos, images, audio, then files, so one reader handles stills and clips. If you bind your own schema, require only what that Format makes.

Each run sends one signed format.run.terminal webhook when it completes or fails; dedupe on request_id. There is no GET /v1/format-runs list, so store each run's data.id against the asset it makes. media.sume.com URLs do not expire and are public to anyone holding them, so proxy or copy them if your product needs per-customer access control.

What does a kit cost?

Each run carries its own cap. generation_spend_cap_usd goes up to $500, null runs at $500, and 0 is rejected. Omit it and the run inherits the Format's cap, which GET /v1/formats/… reports as generation_spend_cap_usd_micros.

The kit's cost is the sum of each run's usage.debited_usd_micros, what the wallet deducted with the agent's own LLM turn included. AI video generation cost per video explains why that figure, not what the cap counts, is the cost.

What if one asset fails?

A failed receipt carries error with the reason, and its artifacts[] still lists whatever the run made. Redo that one asset in one of two ways:

• Start a new run of the same Format with a new key, bumping the version in your derivation.
• If it left work behind, continue it with previous_run_id: a new run with its own cap and its own webhook. Regenerate one scene of an AI video covers which runs qualify.