# 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 every 5 s until `status` is `ready` or `failed` (`success` is not final; a `final` field is coming). New Essence 2 agent: minutes; Expression 2: longer.
- 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 x86_64: Expression 2 now; Essence 1 and Essence 2 come later. Arranged through sales. 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/sign-up?next=%2Fdeveloper%2Fapi-keys&from=docs_header · https://docs.bithuman.ai/start/api-secret.md
- Billing: How billing works (https://docs.bithuman.ai/pricing#how-billing-works). 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; a file path is resampled for you, decoded arrays must be 16 kHz mono)
- Current versions: CLI 2.8.11 · bithuman (Python) 2.12.9 · Swift package 2.23.2 · essence2-android 0.10.3 · expression2-android 0.6.2 · livekit-plugins-bithuman 1.8.11. 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.23.2")` · https://docs.bithuman.ai/platforms/ios.md
- Android: `implementation("ai.bithuman:expression2-android:0.6.2")` · 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

## Python: start here

1. Install: `python3 -m venv .venv && . .venv/bin/activate && pip install "bithuman[expression-2]"`
2. Key: export BITHUMAN_API_SECRET (https://docs.bithuman.ai/start/api-secret.md); the sample avatar download needs no account.
3. First render: `bithuman.open("wise-pup.imx").render("speech.wav", out_mp4="out.mp4")` (a file path is resampled for you; decoded arrays must be 16 kHz mono; out_mp4 needs no display or GPU)
4. Talk to it: text in, OpenAI reply and voice (OPENAI_API_KEY), then render the reply file · https://docs.bithuman.ai/platforms/python.md#talk-to-it
5. See the rate: `logging.basicConfig(level=logging.INFO)` · avatar file about 120–200 MB · https://docs.bithuman.ai/platforms/python.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 M5 (WebGPU) | 4.0× | 2.4× |
| Intel Core i7-13700F (x86_64) (no GPU) | 2.0× | 2.2× |
| Apple M4 iMac (Mac16,3, 10-core GPU) | 4.3× | 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
- bitHuman characters in ChatGPT or Claude (hosted MCP, no sign-in): https://mcp.bithuman.ai/mcp · https://docs.bithuman.ai/build/chatgpt.md · https://docs.bithuman.ai/build/claude.md
- Docs MCP server (setup: https://docs.bithuman.ai/resources/agents.md) · agent skill: https://docs.bithuman.ai/skills/bithuman-integrate/SKILL.md
- OpenAPI 3.1: https://docs.bithuman.ai/openapi.json (YAML: https://docs.bithuman.ai/api/openapi.yaml) · changelog: https://docs.bithuman.ai/changelog.md