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.9
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| livekit_plugins_bithuman-1.8.9.tar.gz | 13.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| livekit_plugins_bithuman-1.8.9-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 26.2 kB
Release files / livekit_plugins_bithuman-1.8.9.tar.gz
| Download URL | livekit_plugins_bithuman-1.8.9.tar.gz |
|---|---|
| Size | 13.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d8c23ec960457e73c8660e9bf10353b2bed1d5ca57d15b7891d163350bcd8cd5
|
|
BLAKE2b-256 checksum How to use checksums |
474e0a46b06d87b4b70e39f908596eeaa60f39528b9e3edecb3af2689f8b99c4
|
| Upload date | |
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.
Transparency logRelease files / livekit_plugins_bithuman-1.8.9-py3-none-any.whl
| Download URL | livekit_plugins_bithuman-1.8.9-py3-none-any.whl |
|---|---|
| Size | 13.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3be221265170609329a8604ae73de03fd82827e656c50395ab09b7616dc05732
|
|
BLAKE2b-256 checksum How to use checksums |
64c8adcb7dc1bdcbc2e86d6e6d20456bdd324f85ed65b6b76dbd170b75a943b7
|
| Upload date | |
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.
Transparency log
