Cancel an avatar video job: the 409 job_generation_already_started

You can cancel an avatar video job with POST /v1/jobs/:id/cancel, but only before generation work starts. Once it has, Sume returns 409 job_generation_already_started with details.cancelable: false, and the job runs to completion. Cancelling a job that is already canceled is idempotent and returns the same canceled job.

This comes from Jobs and results and Errors and credits.

How do I cancel a job?

Take the job id from the submit response and post to its cancel URL; the envelope also carries a cancel_url when present.

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

Which status codes should I expect?

The docs list a 409 family for operations that are not valid for the job's current status.

What if I only wanted to stop a mistake early?

Cancelling is a narrow window, so the cheaper habit is to catch mistakes before the render. Create an avatar video preview first: it makes first-frame stills without starting the full talking-video render, and you only call generate-video when the stills are right.

If a script was wrong but the job is already generating, treat the output as a draft, fix the script and submit again with a new idempotency key. Reusing the old key returns the original job, which is correct for a network retry and wrong for a changed script. See retrying without double billing.

How do I confirm the final state?

Poll GET /v1/jobs/:id/status until terminal is true, and read GET /v1/jobs/:id/events for the timeline: job.created, job.queued, job.started, generation.submitted, then job.completed, job.failed or job.canceled. A generation.submitted event is a sign the cancel window may have closed. Public events do not expose provider task ids.

How should client code handle the 409?

Treat job_generation_already_started as information, not as a failure. Your cancel request did not cancel anything, and the job is still live. Catch the code, stop sending cancel requests, and switch to polling for the terminal state. Do not submit a replacement job in the same breath: if the original completes you will have paid twice for the same intent.

A small decision rule helps. If your reason for cancelling was a typo, wait for the result and re-render with a corrected script. If it was a wrong avatar or aspect ratio, the same applies. If it was a runaway batch, stop submitting new work and let the in-flight jobs finish.

Does cancelling refund anything?

The docs on cancel describe state changes, not refunds, and this post does not claim any billing outcome for a canceled job. For how Sume describes credits, holds and failed jobs, read Errors and credits, and check your dashboard for the ledger after a cancel rather than assuming.