Avatar preview resource_status vs job_status: which field to poll

Use resource_status on the avatar video preview to know whether the resource is ready, and use job_status (or the job's own status and terminal fields) to poll the job. The docs say to prefer both over the legacy status field. Face swap resources follow the same advice: resource_status for readiness, job_status for polling.

Sources: Avatar video previews, Face swap (Beta) and Jobs and results.

Why are there two statuses?

A preview is a resource, and creating it starts a job. The job answers a question about work (queued, processing, finished). The resource answers a question about the thing you will use (ready, failed, canceled). They move together most of the time, but they are different facts, and reading the wrong one is how clients show a stale or missing preview.

What is the polling loop?

Submit, take the status_url from the response, and poll it with backoff until terminal is true; honor next_poll_after_seconds when it is present. Then read GET /v1/avatar-video-previews/:id and check resource_status. Only then read preview_image_url and scene_previews[].

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

curl https://api.sume.com/v1/avatar-video-previews/avp_123 \
  -H "Authorization: Bearer $SUME_API_KEY"

What if the job finished but the resource is not ready?

Do not infer readiness from the job alone. Read the resource, and if resource_status is failed or canceled, handle it as such rather than waiting. Never resubmit a paid request because a local worker timed out: retry the submit with the same Idempotency-Key, or keep polling. If you lose the id, list resources instead; see finding a lost avatar video job.

Does the same rule apply to final videos?

After generate-video, poll the returned job, then read GET /v1/avatar-videos/:id. Read the status vocabulary the same way: job for work, resource for use. A sync wait does not change this; it is capped at 30 seconds and avatar video usually outlasts it, as covered in sync mode and the 30-second wait.

What should my UI show at each state?

Map the two fields to what a user sees. While the job is queued or processing, show a progress state and keep polling. When the job is terminal and resource_status is ready, show the stills. If either side says failed, show the error and offer a retry that reuses nothing you do not need. If it says canceled, show that it was canceled rather than an error.

Do not poll tightly. The docs recommend exponential backoff and warn against tight loops across many jobs.

Where do webhooks fit?

If your server should be told rather than poll, submit with mode: "webhook" and a public HTTPS webhook_url. Sume sends terminal events only (job.completed, job.failed, job.canceled), signs them with HMAC SHA-256, and expects you to keep polling as a backup. A webhook says the job is done; you still read the resource to see whether it is ready.