Avatar handle with a leading @: how Sume stores and reuses it

Sume accepts an avatar_handle with or without a leading @ and stores it normalized, without the @. So @product_host and product_host name the same avatar. The models overview recommends a stable handle because it gives your app or agent a simple name to reuse instead of relying only on a generated id.

This is from Create new avatar and the models overview.

Where does the handle go?

On creation it is the top-level avatar_handle next to the input union. On rendering it is the top-level avatar_handle beside script or video_inputs. The docs examples use lowercase words joined with underscores, such as product_host, reference_presenter and studio_presenter; the docs do not publish the full allowed character set, so stick to that style.

curl -X POST https://api.sume.com/v1/avatar-1.0/talking-video \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: host-intro-001" \
  -d '{
    "avatar_handle": "@product_host",
    "script": "Welcome to the October release. Here are three things that changed."
  }'

Why prefer the handle over the avatar id?

Avatar creation is job-backed, and the avatar becomes a resource only when the job completes. A handle you chose is known before that, so your code, your config and your agent prompt can all refer to it from day one. A generated id has to be read back from the job result first.

What can go wrong?

Avatar video requests need a ready avatar, so do not send a render until the creation job is completed. Keep one handle per identity; the video request supports one resolved avatar per final video, which is why a two-host show is two videos, covered in one avatar per video for a two-host podcast. The docs do not describe renaming a handle, so treat it as permanent when you choose it.

How do I see what I already have?

List avatars with GET /v1/avatar-1.0/avatars and read one with /:id. Before creating a new avatar, check that the handle is not already in your workspace; the reusable avatar guide shows the create-once habit.

How should I name handles in a team?

Pick a convention before the first avatar exists: lowercase words with underscores, one role per handle, and a suffix if you need variants. For example product_host and product_host_alt read clearly in a config file and in an agent prompt. Avoid putting dates or campaign names in a handle, since the handle outlives the campaign.

Can an agent pick the handle for me?

Yes, but give it the list. With MCP, avatars_list and avatars_search are read tools, so an agent can look up the handles in your workspace before it calls avatar-videos_create, which is a paid tool. Naming the handle in the prompt avoids the agent inventing one that does not exist.