Get partial results from a failed AI video run with a scene ledger

A failed Sume Format run still publishes the partial result it produced on output, but only if your output schema says a partial is a legal shape. Make optional fields nullable, leave minItems off the scene list, and name the finished video as primary_output_key: a half-made video can then report the scenes it rendered, and the run still comes back failed.

The rules below come from Sume's Structured output and Errors and spend pages, read on 2026-09-26. Binding a schema in the first place is covered in Sume Format structured output.

What does a failed run still return?

More than an error. output is null only when nothing satisfied your schema, not merely because the run failed. The docs' example is a show that rendered 20 of 40 scenes and then stopped: it reports those 20 on output, the rest carry whatever “failed” value your own schema defines, and output_error explains why it stopped.

• artifacts[] is populated either way, with everything the run made.
• primary_output_key and primary_output_url are null on every non-completed run, so a partial can never pass as the deliverable.
• Over the API, a result that misses your schema is a run failure: status is failed, and error carries the same reason as output_error.

How do I make a partial result legal in my schema?

Sume adds no floor of its own. The validator enforces exactly the keywords you wrote, so a schema that demands every scene turns a 20-of-40 show back into output: null. Two rules do the work:

• Optional means nullable, not absent. Every property must still be listed in required; express “may not exist” as "type": ["string", "null"].
• Leave minItems off the arrays you want to receive partially. It is enforced, so minItems: 1 on a scene list rejects the very ledger you are trying to read.

What does a scene ledger schema look like?

Below is the docs' ledger schema with its description annotations removed. Bind it as the schema inside output_schema, with a namespaced name and strict: true, and send "primary_output_key": "full_video" on the same run.

{
  "type": "object",
  "additionalProperties": false,
  "required": ["full_video", "scenes", "notes"],
  "properties": {
    "full_video": { "type": ["string", "null"] },
    "scenes": { "type": "array", "items": { "$ref": "#/$defs/scene" } },
    "notes": { "type": ["string", "null"] }
  },
  "$defs": {
    "scene": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "status", "video_url", "failure_reason"],
      "properties": {
        "id": { "type": "string" },
        "status": { "type": "string", "enum": ["completed", "failed", "skipped"] },
        "video_url": { "type": ["string", "null"] },
        "failure_reason": { "type": ["string", "null"] }
      }
    }
  }
}

Why pair the ledger with primary_output_key?

It keeps the loosened schema honest. A run that fills scenes but leaves full_video null has satisfied the schema and still not produced the deliverable, so it ends failed with primary_output_missing instead of reporting a success. In the docs' words, the looseness buys you visibility into the partial; it does not buy the run a pass.

How do I read a partial result?

Check output_error before reading output, and fall back to artifacts[] when output is null. Then branch on full_video for “did I get a show” and on each scenes[].status for “what do I need to retry”. The docs name a partial on output for three failure codes:

• primary_output_missing: the result satisfied your schema, but the key you named in primary_output_key is empty.
• agent_reported_failure: the run itself reported that it did not deliver, and output carries the ledger of what was made.
• incomplete_assembly: the run reached its time limit with generation jobs still unfinished, and the partial ledger is on output when your schema allows it.

How do I retry only the missing scenes?

Send the failed run's id as previous_run_id on a new run, and name the scenes to redo: the Cookbook's recipe reads one from input.scene_id, or two at once from scene_ids. The next turn picks up the same conversation with the finished clips already on it. Regenerate one scene of an AI video walks through the call, its refusals, and its budget.

The Cookbook's variant of this schema types each clip as SumeMediaFile# and uses the status values succeeded, stand-in, and failed. There, a scene marked stand-in or failed is what its scene retry recipe fixes.