Product launch teaser: one Format call with a $25 spend cap

A launch teaser is one HTTP call to a Format, plus a spend cap so that a bad prompt cannot cost more than you chose. Send POST /v1/formats/sume/sume-product-commercial/runs with your product data in input, a short instruction, generation_spend_cap_usd, an Idempotency-Key and a webhook URL. The call returns 202 with a receipt, and the video arrives minutes later.

The call

sume-product-commercial is one of the slugs the catalog page lists at the sume handle. Any key with formats:write can call it, and the run and its spend belong to the key that made the call. Before you rely on it, read GET /v1/formats/sume/sume-product-commercial to see its description and io profile. The values in input below are placeholders for your own data.

curl -sS -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: launch-teaser-2026-10-v1" \
  -d '{
    "instruction": "15 second vertical teaser. No pricing on screen.",
    "input": { "product_name": "Northline Kettle", "launch_date": "2026-11-04" },
    "generation_spend_cap_usd": 25,
    "communication": { "webhook_url": "https://example.com/hooks/sume" }
  }'

Why each field is there

The fields below are the ones that change what a failed attempt costs you.

• generation_spend_cap_usd: 25 sets this run's own ceiling. Without it the run inherits the Format's cap, and a Format that never named one reports the platform default of $400.
• Idempotency-Key should come from the thing you are making, here the launch and a version you bump on purpose. Same key and same body returns 200 with idempotency_hit: true and starts no second run.
• communication.webhook_url gets one signed format.run.terminal POST when the run completes or fails. It must be public HTTPS.
• input is caller data. Sume writes it to a file in the run workspace and tells the agent it is data, not instructions.

What you read back

When the run is completed, primary_output_url and artifacts[] hold the files. usage.billable_amount_usd_micros is the generation spend counted against your cap. It does not include the agent's own LLM turn, so it is not the full cost. The real wallet amount is usage.debited_usd_micros.

The table converts a few caps into the micros value you will see on the receipt, as of 2026-10-09. The conversion is the cap in dollars times 1,000,000.

If the teaser is not right

Do not call again with the same key and a different body: that returns 409 idempotency_conflict. Either bump the version in the key and send the changed request, or continue the finished run with previous_run_id so the agent can change one part. A continuation has its own id, receipt and cap.

A pre-flight list

Before you send the call, run through these points. They come from the create-run docs, and each prevents a specific failure.

The body must name at least one of instruction, input, previous_run_id or attachments; an empty {} is 400 invalid_request. Unknown top-level fields are 400 unknown_parameter, and the API suggests the right name when it is close, for example webook_url. The webhook URL must be public HTTPS, so localhost, private ranges and credentials in the URL are refused at create.

Your key must carry formats:write. A key made before the Formats API existed will not, and it fails with 403 insufficient_scope, so mint a new one. A 402 insufficient_credits at create means the wallet cannot fund the run, and nothing ran. The write budget depends on your plan: 120 requests a minute on Free up to 1,200 on Scale, so a single teaser is far below any of them.