Let users pick an avatar in your app with GET /v1/avatar-1.0/avatars

To let people choose an avatar in your own product, read the avatars from your server with GET /v1/avatar-1.0/avatars, cache the list, and send the chosen handle to POST /v1/avatar-1.0/talking-video. Your browser never sees a Sume API key, and the picker only offers avatars that exist in the workspace the key belongs to.

The three calls in the flow

The picker uses the read routes that are already part of Avatar 1.0, plus the video submit.

Keep the key on the server

Your page calls your own endpoint, such as /api/avatars, and your server calls Sume with Authorization: Bearer $SUME_API_KEY. Workspace context comes from the key, so you do not send a workspace id. Do not paste the key into front-end code, and rotate it if it ever appears in a log or a chat history (Authentication).

Cache and refresh

Avatars change rarely. Cache the list for a few minutes in memory or in your database, and refresh it after you create a new avatar. A short cache keeps your picker fast and spares your read budget, because a request that is rate limited returns 429 with retry-after.

Store the handle, not only the display name. The handle is what the video request needs, and Sume stores it lowercase without any leading @.

Do not offer an avatar that is not ready

Creating an avatar is a job. Until that job completes, the avatar is not ready for talking videos. Filter your picker to ready avatars, or show the others disabled with a message. If a user submits a handle that is not ready, expect an error rather than a video, and show it in plain words.

After the user picks and writes a script, submit the video with an idempotency key built from your own record id, such as the draft id. That way a double click returns the original job. Then show progress from your own job table while you poll.

What this is not

This is a picker for avatars you or your workspace made. It is not a public stock gallery, and these docs do not describe one. If your users need their own face, give them an upload form that creates a new avatar from a reference photo, and keep a record of their consent next to the handle.