bitHuman plugin for LiveKit Agents

Support for bitHuman virtual avatars in LiveKit Agents. The avatar renders either locally, inside your agent's process from a bitHuman .imx model file (no GPU required), or in the bitHuman cloud, where it joins the room as a participant.

See the bitHuman integration docs for more information, and bitHuman's LiveKit guide for a complete agent.

Installation

pip install livekit-plugins-bithuman

To render Expression 2 models locally, also install the SDK's Expression 2 extra:

pip install "bithuman[expression-2]"

Pre-requisites

You'll need an API secret from bitHuman (create one). Store it under a name the plugin doesn't read, such as BITHUMAN_MASTER_SECRET, and pass it as api_secret=. If api_secret isn't passed, the plugin falls back to BITHUMAN_API_SECRET.

In cloud mode the plugin puts api_secret in the avatar participant's attributes, which everyone in the room can read. Pass a one-hour token minted for one agent and one room (POST https://api.bithuman.ai/v1/runtime-tokens/mint, how) instead of the secret, and keep BITHUMAN_API_SECRET unset. Cloud mode also uses LIVEKIT_URL, LIVEKIT_API_KEY and LIVEKIT_API_SECRET.

Usage

Local mode: the avatar renders in this process.

import os

from livekit.plugins import bithuman

avatar = bithuman.AvatarSession(
    model_path="./agent.imx",  # or set BITHUMAN_MODEL_PATH
    api_secret=os.environ["BITHUMAN_MASTER_SECRET"],
)
await avatar.start(session, room=ctx.room)

Cloud mode: the avatar renders on bitHuman's servers.

avatar = bithuman.AvatarSession(
    avatar_id="A23WJF0199",  # your bitHuman agent code (A23WJF0199 is the wise-pup sample)
    api_secret=minted_token,  # from POST /v1/runtime-tokens/mint
)
await avatar.start(session, room=ctx.room)

In both modes the avatar publishes the agent's audio, so start the session with room_options=room_io.RoomOptions(audio_output=False).

Models

Essence 2 (essence-2): a photoreal person from one portrait.
Expression 2 (expression-2): any character, including people, animals and cartoons, from one portrait.
essence / expression: the first-generation Essence 1 and Expression 1. Expression 1 runs in the cloud only.

In local mode the .imx file decides the model. In cloud mode, leave model unset to use the model the agent was created with, or set it to pin one; bitHuman refuses a model the avatar wasn't prepared for. A photo passed as avatar_image (no avatar_id) works only with Expression 1. Pricing: docs.bithuman.ai/pricing.

Metadata

Release files for livekit-plugins-bithuman 1.8.7

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for livekit-plugins-bithuman 1.8.7
File	Size	Uploaded
livekit_plugins_bithuman-1.8.7.tar.gz	13.1 kB	Oct 9, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for livekit-plugins-bithuman 1.8.7
File	Interpreter	ABI	Platform	Reset
livekit_plugins_bithuman-1.8.7-py3-none-any.whl 13.0 kB Oct 9, 2026	Python 3	none	any	Details

Total release size: 26.2 kB

Release files / livekit_plugins_bithuman-1.8.7.tar.gz

Download URL	livekit_plugins_bithuman-1.8.7.tar.gz
Size	13.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`82103e6150e15c174851bc7dcb4d038fb2c7f04491c8c6ae4d5972c7ec3a7a0c`
BLAKE2b-256 checksum How to use checksums	`425230fa88df030458e97d4d933495ffc1091a1cf920d75d3561f74923d6d28f`
Upload date	Oct 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/livekit/agents
Publishing commit: github.com/livekit/agents/tree/294de277c49ffa879ff7194a08f87c1a96a87a99

Workflow

Publishing configuration: github.com/livekit/agents/blob/294de277c49ffa879ff7194a08f87c1a96a87a99/.github/workflows/publish.yml
Publishing logs: github.com/livekit/agents/actions/runs/37997829530/attempts/1

Artifact

Subject: livekit_plugins_bithuman-1.8.7.tar.gz
SHA-256 checksum: 82103e6150e15c174851bc7dcb4d038fb2c7f04491c8c6ae4d5972c7ec3a7a0c Verifying attestations

Release files / livekit_plugins_bithuman-1.8.7-py3-none-any.whl

Download URL	livekit_plugins_bithuman-1.8.7-py3-none-any.whl
Size	13.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`d8f1205aee5392380d1fad38620c302c6e756755be95983a94119be9ac04da0c`
BLAKE2b-256 checksum How to use checksums	`5630da7b8a52df6435ea5e34f83a739d634602b1cc48e3040d725f5d4c3c059e`
Upload date	Oct 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/livekit/agents
Publishing commit: github.com/livekit/agents/tree/294de277c49ffa879ff7194a08f87c1a96a87a99

Workflow

Publishing configuration: github.com/livekit/agents/blob/294de277c49ffa879ff7194a08f87c1a96a87a99/.github/workflows/publish.yml
Publishing logs: github.com/livekit/agents/actions/runs/37997829530/attempts/1

Artifact

Subject: livekit_plugins_bithuman-1.8.7-py3-none-any.whl
SHA-256 checksum: d8f1205aee5392380d1fad38620c302c6e756755be95983a94119be9ac04da0c Verifying attestations