Holiday Format run cap in credits: 8,000 to create, 600 to retry

Send generation_spend_cap_credits on every holiday Format run, and size it by the kind of call. The Sume docs' own examples use 8,000 credits for a full create and 600 for a one-scene retry on the same thread; those are the docs' sample numbers for a live-commerce run, not a Sume recommendation for your Format, so pilot a row and set yours from its receipt.

The field is in credits now, so older posts and scripts that name a dollar cap are using the previous spelling. Everything below is from the spend caps section of Calling a Format, Errors and spend, Runs and results, the cookbook and Bulk runs, all read on 2026-10-13.

What the cap does to a run

Every Format has a cap in credits, and a run can never use more than its own effective cap. What you send on the request decides that cap.

Credits are counted at the rates on the API rate card. The cap counts metered generation only (video, image, avatar, voice, timeline work), not the agent's own language-model turn.

Two caps for one holiday ad

A full create makes the voice, the clips and the assembled cut, so it needs the large cap. A scene retry continues the thread with previous_run_id, regenerates one clip, and re-assembles, so it needs a fraction of that. The cookbook says measured production retries used about one twentieth of the first run's credits and tells you to always send a cap.

With the docs' numbers, one twentieth of 8,000 is 400, so a 600 cap on a retry leaves headroom without letting a bad instruction regenerate the whole ad. That division is arithmetic on the docs' examples, so re-derive it from your own pilot receipt.

Because retries are new runs, a new Idempotency-Key per retry is part of the call, and usage stays per run even though the thread's media list is cumulative.

{
  "previous_run_id": "arun_e43e6c5cb2b74052",
  "instruction": "Retry the selected scene only. Keep every other scene and the voice track unchanged.",
  "input": { "scene_id": "sc_7" },
  "generation_spend_cap_credits": 600
}

What a capped run leaves behind

The wallet is checked at create: too few credits is 402 insufficient_credits with details.required_credits and details.available_credits, and nothing ran. The cap is checked during the run, and a run that tries to pass it ends as failed; compare usage.cap.counted_credits with usage.cap.limit_credits before you raise the brief.

Generation that finished before a failure or a cancel keeps its credits, and they do not come back if a later step fails. A 4xx at create, an idempotent 200 replay and a skipped run use none. On the receipt, usage.debited_credits is the wallet total including the agent turn, while counted_credits is the generation total the cap is enforced against.

In a bulk queue the cap is per item

A bulk queue holds up to 100 items, and the cookbook's example puts generation_spend_cap_credits inside each item. The worst case for a queue is therefore the item count times the per-item cap: 100 items at the example 8,000 is 800,000 credits of ceiling, which is a limit, not a forecast. Queue status completed only means every item is terminal, so check counts.failed and each child's receipt, and expect a capped item to show as failed there.

Before Black Friday week, run three rows, read their usage, and set the per-item cap just above the largest counted value. Size retries the same way, as a fraction of that number and never the create cap.