Avatar video 404 "Avatar was not found": handle from another workspace

404 not_found with the message Avatar was not found. on POST /v1/avatar-1.0/talking-video means the avatar_handle you sent does not resolve to an avatar that your workspace can use. Two causes cover nearly every case: the handle is misspelled or never created, or the avatar belongs to a different workspace than the API key you are using. The response creates no job, reserves no usage and writes no ledger entry.

Avatar video requests are documented on Generate avatar video, read 2026-10-05. Avatars are workspace-scoped, which the test suite enforces: a handle from another workspace gets the same answer as a handle that does not exist.

Three different errors for a handle

Sume does not tell you which of the two it was. That is deliberate: confirming that a handle exists in someone else's workspace would leak information. Treat both as one case and check your side.

A third angle: the 404 comes before any billing logic. The test suite asserts that after the response there is no queued job and no ledger entry, so you can retry safely with a corrected handle without wondering whether you were charged for the failed call. See the price ladder for what a successful call costs by tier.

The request itself is otherwise valid, which means validation of the script, duration and quality happens independently. A request can be wrong in several ways at once, and you may see a different error after you fix the handle.

Check what your key can see

List the avatars your key can see and look for the handle. The list is scoped to the key's workspace, so a handle missing from it is the answer. The call is a read and costs nothing.

Compare the output with the handle in your request character by character. A trailing space, a different underscore or a handle from an older naming scheme are all common. If you keep handles in a config file, load them from one place and print them in your startup logs so a stale value is easy to spot.

curl -sS https://api.sume.com/v1/avatar-1.0/avatars \
  -H "Authorization: Bearer $SUME_API_KEY"
# look for your avatar_handle in the response
# not listed: wrong workspace key, misspelling, or never created

The two-workspace mistake

If you run more than one workspace, such as a staging and a production one, the usual cause is a key from one used with a handle created in the other. Put the workspace name next to each key in your secrets store, and have your client log the handle on 404, so the mismatch is visible in the first failed call.

Do not retry a 404. The answer will not change until the avatar exists in the right workspace. Create it there with the create route, wait for it to be ready, and then send the video request.

Copy handles, do not retype them

Copy handles exactly from the list or create response. The sume_ prefix is reserved for system avatars; names such as the default public avatars are people names, so check the list for the exact string instead of guessing one.

If the handle is found but the avatar is not usable yet, you will see 409 avatar_not_ready rather than 404, and that one is solved by waiting on the avatar job.