Is my Sume avatar ready? Check resource_status and preview_video_url

A Sume avatar is ready when GET /v1/avatar-1.0/avatars/{id} returns resource_status: "ready". The same record also carries a preview_image_url, a nullable preview_video_url and a voice.status, and those are the fields worth reading before you spend money on your first talking video.

The field names below come from the published OpenAPI schema (PublicDeveloperApiAvatar) in the repository, read on 2026-10-11, and from the Create new avatar page. Creating the avatar costs a flat $0.95 per avatar in the catalog constants, and every video after that reuses the handle.

Which status field should I trust?

Use resource_status. Its values are processing, ready, failed and archived. The schema says it intentionally uses ready rather than the job-level completed when the avatar image is usable. The older status field is documented with the same four values, but the resource schema calls resource_status the canonical one.

The job still exists underneath. The record includes job_status (queued, processing, completed, failed, canceled or null) and a job object with status_url and result_url. Polling the job as described on Jobs and results works, but a UI that lists avatars should read the resource instead and show ready avatars only.

What do preview_image_url and preview_video_url give me?

preview_image_url is the representative public Sume-hosted image, set when the avatar is ready. preview_video_url is a representative public Sume-hosted preview video, and the schema marks it nullable: it is null when no public-safe preview video artifact exists yet. Raw provider URLs are never returned for either.

So treat the video as optional. A ready avatar with a null preview_video_url is not broken; render the still and move on. Do not block your "ready" state on the video, and do not poll for it forever. Re-read the record later if you want to show it.

Why check voice.status before a script that needs speech?

The voice object has a status of processing, ready or failed, or the whole object is null. The schema describes it as provider-neutral preparation state, and says an avatar whose voice is ready is the selector that the text-to-speech route resolves from avatar_id or avatar_handle. You never hold a voice id.

For a talking video you mainly care that the avatar itself is ready. If you also plan to narrate with the separate speech route, wait for voice.status to be ready too. A walk-through of that case is in which voice does my avatar speak with.

Fields at a glance

The table lists the fields to use for a readiness gate, with the behaviour the schema documents.

How do I list only usable avatars?

GET /v1/avatars accepts limit (1 to 100), status and handle. The status filter takes the job values plus ready, which the docs describe as a resource-friendly alias for completed jobs. The handle filter accepts the stored handle with or without a leading @. The Avatar 1.0 path GET /v1/avatar-1.0/avatars is the preferred route and returns the same shape.

A short loop that fits most apps: list with status=ready, cache the handle, and send it as avatar_handle on POST /v1/avatar-1.0/talking-video. If you submit before the avatar is ready, expect a conflict; the case is explained in the 409 post. Because the handle is stable, one $0.95 avatar serves every later clip, as in reusing one avatar for 40 clips.

curl "https://api.sume.com/v1/avatar-1.0/avatars?status=ready&limit=20" \
  -H "Authorization: Bearer $SUME_API_KEY"