Which Sume calls are unbilled previews, and which reserve money

Four documented Sume calls estimate or validate without reserving credits: the timeline-1.0 plan call, video-filter check, a hosted MCP call with dry_run set, and generation_admission_preview. Any submit that creates a job reserves its estimate at once. The table lists what each call does so you can estimate a batch before you run it.

What each call does

The docs state, for each check below, that it does not create a job or reserve credits. Paid submits are the opposite: they reserve at submit and capture on success.

Using them together

A batch plan starts with the catalog, which gives the rate and the band for each route. For a timeline, the plan call is an unbilled compile preflight, and the render itself is $0.10 per output minute rounded up. For a filter, the check confirms the program is valid before the $0.02 encode.

For a paid MCP call, set dry_run first. The hosted MCP docs show a flow of dry_run, then submit with a new idempotency key, then jobs_wait and jobs_result. You can add max_spend_usd to the submit, and Sume enforces it only when you provide it.

The hosted MCP docs call this Playbook B: inspect one tool before paying. Look at the estimate, the balance and the queue behavior, then submit with a new idempotency_key.

• Estimate: catalog band, then the rate times your seconds, characters or minutes.
• Validate: filter check and timeline plan.
• Preflight: dry_run, and the admission preview for queue and balance.

A preflight order

For a mixed batch, order the checks from cheapest to most specific. Read the catalog first and compute the batch from rates. Run the filter check on every crop program and the timeline plan on every render. For paid generation, send one dry_run per distinct tool and settings pair, not one per clip, since the estimate for identical settings is the same.

Then submit the first job for real, read the usage entry, and compare the debited amount to your estimate. If they match, submit the rest.

Reading a 402 after a clean preview

A preview does not hold the money. Another job in the same workspace can use the balance between the preview and your submit. When that happens the submit returns 402 insufficient_credits before provider work, and nothing is charged. Handle it by checking the balance, upgrading the plan or waiting for included credit, or sending a cheaper request. It is not a reason to skip the preview.

What none of them guarantee

An estimate is the reserve at the moment you ask. A paid submit can still return 402 insufficient_credits if the balance changed between the preview and the submit, or 429 queue_full if the queue filled. Treat the preview as a check, and handle both errors at submit. See the admission preview and capping an agent loop for the code-level view, and why the catalog shows bands for reading the numbers.