LiveKit docs › Models › Virtual avatar › Hedra

---

# Hedra Realtime Avatar integration guide

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

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

> ⚠️ **Deprecated**
> 
> Hedra sunset their Realtime Avatar product on April 15, 2026. This plugin no longer functions. Browse [12+ other avatar integrations](https://docs.livekit.io/agents/models/avatar.md) instead.

## 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.

### Installation

**Python**:

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

```

---

**Node.js**:

```shell
pnpm add @livekit/agents-plugin-hedra

```

> ℹ️ **Python only**
> 
> 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**:

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

server = AgentServer()

@server.rtc_session(agent_name="my-agent")
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....
   )

```

---

**Node.js**:

```typescript
import { voice } from '@livekit/agents';
import * as hedra from '@livekit/agents-plugin-hedra';

const session = new voice.AgentSession({
   // ... stt, llm, tts, etc.
});

const avatar = new hedra.AvatarSession({
   avatarId: "...",  // ID of the avatar to use. See "Avatar setup" for details.
});

// Start the avatar and wait for it to join
await avatar.start(session, room);

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

```

Preview the avatar in the [Agent Console](https://docs.livekit.io/agents/start/console.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 it to the `AvatarSession`:

**Python**:

```python
from PIL import Image

# Create a PIL Image object
avatar_image = Image.open("/path/to/image.jpg")

# Pass the custom image to the avatar session
avatar = hedra.AvatarSession(
   avatar_image=avatar_image,
)

```

---

**Node.js**:

```typescript
import fs from 'node:fs';

// Read an image file
const imageBuffer = fs.readFileSync('path/to/avatar.jpg');

// Create an avatar session with a custom image
const avatar = new hedra.AvatarSession({
  avatarImage: {
    data: imageBuffer,
    mimeType: 'image/jpeg',
    filename: 'avatar.jpg',
  },
});

```

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/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.

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

- **[Agent Console](https://docs.livekit.io/agents/start/console.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-06-07T11:35:39.393Z.
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).