Avatar video 409 avatar_not_ready: wait for the avatar to be ready

A 409 with error.code of avatar_not_ready on POST /v1/avatar-1.0/talking-video means the avatar you named is not ready yet. Sume's OpenAPI lists two stable 409 codes for avatar-video submit: avatar_not_ready, and idempotency_conflict when an Idempotency-Key was reused for a different payload. The fix for the first is to wait until the avatar's resource_status is ready, then submit again.

Why is the avatar not ready right after I created it?

Creating an avatar with POST /v1/avatar-1.0/generate starts a job. The create docs say to poll that job until it completes, then use the returned handle or resource id to generate avatar videos. Between the two, the avatar resource is processing.

The avatar schema says processing means the linked job is queued or running, and ready means public Sume-hosted image data is available. The other states are failed and archived.

Which field should I poll?

Read the avatar with GET /v1/avatar-1.0/avatars/{id} and check data.avatar.resource_status. The schema says this field uses ready rather than the job-level completed when the avatar image is usable, and it also returns job_status (queued, processing, completed, failed, canceled) for the underlying job.

Poll with a pause between calls. Sume's OpenAPI says the read budget defaults to 40 times the write budget, so a status loop does not use up your submit allowance.

curl https://api.sume.com/v1/avatar-1.0/avatars/avatar_123 \
  -H "Authorization: Bearer $SUME_API_KEY"

# proceed when data.avatar.resource_status == "ready"

What if the avatar ends up failed?

A failed avatar will not become ready by waiting. Create a new avatar and render with that one.

Keep the Idempotency-Key stable only while the payload is unchanged: reusing a key with a different body is the other 409, idempotency_conflict.