Format run failed with unattended_blocked: why it never half-finishes

A Format built for chat can stop and ask a person, for example to approve stills before the video is made. Over the API there is no person, so Sume tells the run those approvals are already granted and to carry on within its spend cap. If it genuinely cannot continue, the run comes back failed with error.code: unattended_blocked, never as a half-finished completed.

What the failure looks like

The docs show a failed receipt with output: null and output_error and error both carrying unattended_blocked, with a message written to be shown, such as no avatar matching the brief so no video was made.

Reading results safely

Branch in this order: status, then error, then output_error, and only then output. primary_output_url is null on a failure, so testing if (run.primary_output_url) is a safe way to ask whether the deliverable exists. A completed run can carry output_error when the projection did not match your schema, so a green status alone is not enough.

Because the retry needs a new Idempotency-Key, derive it from your own record plus a version you bump on purpose, as the docs advise, not from the time of the call.

• Put missing facts in input up front, so the run has nothing to ask about.
• Give clear, complete briefs; a vague brief is what a chat Format would have asked about.
• Use the spend cap as the guard on unattended work.

Prevention in the request

Most blocks come from a brief that is missing something. Put every fact the run could need into input, name the exact asset, voice or product, and avoid phrases that invite a question, like asking it to pick the best option when you have a preference. Test a new Format with one run on a low cap before you wire up a batch, and read the failure message, since it is written to be shown.

Limits

Telling the run approvals are granted means it can spend up to its cap without a human looking at the stills, so set generation_spend_cap_usd on purpose. The docs do not guarantee that a failed run spent nothing; compare usage.billable_amount_usd_micros with the cap on the receipt.