409 avatar_handle_reserved: why handles starting sume_ are off limits

The error

When you create an avatar with avatar_handle set to something like sume_clawra, the API answers 409 with code avatar_handle_reserved. The message says the handle uses the reserved sume_ prefix and asks you to choose a non-reserved handle for user-created avatars.

The details object carries three fields: handle (what you sent), reserved_prefix (sume_) and reserved_for (system_avatars).

Why the prefix is blocked

Sume ships system avatars whose handles start with sume_. The Avatar video docs use one in an example, sume_clawra, as a ready avatar you can reference in a talking video. Blocking the prefix on creation keeps a user avatar from ever shadowing a system one.

Reproduce it

curl -X POST https://api.sume.com/v1/avatar-1.0/generate \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reserved-demo-001" \
  -d '{"avatar_handle":"sume_myhost","input":{"type":"props","ethnicity":"Asian","sex":"female","age":28}}'

Fix

Rename the handle with a different first segment, for example myhost or brand_host. Use the same rules as any handle: lowercase letters, digits, dots and underscores, 2 to 30 characters. Reusing the old Idempotency-Key with a changed body gives a separate 409, idempotency_conflict, so send a fresh key with the new handle.

Using system avatars

You do not create a system avatar. You reference it by handle in a talking-video request when it is ready, the way the docs example does.