Avatars

Each Protoface session renders one avatar. Start with av_stock_001 while you validate session creation and media routing, then switch to a custom avatar from the dashboard or API.

Create an avatar

Custom avatar builds are asynchronous. Upload a portrait image, then poll the avatar until status is ready or failed.

curl -X POST https://api.protoface.com/v1/avatars \
  -H "Authorization: Bearer $PROTOFACE_API_KEY" \
  -F "image=@portrait.png" \
  -F "name=Demo Avatar"

Source image checklist

Use a PNG or JPEG source image.
Use one clearly visible, forward-facing face or face-like subject.
Avoid heavy occlusion, extreme crop, harsh lighting, multiple faces, or screen-only/abstract faces without distinct features.
See Source Images for examples of good and bad portrait uploads.
If the avatar reaches status: "failed", check failure_reason on the avatar response before uploading a new source image.

List avatars

curl https://api.protoface.com/v1/avatars \
  -H "Authorization: Bearer $PROTOFACE_API_KEY"

Use avatars with status: "ready" in sessions.

Retrieve an avatar

curl https://api.protoface.com/v1/avatars/av_... \
  -H "Authorization: Bearer $PROTOFACE_API_KEY"

Use an avatar

from livekit.plugins import protoface

avatar = protoface.AvatarSession(avatar_id="av_stock_001")

When using the REST API, pass the same value as avatar_id in POST /v1/sessions.

Delete an avatar

curl -X DELETE https://api.protoface.com/v1/avatars/av_... \
  -H "Authorization: Bearer $PROTOFACE_API_KEY"

Deleting a custom avatar removes its uploaded source image and built assets. Past session and usage records remain. Stock avatars cannot be deleted.

Quickstart

Run a LiveKit Agents app with a Protoface avatar.

LiveKit Agents

Use an avatar with the plugin.

Get started

Integrations

Guides

Reference

Create an avatar

Source image checklist

List avatars

Retrieve an avatar

Use an avatar

Delete an avatar

Next

Quickstart

LiveKit Agents

​Create an avatar

​Source image checklist

​List avatars

​Retrieve an avatar

​Use an avatar

​Delete an avatar

​Next

Quickstart

LiveKit Agents

Create an avatar

Source image checklist

List avatars

Retrieve an avatar

Use an avatar

Delete an avatar

Next