Avatars

Every realtime session runs one avatar. Start with the stock avatar av_stock_001 while you validate session creation and media routing, then switch to a custom avatar built from the dashboard or the API. Building is asynchronous. You upload a PNG or JPEG portrait, and the avatar must reach status: "ready" before a session accepts it. Source images has examples of portraits that build and ones that fail.

Create an avatar

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

The portrait needs one clearly visible, forward-facing face or face-like subject. Avoid heavy occlusion, extreme crops, harsh lighting, and multiple faces. A "failed" build puts the reason on failure_reason.

List avatars

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

Retrieve an avatar

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

Poll this endpoint until status reaches ready or failed.

Use an avatar

Pass a ready avatar ID into the LiveKit plugin:

from livekit.plugins import protoface

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

The avatar starts before the agent session. Once running, avatar.session_id holds the Protoface sess_... ID, and GET /v1/sessions/{id} reports status and usage. End it with await avatar.aclose() or POST /v1/sessions/{id}/end. LiveKit Agents covers the plugin in full. Without the plugin, the avatar ID goes to POST /v1/sessions as avatar_id. The request shape is in API Reference.

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 source image and built assets. Past session and usage records remain. Stock avatars cannot be deleted.

Inference

Realtime

Account

Reference

Create an avatar

List avatars

Retrieve an avatar

Use an avatar

Delete an avatar

​Create an avatar

​List avatars

​Retrieve an avatar

​Use an avatar

​Delete an avatar

Create an avatar

List avatars

Retrieve an avatar

Use an avatar

Delete an avatar