Cap a Format run at $4: generation_spend_cap_usd on a before/after ad

To keep a before/after ad run under $4 on Sume, send generation_spend_cap_usd set to 4 in the body of POST /v1/formats/sume/sume-before-after/runs. A run can never spend more than its effective cap; if it tries to, the run ends as failed with the code format_run_failed, and the receipt shows how close the spend got.

How the cap is chosen

Every Format has a generation spend cap. If you send nothing, the run inherits the Format's cap, and a Format that never named one reports $400 in the errors page. If you send a number up to 500, that number is the run's cap, and Sume accepts a number above the Format's own cap without clamping it. Send null and the run uses $500. Sume rejects 0.

So the cap on the request is a lowering control only if you choose a smaller number than the Format's. Read the Format's cap first with GET /v1/formats/sume/{slug}, field generation_spend_cap_usd_micros.

Reading the result

Every receipt gives the effective cap as usage.generation_spend_cap_usd_micros and the actual spend as usage.billable_amount_usd_micros. The values are in micros, so $4 is 4,000,000. A failed run caused by the cap has the code format_run_failed, the same generic code used for other failures, so compare the two numbers before you conclude it was the cap.

If it was the cap, raise the number or shorten the brief. Do not raise the cap on a hunch: a before/after ad of a few seconds should not need hundreds of dollars, and a run that approaches the cap is a signal to check the brief.

A webhook and an idempotency key

Send an Idempotency-Key so a retry does not start a second run. Add communication.webhook_url if you do not want to poll. Together with a low cap, these make a run safe to queue from a script: bounded spend and a single execution.

A run's media and its spend belong to the key that called it. The sume handle's Formats stay shared and unowned, so you do not fork anything to call them. The guidance here covers mechanics; each run is metered at the rates of the models it uses.

A practical note

A practical test is to run the same Format twice with caps of $4 and $8 on the same input and compare the receipts. If both runs spend the same amount, the cap is only a safety rail and you can keep it low. If the $4 run fails and the $8 run succeeds, you have measured the real cost of the brief. Record that number with the date, because model rates change, and set your production cap about 25 percent above it, so ordinary variation does not fail a run but a runaway one still stops.

Before you scale

Every price in this post is a Sume list price read from the public catalog on 2026-10-09, and the arithmetic is shown so you can redo it with your own counts. Rates can change, so re-read the catalog before a large batch and run a small test first. Sume bills the job's captured amount, and the job result tells you what was used, so compare the first run's receipt with your estimate before you scale the work to the full set.