Name your avatars: a handle scheme that fits 2 to 30 characters

A Sume avatar handle must be 2 to 30 characters of letters, digits, periods and underscores. It cannot start or end with a period or underscore, and it cannot contain two of them in a row. Hyphens are not allowed. Pick a scheme that fits these rules before the first avatar exists, because the handle is what every later talking-video request uses.

The rules, in one table

These come from the Avatar 1.0 request schema in the published OpenAPI and the create-avatar docs.

A scheme that survives the rules

Because hyphens are out, use underscores between parts and periods only when you want a visible group break. A readable pattern is brand, role and version: acme_host_v2. It is 12 characters, which leaves room. Avoid putting a customer or campaign name in a handle, since handles are meant to be reused across many videos.

• Brand or team first, so a sorted list groups avatars together.
• Role second: host, demo, support, founder.
• Version last, so a re-created face does not overwrite the old handle.
• Keep a spreadsheet or table of handle, source, owner and creation date.

Why the lowercase detail matters

Sume lowercases the handle when it stores it. If your own system keeps Acme_Host and compares it with the stored acme_host, a case-sensitive check will say they differ. Lowercase handles in your code at the moment you write them to your database.

Read them back

List the avatars in a workspace with GET /v1/avatar-1.0/avatars, or read one by id with GET /v1/avatar-1.0/avatars/{id}. A handle is only useful for a talking video once the avatar is ready, so check its state first rather than assuming that a returned job id means a usable avatar.

In a multi-scene video, each scene in video_inputs can carry its own avatar reference, and the request can hold up to 20 scenes. Today one final video resolves to one avatar, so plan one handle per video.

Retiring a handle

Do not reuse a handle for a different face. Create a new one with a version bump and move your templates to it. The old handle stays in your history so old videos still make sense.