Skip to main content

bithuman

Run a bitHuman avatar on your own machine, in your own process.

pip install bithuman
DEMO=$(python -c 'import bithuman,os; print(os.path.join(os.path.dirname(bithuman.__file__), "assets", "demo_sample.wav"))')
python -m bithuman render sofia-ramirez "$DEMO"     # -> sofia-ramirez.mp4

Two arguments — an avatar and some audio — and a video you can play (with your API secret in BITHUMAN_API_SECRET; see the key). The avatar is a showcase name (python -m bithuman list), your agent's ten-character code (python -m bithuman list --mine; fetched once, which is free), or a file you already have. The audio above is 15 s of speech that ships with this package, so the first run needs nothing you do not already have. The commands are spelled as in the separate bithuman CLI: render <avatar> <audio> [-o out.mp4] [--limit N] [--json] and list [--mine]. If you signed in with that CLI (bithuman login, which this package does not install), the secret it saved is read here too.

In your own program it is the same two things. The command above fetched the avatar to ~/.cache/bithuman/showcase/:

import bithuman, os

speech = os.path.join(os.path.dirname(bithuman.__file__),
                      "assets", "demo_sample.wav")   # 15 s, ships in the wheel
avatar_file = os.path.expanduser("~/.cache/bithuman/showcase/sofia-ramirez.imx")

avatar = bithuman.open(avatar_file)
frames = 0
for image in avatar.render(speech):   # each image: (height, width, 3) uint8, RGB
    frames += 1
print(frames, "frames")

That is the whole thing: open an avatar, then render audio through it.

every family, the same two lines

Essence 1, Essence 2 (full body essence-2, or face only essence-2f) and Expression 2 avatars are opened and rendered by the code above, unchanged. Nothing you write says which one you have, and you do not have to know.

Two families need one extra package on the machine:

pip install "bithuman[essence-2]"      # the new Essence 2
pip install "bithuman[expression-2]"   # Expression 2

Open one of those avatars without its extra and the refusal says so, and says that line. Nothing else differs.

from the command line

python -m bithuman render <avatar> speech.wav              # -> <avatar>.mp4
python -m bithuman render <avatar> speech.wav --mode face  # Essence 2: face only
python -m bithuman pull <avatar>                            # fetch it now, render later with no network
python -m bithuman pack redeem                              # install a prepaid offline pack on this machine

An agent code renders in the agent's own model. An avatar made with Essence 2 renders in Essence 2; an agent made earlier keeps the model it has (Essence 2 legacy, Expression 2, Essence 1). --model picks another of the agent's models: essence-2, essence-2f (face), expression-2, or essence-2-legacy.

With an offline pack installed, a machine renders with no network and no API secret until the pack is spent; an avatar fetched before is used as it is.


The surface

you write it means
bithuman.open(source) open the avatar file on this machine; returns an Avatar
avatar.render(audio) yield the frames for that audio
Avatar what open gives you
AvatarError catch this for any refusal
InvalidAvatar we cannot find it, or it is not a usable avatar
NotSupported this avatar cannot run here
NotAuthorised the key is missing, invalid, or out of credit
Failed we could not do it — the message says which

There is nothing to configure: this package runs the avatar on this machine. For a live conversation, where audio arrives as it is spoken, use AsyncBithuman (streaming below).

audio in

audio is 16 kHz mono, and it is either a buffer or a stream — the same call:

avatar.render(speech)                      # an audio file path
avatar.render(samples)                     # int16 or float32 in [-1, 1]
avatar.render(raw_bytes)                   # 16 kHz mono, signed 16-bit
avatar.render(microphone())                # any iterable of the above

frames out

Each frame is a (height, width, 3) uint8 array in RGB order, in order, at the avatar's own frame rate, which is a property of the avatar, not something to choose: 25 per second for Essence 2, 20 per second for Expression 2.

import cv2
for image in avatar.render(speech):
    cv2.imshow("avatar", image[:, :, ::-1])   # OpenCV wants BGR
    cv2.waitKey(1)

stopping early

Someone interrupting the avatar is "stop consuming and close the iterator":

images = avatar.render(speech)
for n, image in enumerate(images):
    if n == 50:                       # e.g. the user started talking
        images.close()
        break

releasing it

with frees everything at the end of the block; without it, the avatar is freed when it is garbage collected.

with bithuman.open(avatar_file) as avatar:
    for image in avatar.render(speech):
        frames += 1

streaming a live conversation

AsyncBithuman takes audio as it arrives and yields frames with their audio, paced at the avatar's play rate:

from bithuman import AsyncBithuman          # inside an async function:

avatar = await AsyncBithuman.create(model_path=avatar_file)   # reads BITHUMAN_API_SECRET
await avatar.push_audio(pcm16_bytes, 16000, last_chunk=False)  # as the audio arrives
await avatar.flush()                                            # end of the reply
async for frame in avatar.run():
    if frame.has_image:
        show(frame.bgr_image)            # BGR numpy array
    if frame.audio_chunk:
        play(frame.audio_chunk.array)    # the audio that goes with this frame
await avatar.shutdown()

The full example is at https://docs.bithuman.ai/platforms/python/app.


The four refusals

Each one leads to a different fix, and none of them asks you to know anything about how we are built.

try:
    avatar = bithuman.open(avatar_file)
    for image in avatar.render(speech):
        pass
except bithuman.InvalidAvatar:
    ...   # fix the path or the code, or fetch the avatar again
except bithuman.NotSupported:
    ...   # use the cloud package, or another device
except bithuman.NotAuthorised:
    ...   # fix the credential
except bithuman.Failed:
    ...   # retry, then report it

Every one of them is an AvatarError, so except bithuman.AvatarError catches all four.


The key

Rendering is metered, and the key belongs in the environment rather than in your code:

export BITHUMAN_API_SECRET=...

Without one, render refuses with NotAuthorised before it hands you a frame. Get a key at https://www.bithuman.ai/developer/api-keys.

python -m bithuman also reads a .env file in the current directory; that is deprecated and will stop, so export the variable instead. What is already in the environment always wins.


Where it runs

Python 3.10 – 3.14
macOS Apple silicon
Linux x86-64 and arm64
Windows Windows 11, x86-64 (64-bit Python)
Intel Macs, Windows on Arm no wheel — pip install refuses rather than quietly giving you an old release

ffmpeg is used to read an audio file when it is on your PATH; when it is not, the decoder this package already installs reads the same file in this process, so it is not something to install first.

Three environment variables:

BITHUMAN_API_SECRET your API secret, from https://www.bithuman.ai/developer/api-keys — rendering is metered, so it is required unless you pass api_secret=. BITHUMAN_API_KEY is read as a deprecated alias
BITHUMAN_CACHE_DIR where a prepared avatar is kept (default ~/.cache/bithuman)
BITHUMAN_AVATAR_CACHE_GB the most space prepared avatars may take (default 10). One copy is kept per avatar file content; the least recently used ones that no process has open are removed above it

This package never puts a command on your PATH

pip install bithuman installs a library and nothing else — and python -m bithuman is why that costs you nothing: a module needs no script, cannot collide with one, and is there the moment pip finishes. The full bithuman command-line tool (a live avatar, a conversation) is a different artifact and is not installed with pip:

curl -fsSL https://install.bithuman.ai | sh
brew tap bithuman/bithuman https://gitlab.com/bithuman/sdk/homebrew-bithuman \
  && brew install bithuman/bithuman/bithuman-cli         # macOS, equivalently (always tap with the URL)

That is on purpose: a pip-installed command named bithuman would overwrite the one the CLI installer or Homebrew put at the same path.


Using it from a LiveKit agent

The LiveKit integration is a separate package, livekit-plugins-bithuman, published by LiveKit out of github.com/livekit/agents:

pip install livekit-plugins-bithuman "bithuman[expression-2]"

Do not give that plugin your account API secret. Up to and including 1.8.4, the plugin copies the secret it is given into the avatar's participant attributes, which every participant in the LiveKit room can read. Keep the secret on your server under another name (BITHUMAN_MASTER_SECRET), mint a one-hour runtime token per session (POST /v1/runtime-tokens/mint) and pass that token to the plugin instead. The worker is at https://docs.bithuman.ai/platforms/livekit.


Licence

Commercial software. Terms of use: https://www.bithuman.ai/legal/terms

Metadata

Release files for bithuman 2.12.12

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

Built distributions (wheels)

Table of built distributions (wheels) for bithuman 2.12.12
File Actions
bithuman-2.12.12-cp314-cp314-manylinux_2_28_x86_64.whl CPython 3.14 CPython 3.14 Linux glibc 2.28+ x86-64 Details for bithuman-2.12.12-cp314-cp314-manylinux_2_28_x86_64.whl
bithuman-2.12.12-cp314-cp314-macosx_14_0_arm64.whl CPython 3.14 CPython 3.14 macOS 14.0+ ARM64 Details for bithuman-2.12.12-cp314-cp314-macosx_14_0_arm64.whl
bithuman-2.12.12-cp313-cp313-manylinux_2_28_x86_64.whl CPython 3.13 CPython 3.13 Linux glibc 2.28+ x86-64 Details for bithuman-2.12.12-cp313-cp313-manylinux_2_28_x86_64.whl
bithuman-2.12.12-cp313-cp313-macosx_14_0_arm64.whl CPython 3.13 CPython 3.13 macOS 14.0+ ARM64 Details for bithuman-2.12.12-cp313-cp313-macosx_14_0_arm64.whl
bithuman-2.12.12-cp312-cp312-manylinux_2_28_x86_64.whl CPython 3.12 CPython 3.12 Linux glibc 2.28+ x86-64 Details for bithuman-2.12.12-cp312-cp312-manylinux_2_28_x86_64.whl
bithuman-2.12.12-cp312-cp312-macosx_14_0_arm64.whl CPython 3.12 CPython 3.12 macOS 14.0+ ARM64 Details for bithuman-2.12.12-cp312-cp312-macosx_14_0_arm64.whl
bithuman-2.12.12-cp311-cp311-manylinux_2_28_x86_64.whl CPython 3.11 CPython 3.11 Linux glibc 2.28+ x86-64 Details for bithuman-2.12.12-cp311-cp311-manylinux_2_28_x86_64.whl
bithuman-2.12.12-cp311-cp311-macosx_14_0_arm64.whl CPython 3.11 CPython 3.11 macOS 14.0+ ARM64 Details for bithuman-2.12.12-cp311-cp311-macosx_14_0_arm64.whl
bithuman-2.12.12-cp310-cp310-manylinux_2_28_x86_64.whl CPython 3.10 CPython 3.10 Linux glibc 2.28+ x86-64 Details for bithuman-2.12.12-cp310-cp310-manylinux_2_28_x86_64.whl
bithuman-2.12.12-cp310-cp310-macosx_14_0_arm64.whl CPython 3.10 CPython 3.10 macOS 14.0+ ARM64 Details for bithuman-2.12.12-cp310-cp310-macosx_14_0_arm64.whl

Total release size: 305.8 MB

Release files / bithuman-2.12.12-cp314-cp314-manylinux_2_28_x86_64.whl

Download URL bithuman-2.12.12-cp314-cp314-manylinux_2_28_x86_64.whl
Size 23.9 MB
Tags CPython 3.14 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
f8e16624bce64fc7076c13924a1162767be5e84dc4f8280e5809b7a44d82763e
BLAKE2b-256 checksum
How to use checksums
251d1eaba589f715d0f02383c78dd160b6e3dfe2dde00f29948cdcedcbdc258d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.14.6

Release files / bithuman-2.12.12-cp314-cp314-macosx_14_0_arm64.whl

Download URL bithuman-2.12.12-cp314-cp314-macosx_14_0_arm64.whl
Size 37.3 MB
Tags CPython 3.14 macOS 14.0+ ARM64
SHA-256 checksum
How to use checksums
2d50dab38d0932491131fcf66e3c8414730be5631bb15dbf8919b61939341ee8
BLAKE2b-256 checksum
How to use checksums
fc910d15545c683b745f63997d2d2fdb6f79236df73b29594c1d28d8b64bb0bc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.14.6

Release files / bithuman-2.12.12-cp313-cp313-manylinux_2_28_x86_64.whl

Download URL bithuman-2.12.12-cp313-cp313-manylinux_2_28_x86_64.whl
Size 23.9 MB
Tags CPython 3.13 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
4b9b96e3563619d6be0218bd84481b199c7d02d264d2e3e75c8152be6ac681e8
BLAKE2b-256 checksum
How to use checksums
4b06679da77081448fa2c963d2c123342fbae8631b7e908dcb7fd737a73ba199
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.14.6

Release files / bithuman-2.12.12-cp313-cp313-macosx_14_0_arm64.whl

Download URL bithuman-2.12.12-cp313-cp313-macosx_14_0_arm64.whl
Size 37.3 MB
Tags CPython 3.13 macOS 14.0+ ARM64
SHA-256 checksum
How to use checksums
b7895d18e001f30b9ddb0775845cc37a1dde5062af82294a20058615af6f3c3c
BLAKE2b-256 checksum
How to use checksums
7f95d6791436c48d2d53b680265e9e6c4afc698b4ecdddc486f890bc0cbbdeca
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.14.6

Release files / bithuman-2.12.12-cp312-cp312-manylinux_2_28_x86_64.whl

Download URL bithuman-2.12.12-cp312-cp312-manylinux_2_28_x86_64.whl
Size 23.9 MB
Tags CPython 3.12 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
09ff8af49d5c8846b74fa41eceb104dd4d892212c049fbfd4fc9b627ff57b8d9
BLAKE2b-256 checksum
How to use checksums
ea49b91a7568a5546ccfa31c3a2ee7bcf72b72e697cf4693c985cde9c8c23706
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.14.6

Release files / bithuman-2.12.12-cp312-cp312-macosx_14_0_arm64.whl

Download URL bithuman-2.12.12-cp312-cp312-macosx_14_0_arm64.whl
Size 37.3 MB
Tags CPython 3.12 macOS 14.0+ ARM64
SHA-256 checksum
How to use checksums
eab1d99fffe50e3a4f0e149cabb16a685ec77fa41805fc5963882ac874117272
BLAKE2b-256 checksum
How to use checksums
e2ca2768ba6ee3a87ab9726dbc89aea710f8e786cda6eb43ecc0eb7580b5e98d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.14.6

Release files / bithuman-2.12.12-cp311-cp311-manylinux_2_28_x86_64.whl

Download URL bithuman-2.12.12-cp311-cp311-manylinux_2_28_x86_64.whl
Size 23.9 MB
Tags CPython 3.11 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
4acb53eb145be1418df1f0fcd5afd60b79035b1775d726bfd118a1e5f2b99a53
BLAKE2b-256 checksum
How to use checksums
3107ac7dce5c0cff2710aa40d96c41735b2a671ed6c64ed254bda8a0808f9379
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.14.6

Release files / bithuman-2.12.12-cp311-cp311-macosx_14_0_arm64.whl

Download URL bithuman-2.12.12-cp311-cp311-macosx_14_0_arm64.whl
Size 37.3 MB
Tags CPython 3.11 macOS 14.0+ ARM64
SHA-256 checksum
How to use checksums
18b1bd4a04a0e754a0a7961b7ac4e40758ae06ad2a83da79fa5a6a57061bae10
BLAKE2b-256 checksum
How to use checksums
a59276a2b45b480667d55e80c4994ecb6519b1f9c96fb66f103103ec80b3fed2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.14.6

Release files / bithuman-2.12.12-cp310-cp310-manylinux_2_28_x86_64.whl

Download URL bithuman-2.12.12-cp310-cp310-manylinux_2_28_x86_64.whl
Size 23.9 MB
Tags CPython 3.10 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
b2619c19c6bb6e91afb2afbe576ca846d14ae2e704a095693e1f64d6f59bf161
BLAKE2b-256 checksum
How to use checksums
6a8e3b90f0e52d255f1dbdc4f31f55a717aab17c7b02248dfff4f1a4f2cae596
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.14.6

Release files / bithuman-2.12.12-cp310-cp310-macosx_14_0_arm64.whl

Download URL bithuman-2.12.12-cp310-cp310-macosx_14_0_arm64.whl
Size 37.3 MB
Tags CPython 3.10 macOS 14.0+ ARM64
SHA-256 checksum
How to use checksums
e5f8cfa709567dee8e3f4df0c710892ca06dac1f1b95af188179cb53c2c363b9
BLAKE2b-256 checksum
How to use checksums
7bb62c99e1c023c5a8bac960704d2041924ffa00a5deadcad65fe2c6094bee69
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.14.6

Security for bithuman 2.12.12

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page