Regenerate one scene of an AI video with the Sume API

To regenerate one scene of an AI video made by a Sume Format, send a new POST /v1/formats/{handle}/{slug}/runs with the earlier run's id as previous_run_id and name the scene. The next agent turn continues the same conversation, so it can redo that clip and leave the rest alone. In the Cookbook's scene-retry recipe, the voice track, the other clips, and the script stay as they were, and the whole scene list comes back re-assembled.

The steps, refusals, and budget advice below come from Sume's Runs and results, Cookbook, and Errors and spend pages, read on 2026-09-26.

How do I retry one scene?

Plan for it on the first run. Bind an output_schema whose scenes[] gives every clip a stable id, and store data.id and data.thread_id from the 202: the first for the receipt, the second to group retries. Partial results from a failed AI video run shows a scene ledger schema.

Then continue that run with a body like the Cookbook's:

• previous_run_id: the run to continue.
• instruction: the operator's note. Say which scene, what is wrong, and how it should change.
• input: the machine-readable pointer. input has no fixed fields, so use the key your recipe reads; the Cookbook sends scene_id, and "scene_ids": ["sc_7", "sc_9"] for two scenes at once.
• output_schema: the same schema you bound on the first run. It is per run, not inherited.
• generation_spend_cap_usd, plus a new Idempotency-Key for this retry.

curl -sS -X POST "https://api.sume.com/v1/formats/acme/product-promo/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8823-v1-retry-sc_7" \
  -d '{
    "previous_run_id": "arun_123",
    "instruction": "Retry the selected scene only. Keep every other scene and the voice track unchanged. Do not change the script. New take only.",
    "input": { "scene_id": "sc_7" },
    "output_schema": { "…": "identical to the first run" },
    "primary_output_key": "full_video",
    "generation_spend_cap_usd": 8,
    "communication": { "webhook_url": "https://acme.example.com/hooks/sume" }
  }'

Which runs can be continued?

Read it off the earlier run's own receipt. A run is continuable when its thread_id is not null and it either completed or has a non-empty artifacts[]. So a failed run that left work behind can be continued, and one that left nothing cannot. A continuation the API cannot honor is refused at create, where nothing runs and nothing is charged:

What comes back from a scene retry?

A continuation is a new run: a new arun_… id, a new receipt, its own spend cap, and its own single format.run.terminal webhook. The original run never changes, and its webhook does not fire again. Both runs share the same read-only thread_id, and the new receipt's previous_run_id names the run it continued. Delivery works as described in Sume Format run lifecycle.

With the Cookbook's scene schema, the new receipt reads like this:

• output.scenes[] is the full list again. The retried scene has a new URL, and the others keep theirs.
• full_video is re-assembled at a new URL.
• artifacts[] lists everything the whole conversation generated, while usage stays per run.

How much does a scene retry cost?

The Cookbook says to budget a single-scene retry at a fraction of the create: measured production retries ran at roughly a twentieth of the first run's spend. Errors and spend says production long-form runs are typically created with caps around $120, and a single-scene retry with a few dollars; the Cookbook's retry example above sends a cap of $8. Always send a cap.

The cap is generation_spend_cap_usd, up to the platform maximum of $500; omit it and the retry inherits the Format's cap. The retry's usage.billable_amount_usd_micros is its generation spend against that cap, metered at the rates on API pricing. It excludes the agent's own LLM turn, so read usage.debited_usd_micros for what the wallet actually deducted.

Should I continue a failed run or start over?

When a failure left clips behind, the docs prefer continuing the run over a fresh one. These failure codes point that way:

• incomplete_assembly: the run hit its time limit with generation jobs unfinished. Continue it with previous_run_id; the finished clips are on the thread and are not regenerated.
• primary_output_missing: the result satisfied your schema, but the primary_output_key you named is empty. Continue the run to fill the gap, or retry.
• agent_reported_failure: the run itself reported that it did not deliver, for example with media slots marked failed or stand-in. The clips on output are real and are not regenerated by a retry; continue the run or re-fire with a new Idempotency-Key.

When is a scene retry the wrong tool?

A retry is a new take, not a re-encode: everything generative in that scene is re-rolled. The Cookbook's rule of thumb:

• The look is wrong: retry the scene.
• The words, the host, or the product change: start a new production with new scene ids.
• A fresh run needs a new Idempotency-Key, because the old one is bound to the receipt you already have. Sume Format run failure codes lists when to retry and when to continue.