How to cancel an AI video generation job or run with the Sume API

To cancel a Sume generation job, send POST /v1/jobs/{id}/cancel. It succeeds only before generation work starts; after that it returns 409 job_generation_already_started and the job finishes normally. Format, Action, and Agent runs have their own idempotent cancel routes, and generation a Format run finished before the cancel is still billed.

The rules below come from Sume's Jobs and results, API reference, Runs and results, and Run webhooks docs and the live OpenAPI reference, read on 2026-09-26.

Which cancel endpoint do I call?

Jobs and runs are different resources, and each has its own route. Follow the cancel_url on a status payload or receipt rather than building the path.

When can I cancel a generation job?

Only before generation work starts; the documented cancel path is queued -> canceled. Once any external generation task has begun, Sume rejects the cancel so that usage settlement cannot refund work already submitted for generation, and the job completes or fails normally.

• Check before you call: the status payload's cancelable is true only before external generation work starts, and cancel_url turns null after that.
• A late cancel answers 409 job_generation_already_started with details.cancelable: false.
• A job that already completed or failed cannot be canceled either; the route answers 409.
• Cancelling a job that is already canceled returns the same job, with idempotency_hit: true.

curl -X POST https://api.sume.com/v1/jobs/job_123/cancel \
  -H "Authorization: Bearer $SUME_API_KEY"

How does cancelling a run work?

POST /v1/format-runs/{run_id}/cancel needs formats:write and is idempotent: the current receipt comes back either way. cancel_effect says what happened: canceled means this call stopped a run in flight, and no_op means the run had already finished. cancelable is true while the run is queued or processing.

On an Action run, cancelable is also true while queued or processing, and cancelling an already-terminal run returns that terminal receipt with 200. For Agent Completions, the docs show the same POST …/cancel call to stop a run in flight.

A bulk queue has no cancel-queue endpoint. Cancel each child run instead; its queue item becomes canceled and frees its slot for the next queued item. See Format bulk runs.

What is still billed after a cancel?

Sume reserves the estimated amount when it accepts a paid job, and a cancellation before capture refunds that reservation. A job whose cancel was refused runs on: successful completion captures the reservation, and a failure releases or refunds it where applicable.

On a Format run, generation the run completed before the cancel is billed, and usage reports it. To check one job or run afterwards, GET /v1/usage with job_id or run_id sums exactly what it cost; do failed AI video jobs cost money? shows how to read that ledger.

Does a cancel send a webhook?

Jobs do, runs do not. A job submitted with a webhook_url receives a terminal job.canceled event, with status: "ERROR" and an error object.

A canceled Format, Action, or Agent run never delivers a webhook. Trust the cancel response and poll status_url until the status is canceled; do not wait for a POST. A webhook-only integration has to handle this path from the cancel response itself.

Does a timeout or a dropped poll loop cancel anything?

No. A client-side timeout does not cancel a job: it keeps running and still bills. Abandoning a poll loop does not stop a Format run or its spend. An SDK wait that times out cancels nothing either; to stop the work, call cancelApiJob for a job or cancelFormatRun for a Format run. The CLI has sume jobs cancel <job_id> --confirm-submit, and on hosted MCP jobs_cancel is a write that takes an idempotency_key.

When a submit fails with 429 queue_full, cancelling queued jobs you no longer need is one of the documented steps; video job concurrency and queueing covers the rest.