CLI

One binary, no code: bithuman render turns an audio file into a talking-avatar MP4, and bithuman run opens a live conversation with an avatar in your browser. It renders on your own machine. To program against the models instead, use Python.

Note: On Linux, both models run live on the CPU alone, no GPU. See CPU only (no GPU).

Detail	Expression 2	Essence 2
Renders	any character from one portrait	a photoreal person from one portrait
render and run	both	both
Download per avatar	about 190 MB	140–160 MB, plus a shared audio encoder (about 66 MB) once

Play with sound (6 seconds, captions)

Before you start

Install

# macOS (Apple silicon): also installs ffmpeg, livekit-server and Python
brew install bithuman-product/bithuman/bithuman-cli

# Linux, x86_64 or arm64 (Debian/Ubuntu); the download includes livekit-server
sudo apt install -y ffmpeg python3-venv
curl -fsSL https://install.bithuman.ai | sh

The installer puts the CLI in ~/.local/bin (set BITHUMAN_INSTALL_DIR to change it) and verifies its checksum. If it asks you to, add export PATH="$HOME/.local/bin:$PATH" to your shell profile. On macOS, curl -fsSL https://install.bithuman.ai | sh installs the same release (then brew install ffmpeg livekit yourself). bithuman --version prints the CLI and engine versions.

Check the install:

$ bithuman --version
libessence 2.11.16 ABI 7
bithuman    2.8.3

The CLI is not on PyPI. pip install bithuman installs the Python library, which has no command.

Authenticate

bithuman login            # opens a browser and stores a credential for this device
bithuman login --device   # over SSH: prints a code to enter in any browser
bithuman account          # exit 0 when signed in

Sign in first, because every render path needs a credential: without one, run and render stop before the first frame with exit 77 and write nothing. In scripts and CI, set BITHUMAN_API_SECRET instead of signing in (Your API secret). Credits pay for session time, talking or idle, by the exact second (pricing). Listing, downloading and opening avatars need no account.

First frame

Render the sample speech through the wise-pup sample avatar:

bithuman login
curl -fsSLo speech.wav https://docs.bithuman.ai/samples/speech.wav
bithuman render wise-pup speech.wav -o out.mp4
# → out.mp4: 416×720, 300 frames, 15.0 s

Then talk to it live:

bithuman run wise-pup
# → open the printed http://127.0.0.1:8088/<CODE> and allow the microphone

render accepts any audio format ffmpeg reads. bithuman run needs two more things from Before you start: livekit-server and Python. It starts a local livekit-server and the voice agent; the first run installs the agent, about 350 MB on disk, in one to two minutes.

Complete example

From a fresh machine to a talking-avatar MP4 in four commands.

Requirements

Run it

curl -fsSL https://install.bithuman.ai | sh
export BITHUMAN_API_SECRET="<your API secret>"
curl -fsSLo speech.wav https://docs.bithuman.ai/samples/speech.wav
bithuman render wise-pup speech.wav

Expected output

wise-pup.mp4: 416×720, as long as the audio (15 seconds for the sample). To talk to the avatar instead, run bithuman run wise-pup and open the printed URL (this also needs livekit-server; see CLI).

Make it your own

• Your own avatar: create one with the Agents API (or on bitHuman), then bithuman pull <AGENT_CODE> and render it the same way.
• Your own words: any audio file ffmpeg reads works as the second argument; generate speech with Text to speech.
• A photoreal person: bithuman render sofia-ramirez speech.wav renders Essence 2 (this avatar is 1080×1920 portrait).
• Scripts and CI: add --json and branch on exit codes (reference).
• A conversation instead of a clip: bithuman run wise-pup — Talk to an avatar on your machine.

Integrate into your app

Voice settings

bithuman run starts a voice agent on OpenAI Realtime. Both settings are read from the environment:

The whole setup, and the same conversation in your own Python code: Talk to an avatar on your machine.

Platform notes

• Essence 1 avatars work with run only; for a file use Python or the video API. Expression 1 runs on the cloud API.
• The first Essence 2 render on a machine downloads a shared audio encoder (about 66 MB) to ~/.bithuman/engines/essence-2/ once.
• Intel Macs and Windows have no binary. Use WSL2 on Windows, or the web embed or cloud API.

Performance

Troubleshooting

Reference

• CLI reference: every command, flag, exit code and environment variable.
• Local conversation brain: run the conversation fully on your hardware.
• CLI example scripts: live stream, offline render, REST.
• Changelog and Downloads & versions.