# Source: https://docs.livekit.io/agents/models/avatar/plugins/hedra.md

LiveKit docs › Models › Virtual avatar › Plugins › Hedra

---

# Hedra Realtime Avatar integration guide

> How to use the Hedra virtual avatar plugin for LiveKit Agents.

Available in:
- [ ] Node.js
- [x] Python

## Overview

[Hedra's](https://hedra.ai/) Realtime Avatars let you create your own avatar that can participate in live, interactive conversations. You can use the open source Hedra integration for LiveKit Agents in your voice AI app.

- **[Hedra avatar examples](https://github.com/livekit-examples/python-agents-examples/tree/main/complex-agents/avatars/hedra)**: Multiple full-stack examples showing creative uses of Hedra Realtime Avatars with LiveKit Agents.

## Quick reference

This section includes a basic usage example and some reference material. For links to more detailed documentation, see [Additional resources](#additional-resources).

### Installation

Install the plugin from PyPI:

```shell
uv add "livekit-agents[hedra]~=1.3"

```

If you plan to upload images directly, also install the LiveKit images dependency, which includes Pillow version 10.3 and above:

```shell
uv add "livekit-agents[images]"

```

### Authentication

The Hedra plugin requires a [Hedra API key](https://www.hedra.com/api-profile).

Set `HEDRA_API_KEY` in your `.env` file.

### Usage

Use the plugin in an `AgentSession`. For example, you can use this avatar in the [Voice AI quickstart](https://docs.livekit.io/agents/start/voice-ai.md).

```python
from livekit import agents
from livekit.agents import AgentServer, AgentSession
from livekit.plugins import hedra

server = AgentServer()

@server.rtc_session()
async def my_agent(ctx: agents.JobContext):
   session = AgentSession(
      # ... stt, llm, tts, etc.
   )

   avatar = hedra.AvatarSession(
      avatar_id="...",  # ID of the Hedra avatar to use. See "Avatar setup" for details.
   )

   # Start the avatar and wait for it to join
   await avatar.start(session, room=ctx.room)

   # Start your agent session with the user
   await session.start(
      # ... room, agent, room_options, etc....
   )

```

Preview the avatar in the [Agents Playground](https://docs.livekit.io/agents/start/playground.md) or a frontend [starter app](https://docs.livekit.io/agents/start/frontend.md#starter-apps) that you build.

### Avatar setup

The Hedra plugin requires a source image asset from which to generate the avatar. Avatars render as 512x512px square videos. Hedra automatically centers and crops around the face within the provided image. Hedra supports humanoid faces, in a range of styles from photorealistic to animated.

You can specify the avatar image by ID or by passing an image directly.

#### Pass avatar ID

To use an existing avatar, pass the `avatar_id` parameter to the plugin. You can find the ID in the Hedra web studio or upload it using the Hedra API.

##### Web studio

Generate or upload an image in the [Hedra web studio](https://www.hedra.com/app/image). To find the ID to pass as `avatar_id`, download the image from the [library](https://www.hedra.com/app/library). The avatar ID is the filename of the downloaded image, minus the extension.

##### API upload

To upload an image with the Hedra API, first create a new asset:

```shell
curl -X POST \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"type":"image","name":"<your-avatar-name>"}' \
  https://api.hedra.com/web-app/public/assets

```

The response includes an asset `id`, which you need for the next step.

Then upload the image:

```shell
curl -X POST \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@<your-local-image-path>" \
  https://api.hedra.com/web-app/public/assets/<your-asset-id>/upload

```

You can now use the asset ID in the Hedra plugin as the `avatar_id`.

#### Pass image directly

To upload a new image directly in the plugin, pass a PIL `Image` object in the `avatar_image` parameter.

```python
from PIL import Image

avatar_image = Image.open("/path/to/image.jpg")

avatar = hedra.AvatarSession(
   avatar_image=avatar_image,
)

```

The plugin uploads the image to Hedra and uses it for the avatar session. The image can come from anywhere, including your local filesystem, a remote URL, [uploaded in realtime from your frontend](https://docs.livekit.io/transport/data/byte-streams.md#sending-files), or generated by an external API or AI model.

### Parameters

This section describes some of the available parameters. See the [plugin reference](https://docs.livekit.io/reference/python/v1/livekit/plugins/hedra/index.html.md#livekit.plugins.hedra.AvatarSession) for a complete list of all available parameters.

- **`avatar_id`** _(string)_ (optional): ID of the Hedra avatar to use. See [Avatar setup](#avatar-setup) for details.

- **`avatar_image`** _(string)_ (optional): PIL `Image` object to use for the avatar. See [Image upload](#image-upload) for details.

- **`avatar_participant_name`** _(string)_ (optional) - Default: `hedra-avatar-agent`: The name of the participant to use for the avatar.

## Additional resources

The following resources provide more information about using Hedra with LiveKit Agents.

- **[Python package](https://pypi.org/project/livekit-plugins-hedra/)**: The `livekit-plugins-hedra` package on PyPI.

- **[Plugin reference](https://docs.livekit.io/reference/python/v1/livekit/plugins/hedra/index.html.md)**: Reference for the Hedra avatar plugin.

- **[GitHub repo](https://github.com/livekit/agents/tree/main/livekit-plugins/livekit-plugins-hedra)**: View the source or contribute to the LiveKit Hedra avatar plugin.

- **[Hedra API docs](https://api.hedra.com/web-app/redoc)**: Hedra's API docs.

- **[Agents Playground](https://docs.livekit.io/agents/start/playground.md)**: A virtual workbench to test your avatar agent.

- **[Frontend starter apps](https://docs.livekit.io/agents/start/frontend.md#starter-apps)**: Ready-to-use frontend apps with avatar support.

---

This document was rendered at 2026-02-03T03:25:07.362Z.
For the latest version of this document, see [https://docs.livekit.io/agents/models/avatar/plugins/hedra.md](https://docs.livekit.io/agents/models/avatar/plugins/hedra.md).

To explore all LiveKit documentation, see [llms.txt](https://docs.livekit.io/llms.txt).