Serve and script the CLI

Serve live sessions, set the voice and script the CLI.

Integrate into your app

Job	Command
List the sample avatars	`bithuman list` (the same list as `https://api.bithuman.ai/v1/models/showcase`)
Download one	`bithuman pull <slug>` prints the cached path; `--force` downloads again
Download your own agent	`bithuman pull <AGENT_CODE> --model essence-2` (needs sign-in)
Inspect an avatar	`bithuman open <avatar>`
Render	`bithuman render <avatar> in.wav -o out.mp4` (a code or name is downloaded on first use)
Serve a live session	`bithuman run <avatar>`; `--host <LAN address>` to expose it (`0.0.0.0` also needs `BITHUMAN_ALLOW_PUBLIC_BIND=1`)
Talk with your own OpenAI key	`export OPENAI_API_KEY=…` before `bithuman run` (voice settings)
Run the brain on your own hardware	local conversation brain
Drive it from an AI agent	`bithuman mcp` (MCP server)
Script it	add `--json`: every failure prints one JSON object with a stable code, and the exit code is the contract (reference)

bithuman run starts a voice agent on OpenAI Realtime (the whole setup, and the same conversation in Python). Both settings are read from the environment:

Variable	Default	What it does
`OPENAI_API_KEY`	—	Your OpenAI key. Without it, the voice runs on your bitHuman account at the managed voice-chat rate, 10 credits per minute (pricing).
`BITHUMAN_INSTRUCTIONS`	a short assistant prompt	The agent’s system prompt

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 440 MB on Linux) to ~/.bithuman/engines/essence-2/ once.
Intel Macs have no binary. On Windows (not code-signed; Downloads) the CLI renders in the cloud; to render on the PC, use Python on Windows.