Sume avatar video stuck? Read the job events before retrying

If an avatar video looks stuck, call GET /v1/jobs/{job_id}/events before doing anything else. It returns a public timeline that tells you whether the job is waiting in the queue, was started, was handed to generation, or ended, and that decides whether you wait, cancel or fix the input.

Never resubmit a paid avatar job just because your own poller timed out. A client-side timeout does not cancel the job: it keeps running and still bills.

Which events can I see?

The jobs docs list the public event names. They deliberately omit raw provider task ids and raw provider URLs.

Events are a pull snapshot, not a stream. There is no SSE or WebSocket transport on the Developer API today, and mode: "subscribe" does not give you progress events; it is an alias of sync's bounded wait.

What do I check first?

Start with status, then events, then result, in that order.

curl https://api.sume.com/v1/jobs/job_123/status \
  -H "Authorization: Bearer $SUME_API_KEY"
curl https://api.sume.com/v1/jobs/job_123/events \
  -H "Authorization: Bearer $SUME_API_KEY"
curl https://api.sume.com/v1/jobs/job_123/result \
  -H "Authorization: Bearer $SUME_API_KEY"

On status, terminal says whether the job is over and result_ready says whether the result can be fetched. When next_poll_after_seconds is present, wait that long before the next poll; otherwise back off exponentially.

How do I read a slow job?

Match what you see to the cause. Events that stop at job.queued mean the job is waiting for a slot: that is normal admission, not a failure. Concurrency depends on the plan, and Sume exposes queue counts rather than a per-job queue position or ETA. Events that reach generation.submitted and stay there mean work is in flight; keep polling.

For video, avatar-video and face-swap jobs, the 30-second sync wait routinely runs out. The response is still a success and carries the job id plus status_url, result_url, events_url and cancel_url. Continue with the status URL; do not submit again.

What do I do with a failed job?

Failed jobs expose public error metadata such as category, stage, retryability and a next action. Categories include validation (fix the input), quota (add funds or lower the cost), queue (retry later with the same idempotency key) and generation_rejected (inspect events and fix the unsupported input).

Retry with the same Idempotency-Key only when the request body is unchanged. A changed body under an old key returns 409 idempotency_conflict.

When can I cancel?

Only before generation starts. Once it has, POST /v1/jobs/{id}/cancel returns 409 job_generation_already_started with details.cancelable: false, and the job completes or fails on its own. Cancelling an already canceled job is idempotent.

If you lose a job id altogether, list the resource instead: find a lost avatar video job walks through it. Request ids from error bodies are safe to share with support.