LiveKit docs › Models › Virtual avatar › bitHuman

---

# bitHuman virtual avatar integration guide

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

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

## Overview

[bitHuman](https://www.bithuman.ai/) provides realtime virtual avatars that you can run either locally or in the cloud. You can use the open source bitHuman integration for LiveKit Agents to add virtual avatars to your voice AI app.

### Installation

Install the plugin from PyPI:

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

```

If you plan to use cloud-hosted models with images, also install the LiveKit images dependency, which includes Pillow version 10.3 and above:

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

```

### Authentication

The bitHuman plugin requires a [bitHuman API Secret](https://www.bithuman.ai/#api-keys).

Set `BITHUMAN_API_SECRET` in your `.env` file.

### Avatar setup

The bitHuman plugin supports three ways to set up avatars:

- pass `.imx` model files
- pass an image directly using PIL image objects or a source image path/URL
- pass bitHuman avatar IDs

#### Pass model files

Create and download a bitHuman `.imx` file from the [bitHuman console](https://www.bithuman.ai/#library) or download a [prebuilt model](https://www.bithuman.ai/#live). You can pass the model path to the avatar session or set the `BITHUMAN_MODEL_PATH` environment variable.

> ℹ️ **Note**
> 
> Agents consume more CPU when using `.imx` models directly.

#### Pass image directly

Pass an image directly in the `avatar_image` parameter using PIL image objects or a source image path/URL.

```python
from PIL import Image
from livekit.plugins import bithuman

bithuman_avatar = bithuman.AvatarSession(
    avatar_image=Image.open(os.path.join(os.path.dirname(__file__), "avatar.jpg")),
)

```

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.

#### Pass avatar ID

You can use an existing avatar by passing the `avatar_id` parameter to the plugin. You can find the ID in the [bitHuman console](https://www.bithuman.ai/#library) in the description of the avatar on the **Library** page.

### Usage

You can use the bitHuman 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).

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.

The following code uses a local bitHuman `.imx` model.

```python
from livekit.plugins import bithuman

session = AgentSession(
   # ... stt, llm, tts, etc.
)

avatar = bithuman.AvatarSession(
    model_path="./albert_einstein.imx", # This example uses a demo model installed in the current directory
)

# 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=ctx.room,
)

```

The following code uses an image or avatar ID.

```python
from livekit.agents import room_io
from livekit.plugins import bithuman
from PIL import Image

avatar = bithuman.AvatarSession(
    avatar_image=Image.open("avatar.jpg").convert("RGB"), # This example uses an image in the current directory.
    # or: avatar_id="your-avatar-id" # You can also use an existing avatar ID.
)

await avatar.start(session, room=ctx.room)

await session.start(
    room=ctx.room,
    room_options=room_io.RoomOptions(audio_output=False),
)

```

### Parameters

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

- **`model`** _(string | Literal['essence', 'expression'])_: Model to use. `expression` provides dynamic expressions and emotional responses. `essence` uses predefined actions and expressions.

- **`model_path`** _(string)_ (optional) - Environment: `BITHUMAN_MODEL_PATH`: Path to the bitHuman `.imx` model.

- **`avatar_image`** _(PIL.Image.Image | str)_ (optional): Avatar image to use. Pass a PIL image (`Image.open("avatar.jpg")`) or a string (local path to the image).

- **`avatar_id`** _(string)_ (optional): The avatar ID from bitHuman.

## Additional resources

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

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

- **[Plugin reference](https://docs.livekit.io/reference/python/livekit/plugins/bithuman.md)**: Reference for the bitHuman avatar plugin.

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

- **[bitHuman docs](https://docs.bithuman.ai)**: bitHuman's full API docs site.

- **[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:11.242Z.
For the latest version of this document, see [https://docs.livekit.io/agents/models/avatar/plugins/bithuman.md](https://docs.livekit.io/agents/models/avatar/plugins/bithuman.md).

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