Format spend caps: the $400 default, $500 maximum, and your own

Every Sume Format has a generation spend cap, and a run can never spend more than its effective cap. A Format that never named a cap reports $400. On a run you can send generation_spend_cap_usd up to the platform maximum of $500, and if you omit it the run inherits the Format's cap. Set your own number on every run; the default is far higher than most clips need.

How the effective cap is chosen

The docs give a short rule. The table shows what each request value does.

One surprise to design around

Because a number above the Format's own cap is accepted and not clamped, a caller can raise the ceiling for one run. Treat the request field as a policy you control in your backend, not as input from end users. If your product lets customers trigger runs, set the cap in server code from a plan or a price tier.

What happens at the cap

If a run tries to spend more than its cap, it ends as failed with the generic code format_run_failed. The receipt's usage.billable_amount_usd_micros shows the spend against usage.generation_spend_cap_usd_micros. Compare the two before you decide to raise the brief or the cap. Artifacts the run already made are still listed on a failed receipt.

A separate gate runs before the run starts. If the workspace wallet cannot fund the run, the create call returns 402 insufficient_credits and nothing runs.

Sizing a cap

Start from measured runs, not from a guess.

• Run five typical inputs with a generous cap, and read usage.billable_amount_usd_micros from each terminal receipt.
• Set the cap to the highest of the five plus a margin you can accept.
• A retry of one scene on the same thread usually needs a fraction of a full run, so give retries a smaller cap.
• Alert when spend reaches most of the cap; a run near its cap is one input away from failing.

Keep the cap with the record

Store the cap you sent next to your own order id, with the run id and the idempotency key. When finance asks why one run cost more than the others, you can compare the cap, the actual spend and the Format version on the receipt in one query.