Format run spend cap: 500 max, null, 0 and the $400 default

Every Sume Format run has a generation spend cap, and it can never spend more than its own effective cap. Send a number up to 500 to set it for one run, send nothing to inherit the Format's cap, and send null for the platform maximum of $500. Zero and anything above 500 return a 400.

The four cases

A Format that never named a cap reports the platform default of $400 in generation_spend_cap_usd_micros on GET /v1/formats/.... Read that field before you pick a number.

Where to read the cap and the spend

Every receipt carries both values under usage. generation_spend_cap_usd_micros is the effective cap. billable_amount_usd_micros is what the run has spent against it. A micro is one millionth of a dollar, so 120000000 is $120.

The create response in the docs shows a queued run with a cap of 120000000 and a billable amount of 0. The terminal webhook payload then shows the same cap and the final amount.

Choosing a number

Do not copy a cap from another Format. Start from the cheapest honest estimate for your recipe, set the cap above it, and read usage on the first real receipts. The docs note that a single-scene retry on the same thread needs a fraction of a full run's cap, so retries can use a smaller number than the first run.

null lifts the ceiling to $500 but does not remove it. Use it only for a run that you have watched and priced before.

• A cap protects you from a hostile input payload, because the spend stops at the limit.
• A cap is not a quote. Sume meters spend at the rates on the API pricing page.
• A 402 at create or during the run is a wallet problem, covered in the errors page.

A request that sets it

Add the field next to your idempotency key. The body below is valid on its own, because at least one of instruction, input, previous_run_id or attachments is present.

curl -sS -X POST "https://api.sume.com/v1/formats/sume/sume-video-hook/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: hook-test-001" \
  -d '{
    "instruction": "A 6 second hook for a water bottle, vertical.",
    "generation_spend_cap_usd": 25
  }'

What to log per run

Keep four values next to your own record: data.id, the Idempotency-Key, the cap that you sent, and usage.billable_amount_usd_micros from the terminal receipt. Your identifiers do not come back in output, because Sume builds output from what the run made and said, not from input. Key your records by run id or by idempotency key instead.

With those four values you can answer the questions that matter after a launch week: which runs reached their cap, which cost far less than the cap, and whether the cap you chose was too tight for the recipe or too generous. The docs note that production live-commerce integrations run with caps of approximately $120, which is a useful scale for a full multi-scene video, not a rule for your Format.

Cap plus idempotency

A retry with the same key and the same body returns the original receipt and does not bill twice. If you change the cap, the body changed, so the same key returns 409 idempotency_conflict. Change the key when you change the cap on purpose.