Avatar handle with a hyphen is rejected: the valid pattern

An avatar handle such as product-host does not match the pattern in the Sume OpenAPI: only letters, digits, periods and underscores are allowed, 2 to 30 characters, and a period or underscore cannot be first, last or doubled. Use product_host instead. A leading @ is optional: Sume lowercases the handle and stores it without the @.

What the pattern accepts

The Avatar 1.0 create route (POST /v1/avatar-1.0/generate) takes a top-level avatar_handle. The OpenAPI pattern for face swap and TTS is the same grammar: ^@?(?![._])(?!.*[._]$)(?!.*[._]{2})[A-Za-z0-9._]{2,30}$. The table runs ten candidates through that regex.

Check handles before you submit

Add a local check in your import script so a bad handle fails in your code and not in a batch of 200 creates. The pattern is the one from the docs; keep it in sync if the OpenAPI changes.

import re

HANDLE = re.compile(r"^@?(?![._])(?!.*[._]$)(?!.*[._]{2})[A-Za-z0-9._]{2,30}$")

def to_handle(name: str) -> str:
    """Turn a brand name into a legal handle, or raise."""
    cand = re.sub(r"[^A-Za-z0-9._]+", "_", name.strip()).strip("._")
    cand = re.sub(r"[._]{2,}", "_", cand)
    if not HANDLE.match(cand):
        raise ValueError(f"no legal handle for {name!r}")
    return cand.lower()

print(to_handle("Product Host"))    # product_host
print(to_handle("brand-host.v2"))  # brand_host.v2

Limits and gotchas

• The handle is the name you reuse later in avatar_handle on talking videos, so pick one you will not want to change.
• Handles must be normalized by you if you compare them: @Product.Host and product.host are the same avatar.
• The same grammar applies when you pass avatar_handle to TTS or face swap, so one validator covers all three.
• Creating the avatar is a fixed per-avatar price, listed in GET /v1/catalog.