How do I cap what one Shorts episode run can spend in Sume?

Send generation_spend_cap_usd on each run item. It takes a number up to 500; 0 or above 500 returns 400, null lifts the cap to the $500 platform maximum, and leaving it out inherits the Format's cap. A Format that never named one reports a default of $400.

Because every run in a bulk queue is an ordinary Format run, each episode can carry its own ceiling.

Reading the receipt

Every receipt shows the effective cap as usage.generation_spend_cap_usd_micros and the actual spend as usage.billable_amount_usd_micros. A run can never spend more than its cap. Production live-commerce runs use caps of about $120, and a single-scene retry needs a fraction of that, per the docs.

Micros are millionths of a dollar, so divide by 1,000,000.

Caps for a season

A cap of $30 per episode is more than enough for a 60-second Wan 3.0 episode at 720p ($7.50 of video). Pick the cap from your own table and add margin for re-rolls. Wallet shortfalls surface as 402 insufficient_credits before provider work starts.

For a bulk queue, set the cap in each item, since the envelope has only concurrency and items. See the bulk post and the deadline post.

• Cap per item, not per queue.
• Retry scenes with a smaller cap.
• Alert when usage nears the cap.

Thinking in caps, not budgets

A budget is what you plan to spend. A cap is what you refuse to spend. For a batch, the cap protects you from the failure modes that no plan expects: a prompt loop, a model that returns something you must redo three times, or a bug in your own script.

Set the Format's cap to your normal ceiling and send a smaller one only where you are sure. The API does not clamp a number above the Format's cap, so a typo in a run can raise a cap instead of lowering it. Check the effective value on the receipt after the first run.

Finally, remember that a cap limits generation spend, not the other things you pay for. Captions, renders and imports are billed at their own rates, listed on the API pricing page.

A worked cap

Take a 60-second episode of two 30-second Wan 3.0 clips at 720p: $7.50 of video. Add captions at $0.20 and a render at $0.10 and the episode is $7.80. A cap of $20 allows more than two full takes of each clip and still stops a runaway.

Raise the cap for the finale only. A cap per item lets one expensive episode sit in a queue of cheap ones without raising the ceiling for all of them.

Review the receipts of the first three episodes before you queue the rest. If actual spend sits well under the cap, lower the cap for the remaining items; if it sits close, raise it or shorten the scenes.