What to show a viewer while an avatar video job is queued

Show a plain waiting state with the job's real status, not a fake progress bar. A Sume avatar video job moves through queued, processing, and then one of three terminal states: completed, failed, or canceled. Sume avatars are async jobs: you submit a request, get a job id back, and read the finished video later. There is no live video session. Your page should therefore be built around a status, a result link, and a retry rule.

The Jobs and results page states that queued is a normal accepted state for paid generation. Workspace concurrency limits apply when workers move a job into processing, not when the API accepts a valid job. A viewer who sees "queued" has not hit an error.

Status to screen map

The status endpoint returns booleans (terminal, result_ready) and sume_status. It also returns a queue-shaped status field (IN_QUEUE, IN_PROGRESS, COMPLETED, FAILED, CANCELED) that maps one-to-one onto sume_status. Pick one and use it everywhere.

Polling rules that keep you out of trouble

Use exponential backoff, or follow next_poll_after_seconds when the response includes it. Stop on completed, failed, or canceled. If your own process times out, do not submit the original paid request again; poll the same job id, or retry the submit with the same Idempotency-Key so you get the original job back and not a second bill.

A client-side timeout does not cancel the job. It keeps running and keeps its reservation. If a viewer closes the tab, you can still collect the result later from the job id, which is why you should store the id before you return anything to the page.

Do not promise seconds

The docs say that avatar-video and face-swap jobs usually do not finish inside the 30-second wait budget that sync offers, and that a 30-second wait is an HTTP budget, not a job duration. For a viewer-facing page, that means two designs work: email or notify when the job completes (webhook mode, with polling as a backup), or an "we will show it here" page that polls in the background.

If the viewer must see a face in under a second, that is a real-time product, and Sume does not offer a live session. If a clip a few minutes from now is fine, the states above are all you need.

Admission errors are not job states

A request can also be refused before a job exists, for example 402 insufficient_credits when Sume cannot reserve the estimated cost. That response has no job id, so your UI should treat it as a form error, not as a waiting state. Read the Generation admission page for the queue-full and tier-limit cases.

A small waiting component

Keep the page logic small. On load, read the job id from your own database. Render the state from the last status you stored. A background worker, or a short poll in the page, updates the status. When the job is completed, store the media URL from the result and switch the page to the player. When it ends in failed, show a retry button that creates a new request, with a new Idempotency-Key, only after the user confirms.

Elapsed time is the one honest number you can show. The status fields above carry no percentage, so a bar that fills to 80% and stalls teaches viewers not to trust the page. A line such as "Started 2 minutes ago, we will email you when it is ready" is accurate at every moment.

If an admin or teammate needs to stop a job that has not started yet, cancellation is a request, and a job that has already started generation can answer with a conflict. Design the cancel button to say "requested" and then wait for the terminal state, instead of assuming the job is gone.