> ## Documentation Index
> Fetch the complete documentation index at: https://docs.protoface.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Avatars

> Create, list, and use avatars in realtime sessions.

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](/guides/avatar-source-images) has examples of portraits
that build and ones that fail.

## Create an avatar

```bash theme={null}
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

```bash theme={null}
curl https://api.protoface.com/v1/avatars \
  -H "Authorization: Bearer $PROTOFACE_API_KEY"
```

## Retrieve an avatar

```bash theme={null}
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:

```python theme={null}
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](/guides/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](/api-reference).

## Delete an avatar

```bash theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.