Avatars
An avatar is the face a session renders. You reference one by its av_... ID
when you create a session.
The avatar object
Section titled “The avatar object”| Field | Type | Notes |
| -------------- | -------------- | ------------------------------------------- |
| id | string | av_... |
| object | "avatar" | |
| name | string | Human-readable name. |
| status | AvatarStatus | ready | processing | failed |
| runtime_type | string | mock in v0; real model types land later. |
| is_demo | bool | true for platform built-ins. |
| created_at | timestamp | |
List avatars
Section titled “List avatars”GET /v1/avatars returns the avatars available to your org, including platform
demo avatars. v0 returns only built-in demos such as av_demo. Cursor
pagination applies.
const page = await client.avatars.list();for (const a of page.data) console.log(a.id, a.name, a.status);curl https://api.protoface.com/v1/avatars \ -H "Authorization: Bearer $PROTOFACE_API_KEY"Retrieve an avatar
Section titled “Retrieve an avatar”GET /v1/avatars/{avatar_id} returns a single avatar.
const avatar = await client.avatars.get("av_demo");console.log(avatar.status); // "ready"curl https://api.protoface.com/v1/avatars/av_demo \ -H "Authorization: Bearer $PROTOFACE_API_KEY"Using an avatar in a session
Section titled “Using an avatar in a session”Pass the avatar’s id as avatar_id on session create. Only use avatars whose
status is ready:
const session = await client.sessions.createLivekit({ avatarId: "av_demo", url: process.env.LIVEKIT_URL!, roomName: "demo-room", workerToken,});