Avatar handle with an @ prefix: Sume stores it without the @

Yes, you can type the handle with a leading @ when you create an avatar. The Create new avatar page says the handle can start with @, and that Sume normalizes the handle and stores it without the @. So @product_host and product_host name the same avatar after creation, and the stored value is product_host.

Sume avatars are async jobs: you submit a request, get a job id back, and read the finished video later. There is no live video session. That matters here because the handle is the only thing that ties a script to a face. Creating the avatar is one job, and each talking video that uses the handle is another job.

What Sume does with the handle

Avatar creation uses a top-level avatar_handle plus an input union. The input is one of three types: a text prompt, structured profile traits (the API type is props), or a reference photo (the API type is photo). Each request creates a job, and you poll that job until it completes. Then you use the returned handle or resource id for talking videos.

The normalization rule is a convenience for people and agents who write handles the way they appear on social media. You do not need a pre-processing step in your code to remove the @. If you want one canonical spelling in your own database, store the handle as it comes back from the job result, not as you typed it.

Create with an @ and keep the key stable

Send an Idempotency-Key on the create call so a client retry after a timeout returns the original job instead of a second one. The price of one avatar creation is a flat $0.95 (provider-pricing rate card sume_flat_avatar_creation_price), so a double submit without a key is a real double charge.

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: avatar-product-host-001" \
  -d '{
    "avatar_handle": "@product_host",
    "input": {
      "type": "props",
      "ethnicity": "Asian",
      "sex": "female",
      "age": 28
    }
  }'

Using the handle in a talking video

Once the avatar job is completed, the talking-video route takes the top-level avatar_handle to pick the ready avatar. Provide one of script or video_inputs, never both, and plan for a duration between 4 and 60 seconds. The first-party docs show handles without an @ in the talking-video examples, so the safest habit is to use the handle exactly as the create result returns it.

If you let an agent pick handles, give it one rule: lowercase, underscores, no spaces, and no leading @ in anything you store. That avoids a situation where two spellings look different in a spreadsheet but resolve to the same avatar on Sume.

Checklist

• Leading @ on create is accepted; Sume stores the handle without it.
• Create is a job: poll /v1/jobs/:id/status, then read /v1/jobs/:id/result.
• Creation costs a flat $0.95 per avatar; reuse the handle for every later clip.
• Use Idempotency-Key on every paid submit, including creation.
• A handle that is already taken is a conflict, so plan names per client or per presenter.

Naming rules worth adopting

Handles are the stable key your team, your scripts, and any agent will use for months, so it pays to settle a convention before you create the first avatar. Pick one pattern and apply it everywhere: for example brand_role, such as acme_support_host or acme_launch_presenter. Short, readable names beat clever ones when someone has to find the right avatar in a list at the end of a long week.

Because creation is a paid job that ends with a reusable resource, do not create a fresh avatar for every video. Reading the list route (GET /v1/avatar-1.0/avatars) first, and reusing a handle that already exists, saves the $0.95 creation price each time and keeps the same face across a series of clips.

When a create call is rejected because the handle is already in use, treat that as information, not as a problem to work around by adding a random suffix. Either reuse the existing avatar, or pick a name that says what is different about the new one.