Python

A file in and frames out, or a live stream of audio in and frames out, on your own machine.

Before you start

To run an avatar without code, use the CLI.

Note: On Linux and Windows, Python renders both models on the CPU alone, no GPU. On macOS it renders on Apple silicon. Windows has its own page: Windows. See CPU only (no GPU).

Install

python3 -m venv .venv
source .venv/bin/activate
pip install "bithuman[expression-2]"

Install into a virtual environment: Debian and Ubuntu refuse a system-wide pip install (externally-managed-environment). If venv is missing, run sudo apt install -y python3-venv first. The package installs no command-line tool.

Authenticate

Set BITHUMAN_API_SECRET in the shell that runs Python (bithuman.open reads it), or pass api_secret= to AsyncBithuman.create(). Downloading a sample avatar needs no account.

Run your first avatar

export BITHUMAN_API_SECRET="<your API secret>"
curl -fL -o wise-pup.imx "https://api.bithuman.ai/v1/agent/A23WJF0199/model/download?model=expression-2"
curl -fsSLo speech.wav https://docs.bithuman.ai/samples/speech.wav

import bithuman
bithuman.open("wise-pup.imx").render("speech.wav", out_mp4="out.mp4")
# → out.mp4: wise-pup speaking the sample, 416×720, 15 s

Open out.mp4 to watch it talk. out_mp4= needs no ffmpeg, and render returns the number of frames written. It takes a path to an audio file (WAV, MP3 and the other common formats), or already-decoded 16 kHz mono audio (int16 or float32 arrays, or raw 16-bit bytes). The same call opens Essence 2 and Essence 1 .imx files: for a photoreal person, download the sofia-ramirez Essence 2 sample with curl -fL -o sofia-ramirez.imx "https://api.bithuman.ai/v1/agent/A52DHS2219/model/download?model=essence-2" and render it the same way (1080×1920).

To process the frames yourself, iterate over render without out_mp4=:

import bithuman

with bithuman.open("wise-pup.imx") as avatar:
    frames = [image for image in avatar.render("speech.wav")]
print(len(frames), "frames of", frames[0].shape)
# → 300 frames of (720, 416, 3)

Frames are RGB; OpenCV expects BGR, so write one with cv2.imwrite("frame.png", image[:, :, ::-1]).

Play with sound (8 seconds, captions)

Performance

A finished render logs its own rate on the bithuman logger at INFO.