Spend cap 0 is a 400 and null is $500: set a cap per holiday item

On a Sume Format run, generation_spend_cap_usd accepts a number up to 500, treats null as the platform maximum of $500, and rejects 0 or any value above 500 with a 400. If you omit the field, the run uses the Format's own cap, and a Format that never named one reports the platform default of $400. In a holiday bulk queue, set an explicit number on every item, because null lifts the ceiling to $500 and does not remove it.

What each value does

The Format-call docs give the table below. Sume accepts a number above the Format's own cap and does not clamp it, so the field on the request really is the cap for that run.

Steps for a bulk queue

Each item in a bulk queue is the same body as a single run, so the cap goes on each item and not on the queue.

• Estimate a sensible ceiling for one item from a test run, using usage.billable_amount_usd_micros on its receipt.
• Set generation_spend_cap_usd on every item to that ceiling plus a margin.
• Multiply the cap by the number of items to get your worst case, since there is no queue-level limit.
• After the first small batch, compare the effective cap, shown as usage.generation_spend_cap_usd_micros, with the real spend and tighten the number.

What Sume does not do

A cap is a ceiling for the generation spend of a run, and the docs say the metered total does not include the language-model turn of the agent, so it is not the whole cost of the run. The wallet figure is usage.debited_usd_micros, which does include it.

Also, a cap does not make a run succeed. If a run reaches its ceiling, it cannot spend more, so a cap set too low for a heavy video may stop the run before it delivers what you wanted; read the receipt to see what happened. Choose the number from measured runs and not from a guess.

A worked example

Suppose a test run of your holiday Format shows a billable amount of a few dollars and you decide a cap of $10 per item is comfortable. A queue of 100 items then has a worst case of 100 times $10, which is $1,000, and you should confirm your wallet and your approvals cover that number before you press send. If you instead sent null on each item, the worst case would be 100 times $500, which is $50,000, and nothing in the queue would stop you. The arithmetic is the whole point of setting the cap per item.