Is my avatar ready? GET /avatars with status=ready and a handle filter

To check that one Sume avatar is ready before you render a video, call GET /v1/avatar-1.0/avatars?status=ready&handle=<handle>. If the handle comes back in data.avatars, it is a completed avatar you can use; if the list is empty, the avatar job is still running or did not finish, and a talking-video request would be premature.

The query parameters come from the Avatar 1.0 list operation in the live OpenAPI schema: limit, status and handle. status accepts queued, processing, completed, failed, canceled, and ready, which the schema describes as a resource-friendly alias for completed jobs. handle is an optional avatar handle filter that accepts the stored handle with or without the leading @.

Why check before rendering?

Creating an avatar is a job, and the Avatar guide says to poll it until it completes before using the returned handle for avatar videos. Skipping that wait is how an integration ends up submitting a video against an avatar that does not exist yet. A cheap read call is a better guard than a failed paid submit.

Which status value should you filter on?

Use ready for the question you actually have. The other values answer different questions.

How do you do it in Python?

The helper below returns True only when the filtered list contains at least one avatar. It uses requests and reads the list shape the schema documents, data.avatars. It does not guess at fields inside each avatar summary.

import os
import requests

URL = "https://api.sume.com/v1/avatar-1.0/avatars"
HEADERS = {"Authorization": f"Bearer {os.environ['SUME_API_KEY']}"}


def avatar_is_ready(handle: str) -> bool:
    resp = requests.get(
        URL,
        headers=HEADERS,
        params={"status": "ready", "handle": handle, "limit": 1},
        timeout=30,
    )
    resp.raise_for_status()
    return len(resp.json()["data"]["avatars"]) > 0


if __name__ == "__main__":
    print(avatar_is_ready("shop_owner"))

What should you do when it is not ready?

Do not loop on the list route. Poll the avatar job itself at /v1/jobs/:id/status, which is the route Jobs and results documents for waiting, and then read the result. The list check is for a gate at the start of a pipeline, not for a wait loop.

Because the filter accepts a handle with or without @, you do not need to normalise it before the call. Stored handles drop the @ either way.

What does this not tell you?

A ready avatar does not guarantee a video will look right; that is what a first-frame preview is for. It also does not check your script length, which must estimate to 4-60 seconds. And it only sees avatars in the workspace your API key belongs to.

What about the resource route for one avatar?

If you already hold the avatar id, GET /v1/avatar-1.0/avatars/{id} reads one avatar directly, and it returns 404 when the resource is not in your workspace. The list route with handle is for when you only know the handle. Older compatibility paths such as GET /v1/avatars still exist, but new integrations should use the Avatar 1.0 routes.

In a CLI flow, sume avatars list --agent --json serves the same purpose as the list call here.