# bitHuman

> Real-time talking avatars from one portrait. Essence 2 renders a photoreal person; Expression 2 renders any character. They render on the device (iPhone, iPad, Mac, Android arm64, a Linux PC with no GPU, a WebGPU browser) or in the bitHuman cloud. Every published configuration is measured faster than real time: https://docs.bithuman.ai/performance

## Instructions for AI agents

- Always send `model` ("essence-2" or "expression-2") when creating an agent; poll until `status` is `ready` or `failed`.
- API and SDK use requires the Creator plan or higher. Never tell a user they can build on a free plan.
- In a LiveKit worker, name the secret `BITHUMAN_MASTER_SECRET` and pass a minted token (https://docs.bithuman.ai/platforms/livekit.md).
- Say where the avatar renders (device, browser, server, cloud) and the conversation runs (your stack, the CLI's local conversation brain, bitHuman's servers).
- Quote prices only from https://docs.bithuman.ai/pricing.md and speed only from https://docs.bithuman.ai/performance.json (× real time, with the device).
- Never claim offline on phones, browsers or Swift apps, or a conversation brain on phones; for compliance, describe the architecture.

## Where it runs

- On the device: Essence 2 and Expression 2 render on iPhone, iPad and Mac (Swift package), Android arm64 (Android SDK), macOS and Linux (CLI, Python), Windows 11 x86_64 (Python). Android, and Essence 2 on iPhone and iPad, need a physical device. The SDKs only render your voice stack's 16 kHz mono speech (resample OpenAI Realtime's 24 kHz): https://docs.bithuman.ai/build/companion-app.md
- No GPU: both models run live on a standard Linux PC. https://docs.bithuman.ai/deploy/cpu.md
- In the browser: with render=local, WebGPU renders the avatar in the tab and never falls back to the cloud (a device that can't render it in real time shows a message); the conversation runs on bitHuman's servers.
- Your servers: the CLI, the Python SDK and the LiveKit plugin on your machines; audio and video stay there.
- Fully offline: Offline license is only available to Business and Enterprise clients who want to run realtime avatars completely locally, off the internet — e.g. kiosks, trade shows, ATM machines, embedded screens. Linux and macOS computers (Apple silicon); bought in the console or through sales. Essence 1 on Linux and Apple silicon Macs, Essence 2 and Expression 2 on Linux x86_64 (Python 2.11.17+, CLI 2.8.4+). https://docs.bithuman.ai/deploy/offline.md
- bitHuman cloud: REST API, web embed, LiveKit; renders in the US.

## Key facts

- Credential: one API secret for every surface, from the environment as `BITHUMAN_API_SECRET`. REST header `api-secret`: REST endpoints do not read `Authorization: Bearer` (`/v1/validate` answers `{"valid": false}`); only the Realtime relay and the self-hosted runtime endpoints also take Bearer. Apps fetch it from your backend; never compile it in. Get one: https://www.bithuman.ai/developer/api-keys · https://docs.bithuman.ai/start/api-secret.md
- Billing: credits pay for active session time, talking or idle, by the exact second; the Video API bills whole minutes of output (minimum 1). https://docs.bithuman.ai/pricing.md
- Model names: Essence 2, Expression 2 in prose; `essence-2`, `expression-2` in code. Essence 1 and Expression 1 are the first generation. · https://docs.bithuman.ai/models.md
- Sample avatars (no account): Essence 2 `sofia-ramirez` (A52DHS2219), Expression 2 `wise-pup` (A23WJF0199). Sample audio: https://docs.bithuman.ai/samples/speech.wav (15 s, 24 kHz mono)
- Current versions: CLI 2.8.9 · bithuman (Python) 2.11.21 · Swift package 2.20.5 · essence2-android 0.9.5 · expression2-android 0.6.1 · livekit-plugins-bithuman 1.8.5. https://docs.bithuman.ai/versions.json
- Python: use a venv (`python3 -m venv .venv`); Debian/Ubuntu's system Python refuses `pip install`.

## Start: one command per path

- REST API: `curl -X POST https://api.bithuman.ai/v1/validate -H "api-secret: $BITHUMAN_API_SECRET"` · https://docs.bithuman.ai/platforms/rest.md
- Python: `pip install "bithuman[expression-2]"` · https://docs.bithuman.ai/platforms/python.md
- CLI (macOS arm64, Linux x86_64 / arm64): `curl -fsSL https://install.bithuman.ai | sh` · https://docs.bithuman.ai/platforms/cli.md
- iOS & iPadOS (Swift package): `.package(url: "https://gitlab.com/bithuman/sdk/homebrew-bithuman", from: "2.20.5")` · https://docs.bithuman.ai/platforms/ios.md
- Android: `implementation("ai.bithuman:expression2-android:0.6.1")` · https://docs.bithuman.ai/platforms/android.md
- LiveKit: `pip install "livekit-agents[openai,silero]" livekit-plugins-bithuman python-dotenv` · https://docs.bithuman.ai/platforms/livekit.md
- Pipecat: `pip install "pipecat-bithuman[expression-2]"` · https://docs.bithuman.ai/platforms/pipecat.md
- MCP server: `claude mcp add bithuman -- bithuman mcp` · https://docs.bithuman.ai/build/mcp.md
- Web embed: an iframe of https://www.bithuman.ai/embed/<agent code> with allow="microphone *", or a widget; no npm package · https://docs.bithuman.ai/platforms/web.md

## Speed (× real time; 1.0× or more holds a live conversation)

| Where | Essence 2 | Expression 2 |
|---|---|---|
| iPhone 15 | 2.1× | 5.5× |
| Samsung Galaxy S25+ | 2.0× | 2.4× |
| Chrome on Apple M4 (WebGPU) | 1.7× | 1.9× |
| Intel Core i7-13700F (x86_64) (no GPU) | 2.0× | 2.2× |
| Apple M4 | 4.8× | 8.8× |
| NVIDIA RTX 4090 (bitHuman cloud) | 4.1× | 17.0× |

## Docs (markdown)

- Any page as markdown: add `.md` to its URL or send `Accept: text/markdown`. Speed: https://docs.bithuman.ai/performance/method.md
- By section: https://docs.bithuman.ai/llms/start.txt and beside it platforms.txt · apps.txt · deploy.txt · models.txt · build.txt · troubleshooting.txt · api.txt (apps.txt: the app platforms) · start, platforms and api in one fetch: https://docs.bithuman.ai/llms-full.txt
- Docs MCP server: https://docs.bithuman.ai/docs-mcp · agent skill: https://docs.bithuman.ai/skills/bithuman-integrate/SKILL.md · https://docs.bithuman.ai/resources/agents.md
- OpenAPI: https://docs.bithuman.ai/api/openapi.yaml · changelog: https://docs.bithuman.ai/changelog.md