A failed Format run still lists its media: read artifacts[], continue

A Sume Format run that ends failed still lists every durable file it made in artifacts[], so a failure does not mean the media is lost. If the run left work and has a thread, you can continue it with previous_run_id instead of starting over,.

What the receipt keeps

The docs say it in two places. In the status table, failed means finished with an error, error gives the cause, and artifacts[] still holds all the media that the run made. And in the continue section, a failed run that left work can be continued, while a run that left nothing cannot.

Failure is honest

An unfinishable run comes back failed, for example with unattended_blocked, and never as a half-finished completed. That is a deliberate choice. It means your code can trust completed as a sign that the deliverable exists, and it means you should look at artifacts[] on every failure before you decide to re-run.

When you can continue

A continuation is only possible under two conditions: the receipt's thread_id is not null, and the run either completed or has a non-empty artifacts[]. Each refusal has its own code.

What a continuation is

A continuation is a new run with its own id, its own receipt, its own spend cap and its own single webhook. The original run never changes. Bind the same output_schema again, because it is per run and is not inherited, and remember that usage stays per run even though artifacts[] on the continued run lists all the media of the whole conversation.

List what survived

The script below reads a failed run's artifacts and prints what survived. It needs RUN_ID and SUME_API_KEY, and it only reads.

import json, os, urllib.request
req = urllib.request.Request(
    "https://api.sume.com/v1/format-runs/" + os.environ["RUN_ID"],
    headers={"Authorization": "Bearer " + os.environ["SUME_API_KEY"]},
)
with urllib.request.urlopen(req) as r:
    run = json.load(r)["data"]
print(run["status"], (run.get("error") or {}))
for a in run.get("artifacts") or []:
    print(a["type"], a["content_type"], a["url"])

A rule of thumb

Decide on the number of artifacts before you decide on a retry. Zero artifacts means a fresh run. A few artifacts and a clear error mean a continuation with a narrow instruction, such as redoing one scene. The continuation has its own spend cap, so you set the limit for the retry yourself.