# bitHuman — documentation for agents

> Real-time talking avatars from one portrait. Index: https://docs.bithuman.ai/llms.txt · every page is also served as markdown at <url>.md · OpenAPI: https://docs.bithuman.ai/api/openapi.yaml

## 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 (Essence 2 2.0×, Expression 2 2.2× real time on Intel Core i7-13700F (x86_64)). 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.4 · 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`.

## Contents

This file inlines getting started, the code, terminal and agent platform pages (Python, CLI, Windows, LiveKit, Pipecat, REST) and the REST API; the app platform pages are in /llms/apps.txt. The same text by section, and the sections not inlined here:

- Get started (choose your path, your API secret, performance, FAQ, glossary): https://docs.bithuman.ai/llms/start.txt
- Platforms (Python, CLI, Windows, LiveKit, Pipecat, REST): https://docs.bithuman.ai/llms/platforms.txt
- App platforms (iOS & iPadOS, macOS, Android, Flutter, Web): https://docs.bithuman.ai/llms/apps.txt
- Deploy (bitHuman cloud, your servers, on the device, fully offline; CPU only; privacy; pricing): https://docs.bithuman.ai/llms/deploy.txt
- Models (Essence 2, Expression 2, the first generation, how it works): https://docs.bithuman.ai/llms/models.txt
- Build (voice agent, companion app, kiosk, talking video, avatars, personas, voices, gestures, MCP): https://docs.bithuman.ai/llms/build.txt
- Troubleshooting (symptoms and fixes, site-wide and for each platform): https://docs.bithuman.ai/llms/troubleshooting.txt
- REST API (agents, realtime, video, embedding, errors, rate limits): https://docs.bithuman.ai/llms/api.txt

- Quickstart — https://docs.bithuman.ai/start
- Your API secret — https://docs.bithuman.ai/start/api-secret
- Performance — https://docs.bithuman.ai/performance
- Python — https://docs.bithuman.ai/platforms/python
- Windows — https://docs.bithuman.ai/platforms/windows
- Build a Python app — https://docs.bithuman.ai/platforms/python/app
- CLI — https://docs.bithuman.ai/platforms/cli
- Serve and script the CLI — https://docs.bithuman.ai/platforms/cli/voice
- LiveKit — https://docs.bithuman.ai/platforms/livekit
- Build a LiveKit agent — https://docs.bithuman.ai/platforms/livekit/app
- Pipecat — https://docs.bithuman.ai/platforms/pipecat
- Build a Pipecat bot — https://docs.bithuman.ai/platforms/pipecat/app
- REST API — https://docs.bithuman.ai/platforms/rest
- Cloud avatar in your room — https://docs.bithuman.ai/platforms/livekit/cloud-avatar
- API overview — https://docs.bithuman.ai/api
- Authentication — https://docs.bithuman.ai/api/authentication
- Errors — https://docs.bithuman.ai/api/errors
- Rate limits — https://docs.bithuman.ai/api/rate-limits
- Realtime relay — https://docs.bithuman.ai/api/realtime
- Agents — https://docs.bithuman.ai/api/agents
- Embedding — https://docs.bithuman.ai/api/embedding
- Talking video API — https://docs.bithuman.ai/api/video

In https://docs.bithuman.ai/llms/apps.txt, https://docs.bithuman.ai/llms/deploy.txt, https://docs.bithuman.ai/llms/models.txt, https://docs.bithuman.ai/llms/build.txt, https://docs.bithuman.ai/llms/troubleshooting.txt (or read the .md twin):
- iOS & iPadOS — https://docs.bithuman.ai/platforms/ios.md
- macOS — https://docs.bithuman.ai/platforms/macos.md
- Build a Swift app — https://docs.bithuman.ai/platforms/swift/app.md
- Android — https://docs.bithuman.ai/platforms/android.md
- Build an Android app — https://docs.bithuman.ai/platforms/android/app.md
- Flutter — https://docs.bithuman.ai/platforms/flutter.md
- Build a Flutter app — https://docs.bithuman.ai/platforms/flutter/app.md
- Web embed — https://docs.bithuman.ai/platforms/web.md
- Build a web app — https://docs.bithuman.ai/platforms/web/app.md
- Render with WebGPU — https://docs.bithuman.ai/platforms/web/webgpu.md
- Put an animated character in an iPhone app — https://docs.bithuman.ai/build/how-to/iphone-character.md
- Give an app's voice assistant a face — https://docs.bithuman.ai/build/how-to/voice-assistant-face.md
- Pricing and credits — https://docs.bithuman.ai/pricing.md
- Estimate your costs — https://docs.bithuman.ai/pricing/estimate.md
- Deployment options — https://docs.bithuman.ai/deploy.md
- bitHuman cloud — https://docs.bithuman.ai/deploy/cloud.md
- Your servers (self-hosted) — https://docs.bithuman.ai/deploy/self-hosted.md
- CPU only (no GPU) — https://docs.bithuman.ai/deploy/cpu.md
- On the device — https://docs.bithuman.ai/deploy/on-device.md
- Fully offline — https://docs.bithuman.ai/deploy/offline.md
- Data flows & privacy — https://docs.bithuman.ai/deploy/privacy.md
- Security and retention — https://docs.bithuman.ai/deploy/privacy/retention.md
- Use cases — https://docs.bithuman.ai/deploy/use-cases.md
- Banking and ATMs — https://docs.bithuman.ai/deploy/use-cases/banking-and-atms.md
- Healthcare — https://docs.bithuman.ai/deploy/use-cases/healthcare.md
- Events and trade shows — https://docs.bithuman.ai/deploy/use-cases/events-and-trade-shows.md
- Compare models — https://docs.bithuman.ai/models.md
- Essence 2 — https://docs.bithuman.ai/models/essence-2.md
- Expression 2 — https://docs.bithuman.ai/models/expression-2.md
- First generation — https://docs.bithuman.ai/models/first-generation.md
- How it works — https://docs.bithuman.ai/models/how-it-works.md
- The avatar file — https://docs.bithuman.ai/models/avatar-file.md
- Voice agent — https://docs.bithuman.ai/build/voice-agent.md
- Voice agent in Python — https://docs.bithuman.ai/build/voice-agent/python.md
- Barge-in — https://docs.bithuman.ai/build/barge-in.md
- Create your own avatar — https://docs.bithuman.ai/build/create-avatar.md
- Persona — https://docs.bithuman.ai/build/persona.md
- Voices — https://docs.bithuman.ai/build/voices.md
- Gestures (Essence 1) — https://docs.bithuman.ai/build/gestures.md
- Website widget — https://docs.bithuman.ai/build/website-widget.md
- Companion app — https://docs.bithuman.ai/build/companion-app.md
- Kiosk on a Linux PC — https://docs.bithuman.ai/build/kiosk.md
- Talking video — https://docs.bithuman.ai/build/talking-video.md
- Claude & Cursor (MCP) — https://docs.bithuman.ai/build/mcp.md
- Troubleshooting — https://docs.bithuman.ai/resources/troubleshooting.md
- Swift troubleshooting — https://docs.bithuman.ai/platforms/swift/troubleshooting.md
- Android troubleshooting — https://docs.bithuman.ai/platforms/android/troubleshooting.md
- Flutter errors — https://docs.bithuman.ai/platforms/flutter/errors.md
- Flutter troubleshooting — https://docs.bithuman.ai/platforms/flutter/troubleshooting.md
- Web troubleshooting — https://docs.bithuman.ai/platforms/web/troubleshooting.md
- Python troubleshooting — https://docs.bithuman.ai/platforms/python/troubleshooting.md
- CLI troubleshooting — https://docs.bithuman.ai/platforms/cli/troubleshooting.md
- LiveKit troubleshooting — https://docs.bithuman.ai/platforms/livekit/troubleshooting.md
- Pipecat troubleshooting — https://docs.bithuman.ai/platforms/pipecat/troubleshooting.md

Linked, not inlined (read the .md twin):
- FAQ — https://docs.bithuman.ai/resources/faq.md
- Glossary — https://docs.bithuman.ai/resources/glossary.md
- How we measure — https://docs.bithuman.ai/performance/method.md
- Local conversation brain — https://docs.bithuman.ai/platforms/cli/local-brain.md
- Turn a drawing, mascot or pet photo into a talking character — https://docs.bithuman.ai/build/how-to/drawing-to-character.md
- Webhooks — https://docs.bithuman.ai/api/webhooks.md
- Runtime sessions — https://docs.bithuman.ai/api/runtime-sessions.md
- Knowledge — https://docs.bithuman.ai/api/knowledge.md
- Gestures API — https://docs.bithuman.ai/api/dynamics.md
- Files — https://docs.bithuman.ai/api/files.md
- Billing & usage — https://docs.bithuman.ai/api/billing.md
- API secrets API — https://docs.bithuman.ai/api/api-keys.md
- Organizations — https://docs.bithuman.ai/api/organizations.md
- Providers (BYOK) — https://docs.bithuman.ai/api/providers.md
- Examples: https://docs.bithuman.ai/examples.md · changelog: https://docs.bithuman.ai/changelog.md · API references: https://docs.bithuman.ai/platforms/cli/reference.md, https://docs.bithuman.ai/platforms/python/reference.md, https://docs.bithuman.ai/platforms/swift/reference.md, https://docs.bithuman.ai/platforms/android/reference.md
- Renamed and retired names: https://docs.bithuman.ai/resources/renamed.md

---

# Quickstart

URL: https://docs.bithuman.ai/start

## Choose your platform

| You want to… | Use | Needs | First command |
|---|---|---|---|
| Put an avatar on a website | Web embed | nothing | `<iframe src="https://www.bithuman.ai/embed/A23WJF0199" allow="microphone *" style="width:100%;height:600px;border:0"></iframe>` |
| Call it from any backend | REST API | API secret | `curl -X POST https://api.bithuman.ai/v1/validate -H "api-secret: $BITHUMAN_API_SECRET"` |
| Render or stream from Python | Python | API secret | `pip install "bithuman[expression-2]"` |
| Run it from a terminal | CLI (macOS arm64, Linux x86_64 / arm64) | sign-in | `curl -fsSL https://install.bithuman.ai \| sh` |
| Ship an iPhone, iPad or Mac app | iOS & iPadOS (Swift package) | Xcode 26+, API secret | `.package(url: "https://github.com/bithuman-product/homebrew-bithuman.git", from: "2.20.4")` |
| Ship an Android app | Android | arm64 device, API secret | `implementation("ai.bithuman:expression2-android:0.6.1")` |
| Add a face to a LiveKit voice agent | LiveKit | API secret | `pip install "livekit-agents[openai,silero]" livekit-plugins-bithuman python-dotenv` |
| Add a face to a Pipecat voice bot | Pipecat | API secret | `pip install "pipecat-bithuman[expression-2]"` |
| Drive it from Claude or Cursor | MCP server | sign-in | `claude mcp add bithuman -- bithuman mcp` |
| Run fully offline (kiosk, trade show, ATM) | Fully offline | Business or Enterprise plan; Essence 1 on Linux or an Apple silicon Mac, Essence 2 and Expression 2 on Linux x86_64 | — ([contact sales](https://www.bithuman.ai/enterprise?topic=offline#contact)) |

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.

## Run it

### Put an avatar on a website: Web embed

```html
<iframe src="https://www.bithuman.ai/embed/A23WJF0199" allow="microphone *" style="width:100%;height:600px;border:0"></iframe>
```

Expected: A live avatar in your page that listens and answers. Allow the microphone when the browser asks.

### Call it from any backend: REST API

```bash
export BITHUMAN_API_SECRET="<your API secret>"
curl -s -X POST https://api.bithuman.ai/v1/validate -H "api-secret: $BITHUMAN_API_SECRET"
# → {"valid":true}
```

Expected: Your API secret works. The API quickstart continues with a talking video of a sample agent speaking your audio, in minutes, then an agent of your own.

### Render or stream from Python: Python

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install "bithuman[expression-2]"
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
python -c 'import bithuman
with bithuman.open("wise-pup.imx") as a: print(sum(1 for _ in a.render("speech.wav")), "frames")'
# → 300 frames
```

Expected: 300 frames of 416×720 video: the 15 seconds of sample speech.

### Run it from a terminal: CLI (macOS arm64, Linux x86_64 / arm64)

```bash
# macOS: brew install ffmpeg   ·   Debian/Ubuntu: sudo apt install -y ffmpeg
curl -fsSL https://install.bithuman.ai | sh
export PATH="$HOME/.local/bin:$PATH"
bithuman login
curl -fsSLo speech.wav https://docs.bithuman.ai/samples/speech.wav
bithuman render wise-pup speech.wav -o out.mp4
# → out.mp4: 15 s of a talking avatar
```

Expected: out.mp4, 15 seconds of the avatar saying the sample. `bithuman run wise-pup` opens a live conversation instead.

---

# Your API secret

URL: https://docs.bithuman.ai/start/api-secret

> The one credential for every bitHuman surface, and where each platform reads it.

One API secret works for the REST API, the CLI, Python, Swift, Android and LiveKit. It needs a bitHuman account on the Creator plan or higher ([pricing](https://docs.bithuman.ai/pricing)); the live demo and the web embed need none.

## Get one

Create an API secret under [Developer → API Secrets](https://www.bithuman.ai/developer/api-keys), then export it:

```bash
export BITHUMAN_API_SECRET="<your API secret>"
curl -s -X POST https://api.bithuman.ai/v1/validate -H "api-secret: $BITHUMAN_API_SECRET"
# → {"valid":true}
```

## Where each platform reads it

| Platform | Environment | In code |
|---|---|---|
| REST API | — | header `api-secret` |
| CLI | `BITHUMAN_API_SECRET` | `bithuman login` stores a credential for you |
| Python | `BITHUMAN_API_SECRET` (read by `bithuman.open`) | `api_secret=` on `AsyncBithuman.create()` only; `bithuman.open()` reads the environment |
| Apple | `BITHUMAN_API_SECRET` | `Essence2Credential.set` / `Expression2Credential.set` |
| Android | — | `Essence2Credential.set(secret)` / `Expression2Credential.set(secret)` before `fetch()` and `create()`; fetch the secret from your backend in a shipped app |
| LiveKit worker | `BITHUMAN_MASTER_SECRET`, never `BITHUMAN_API_SECRET` | a short-lived token minted from it, never the secret ([LiveKit](https://docs.bithuman.ai/platforms/livekit#authenticate)) |
| Web embed | — | none for a public agent; an [embed token](https://docs.bithuman.ai/api/embedding) for a private one |

## Keep it safe

- Keep the secret in the environment or a secrets manager, never in source control or on a command line.
- Browsers and LiveKit rooms get short-lived tokens: an [embed token](https://docs.bithuman.ai/api/embedding) or a runtime token minted with [`POST /v1/runtime-tokens/mint`](https://docs.bithuman.ai/platforms/livekit#authenticate).
- If a secret leaks, create a new one and delete the old one in the console.

## What a shipped app holds

The Swift package and the Android SDK authenticate with your API secret, so every copy of an app you distribute carries it. Treat that secret as exposed: whoever extracts it can call the API as your account, spend your credits and create more secrets.

- Fetch the secret from your backend when the app starts. Never compile it into a build you ship.
- Give each app its own secret, so you can rotate one without touching the others ([API secrets](https://www.bithuman.ai/developer/api-keys)).
- Watch your [balance](https://docs.bithuman.ai/api/billing#check-credit-balance), and rotate the secret at once if usage looks wrong.

## Next

- [REST authentication](https://docs.bithuman.ai/api/authentication): the header, validation and error codes.
- [Pick your platform](https://docs.bithuman.ai/start#choose-your-platform).

---

# Performance

URL: https://docs.bithuman.ai/performance

> How fast Essence 2 and Expression 2 render on each platform.

**× real time** is seconds of avatar video rendered per second. At 1.0× or more the avatar keeps up with a live conversation; higher means more headroom.

Every configuration we publish renders faster than real time. The tables below list every published configuration.

| Runs on | Hardware | Essence 2 fps | Essence 2 × real time | Expression 2 fps | Expression 2 × real time |
|---|---|---|---|---|---|
| Cloud API · GPU | NVIDIA RTX 4090 | 104 | **4.1×** real time | 340 | **17.0×** real time |
| Cloud API · Apple silicon | Apple M4 Max | 71 | **2.8×** real time | 111 | **5.5×** real time |
| Cloud API · CPU | x86 server CPU | 28 | **1.1×** real time | 27 | **1.3×** real time |
| macOS · CLI | Apple M4 | 106 | **4.2×** real time | 168 | **8.4×** real time |
| macOS · Python | Apple M4 | 174 | **6.9×** real time | 169 | **8.4×** real time |
| macOS · Swift package | Apple M4 | 120 | **4.8×** real time | 177 | **8.8×** real time |
| Linux · CLI | Intel Core i7-13700F (x86_64) | 50 | **2.0×** real time | 44 | **2.2×** real time |
| Linux · Python | Intel Core i7-13700F (x86_64) | 49 | **1.9×** real time | 47 | **2.3×** real time |
| Windows · Python | Intel Core i7-13700F (x86_64), 8 threads | 30 | **1.2×** real time | 21 | **1.0×** real time |
| iPhone · Swift package | iPhone 15 | 54 | **2.1×** real time | 111 | **5.5×** real time |
| Android | Samsung Galaxy S25+ | 52 | **2.0×** real time | 48 | **2.4×** real time |
| Web browser (WebGPU) | Chrome on Apple M4 | 43 | **1.7×** real time | 39 | **1.9×** real time |

Each figure is one avatar session rendering as fast as the hardware allows.

The sections below go platform by platform, on-device first. [How we measure](https://docs.bithuman.ai/performance/method) has the method, the releases measured, memory, the time to a finished video and the raw data.

## Mobile

First a short burst on each phone, then one session held for 10 minutes.

| Runs on | Hardware | Essence 2 fps | Essence 2 × real time | Expression 2 fps | Expression 2 × real time |
|---|---|---|---|---|---|
| iPhone · Swift package | iPhone 15 | 54 | **2.1×** real time | 111 | **5.5×** real time |
| Android | Samsung Galaxy S25+ | 52 | **2.0×** real time | 48 | **2.4×** real time |

<details class="releases">
<summary>Releases measured</summary>

Measured in September 2026 on Swift package 2.17.3, Swift package 2.18.0, essence2-android 0.7.0 and expression2-android 0.4.10.

</details>

- The first table is one render of a speech clip on a cool phone, as fast as the phone allows.
- Some phone figures use a shorter speech clip than the other platforms; each cell's clip is in [performance.json](https://docs.bithuman.ai/performance.json).
- Only an iPhone 15 and a Samsung Galaxy S25+ are measured. Other phones render at other rates.

Setup for each SDK: [Apple](https://docs.bithuman.ai/platforms/ios), [Android](https://docs.bithuman.ai/platforms/android).

## Held for 10 minutes

| Runs on | Hardware | Essence 2 fps | Essence 2 × real time | Expression 2 fps | Expression 2 × real time |
|---|---|---|---|---|---|
| iPhone · Swift package | iPhone 15 | 33 | **1.3×** real time | 103 | **5.1×** real time |
| Android | Samsung Galaxy S25+ | 37 | **1.4×** real time | 44 | **2.2×** real time |
| Web browser (WebGPU) | Chrome on Apple M4 | 54 | **2.1×** real time | 41 | **2.0×** real time |

One session held open for ten minutes from a cool start on Swift package 2.15.0, essence2-android 0.8.1, expression2-android 0.5.2 and web viewer, rendering as fast as the device allows. Each number is the median 30-second stretch of the slowest of that row's sessions (four on iPhone · Swift package, three on Android, three on Web browser (WebGPU) Essence 2, four on Web browser (WebGPU) Expression 2); the slowest single stretch was lower (iPhone · Swift package Essence 2 31 fps; iPhone · Swift package Expression 2 100 fps; Android Essence 2 32 fps; Android Expression 2 37 fps; Web browser (WebGPU) Essence 2 50 fps; Web browser (WebGPU) Expression 2 41 fps). A phone warms up over a long conversation and slows its processor to stay cool, so a kiosk or any screen that renders all day should plan on this number rather than the short-burst rate.

Memory over the ten minutes (the probe's own reading at the start and the end of the held window): Android Essence 2 memory (PSS) 0.9 GB to 0.9 GB (+0 MB); Android Expression 2 memory (PSS) 0.7 GB to 0.8 GB (+34 MB); Web browser (WebGPU) Essence 2 Chrome tab memory footprint 3.1 GB to 3.0 GB (-55 MB).

The Web browser row is the engine's render throughput with WebGPU in Chrome on an Apple M4, measured in a visible (headed) browser window. It is not the frame rate a visitor sees on the page, where the voice and the display share the browser with the engine.

## Web

These figures are for the avatar rendering in the visitor's own tab (`render=local`). By default the avatar renders on the [cloud API](https://docs.bithuman.ai/performance#cloud) and streams to the page.

| Runs on | Hardware | Essence 2 fps | Essence 2 × real time | Expression 2 fps | Expression 2 × real time |
|---|---|---|---|---|---|
| Web browser (WebGPU) | Chrome on Apple M4 | 43 | **1.7×** real time | 39 | **1.9×** real time |

<details class="releases">
<summary>Releases measured</summary>

Measured in September 2026 on the hosted web viewer.

</details>

- Each figure is the engine's render throughput with WebGPU in Chrome on an Apple M4, measured in an automated browser.
- It is not the frame rate a visitor sees on the page, where the voice and the display share the browser with the engine.
- Only Chrome on an Apple M4 is measured. Other browsers, other GPUs and devices without WebGPU are not.

Setup and the WebGPU check: [Web](https://docs.bithuman.ai/platforms/web).

## Desktop

Pick the row for the product you use: the CLI, Python and the Swift package render at different rates on the same machine.

| Runs on | Hardware | Essence 2 fps | Essence 2 × real time | Expression 2 fps | Expression 2 × real time |
|---|---|---|---|---|---|
| macOS · CLI | Apple M4 | 106 | **4.2×** real time | 168 | **8.4×** real time |
| macOS · Python | Apple M4 | 174 | **6.9×** real time | 169 | **8.4×** real time |
| macOS · Swift package | Apple M4 | 120 | **4.8×** real time | 177 | **8.8×** real time |
| Linux · CLI | Intel Core i7-13700F (x86_64) | 50 | **2.0×** real time | 44 | **2.2×** real time |
| Linux · Python | Intel Core i7-13700F (x86_64) | 49 | **1.9×** real time | 47 | **2.3×** real time |
| Windows · Python | Intel Core i7-13700F (x86_64), 8 threads | 30 | **1.2×** real time | 21 | **1.0×** real time |

<details class="releases">
<summary>Releases measured</summary>

Measured in September 2026 on CLI 2.8.1, bithuman 2.11.12, bithuman 2.11.13, bithuman 2.11.18 and Swift package 2.15.0.

</details>

- Each figure is one render of a reference speech clip, as fast as the machine allows, with nothing else running.
- Only these two machines are measured: an Apple M4 Mac and an Intel Core i7-13700F desktop. Other processors render at other rates.

Memory per render is on [How we measure](https://docs.bithuman.ai/performance/method#memory). Setup for each product: [CLI](https://docs.bithuman.ai/platforms/cli), [Python](https://docs.bithuman.ai/platforms/python), [Apple](https://docs.bithuman.ai/platforms/ios).

## Cloud

bitHuman picks the server for each session, and every server type renders faster than real time. Each row is one server type.

| Runs on | Hardware | Essence 2 fps | Essence 2 × real time | Expression 2 fps | Expression 2 × real time |
|---|---|---|---|---|---|
| Cloud API · GPU | NVIDIA RTX 4090 | 104 | **4.1×** real time | 340 | **17.0×** real time |
| Cloud API · Apple silicon | Apple M4 Max | 71 | **2.8×** real time | 111 | **5.5×** real time |
| Cloud API · CPU | x86 server CPU | 28 | **1.1×** real time | 27 | **1.3×** real time |

<details class="releases">
<summary>Releases measured</summary>

Measured in September 2026 on the cloud API.

</details>

- Each figure is how fast one finished video is delivered, including encoding the video file, on a server with no other sessions.
- With other sessions on the same server, a session can render more slowly than shown.
- A live conversation plays at the model's own rate, 25 fps for Essence 2 and 20 fps for Expression 2. Speed above that makes a video file finish sooner; it does not put more frames on screen.

---

# Python

URL: https://docs.bithuman.ai/platforms/python

> Render Essence 2 and Expression 2 avatars from your own Python code.

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](https://docs.bithuman.ai/platforms/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](https://docs.bithuman.ai/platforms/windows). See [CPU only (no GPU)](https://docs.bithuman.ai/deploy/cpu).

| Detail | Expression 2 | Essence 2 |
|---|---|---|
| **Renders** | [any character from one portrait](https://docs.bithuman.ai/models/expression-2) | [a photoreal person from one portrait](https://docs.bithuman.ai/models/essence-2) |
| **Install** | `pip install "bithuman[expression-2]"` | included in the same install |
| **Frames** | RGB `numpy` arrays, `(height, width, 3)` `uint8` | the same |

| You need | Check |
|---|---|
| Python 3.10–3.14 | `python3 --version` |
| macOS 14+ on Apple silicon, Linux x86_64 or Linux arm64, or [Windows 11 x86_64](https://docs.bithuman.ai/platforms/windows) | `python3 -c "import platform; print(platform.system(), platform.machine())"` |
| An API secret | [Your API secret](https://docs.bithuman.ai/start/api-secret) |
| A paid plan (Creator or higher): usage bills per second while the avatar runs | [Pricing](https://docs.bithuman.ai/pricing) |
| About 1 GB of disk (570 MB package, 118–190 MB per avatar) | `df -h .` |

## Install

```bash
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

```bash
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
```

```python
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=`:

```python
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])`.

<div class="fig-end">

*Capture: The sofia-ramirez avatar speaking in a window opened by the Python SDK on a Mac. Captured on an Apple M4 Mac (macOS) · Python SDK 2.11.6 · sofia-ramirez (Essence 2) · 2026-09-23.* (https://docs.bithuman.ai/examples/python-macos/clip.mp4)

## Performance

| Configuration | Hardware | Essence 2 | Expression 2 |
|---|---|---|---|
| Linux · Python · CPU only (no GPU) | Intel Core i7-13700F (x86_64) | 1.9× real time | 2.3× real time |
| macOS · Python | Apple M4 | 6.9× real time | 8.4× real time |

× real time: seconds of video rendered per second; 1.0× or more holds a live conversation ([method](https://docs.bithuman.ai/performance#desktop)).

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

---

# Windows

URL: https://docs.bithuman.ai/platforms/windows

> Render Essence 2 and Expression 2 on a Windows 11 PC, with no GPU.

The `bithuman` Python package: a file in and frames or an MP4 out, or a live stream in and frames out.

## Before you start

Both models run on the CPU alone, with no GPU and no WSL. The [CLI](https://docs.bithuman.ai/platforms/cli) on Windows runs cloud sessions and MCP.

| Detail | Expression 2 | Essence 2 |
|---|---|---|
| **Renders** | [any character from one portrait](https://docs.bithuman.ai/models/expression-2) | [a photoreal person from one portrait](https://docs.bithuman.ai/models/essence-2) |
| **Install** | `pip install "bithuman[expression-2]"` | included in the same install |
| **Frames** | RGB `numpy` arrays, `(height, width, 3)` `uint8` | the same |

| You need | Check |
|---|---|
| Windows 11 on x86_64 (64-bit Intel or AMD) | `python -c "import platform; print(platform.system(), platform.machine())"` prints `Windows AMD64` |
| 64-bit Python 3.10–3.14, from [python.org](https://www.python.org/downloads/windows/) or `winget install Python.Python.3.12` | `python --version` |
| An API secret | [Your API secret](https://docs.bithuman.ai/start/api-secret) |
| A paid plan (Creator or higher): usage bills per second while the avatar runs | [Pricing](https://docs.bithuman.ai/pricing) |
| About 1 GB of disk (the package, 118–190 MB per avatar) | `Get-PSDrive C` |

The package carries the Microsoft C++ runtime it needs, so there is nothing else to install. It is tested on Windows 11; Windows on Arm has no package yet.

## Install

In PowerShell:

```powershell
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install "bithuman[expression-2]"
```

The package installs no command-line tool.

## Authenticate

Set `BITHUMAN_API_SECRET` in the PowerShell window that runs Python (`bithuman.open` reads it), or pass `api_secret=` to `AsyncBithuman.create()`. See [Your API secret](https://docs.bithuman.ai/start/api-secret). Downloading a sample avatar needs no account.

## Run your first avatar

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

```python
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. Windows' own H.264 encoder writes it, so no `ffmpeg` install is needed. To process the frames yourself, iterate over `render` without `out_mp4=`:

```python
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)
```

## Integrate into your app

The Python API is the same on Windows as on macOS and Linux: `AsyncBithuman` takes audio as it arrives and yields frames and audio at the model's rate, `interrupt()` stops a reply, and the [LiveKit plugin](https://docs.bithuman.ai/platforms/livekit) renders the avatar inside a LiveKit Agents worker. The code and the calls are in [Python: Integrate into your app](https://docs.bithuman.ai/platforms/python/app#integrate-into-your-app).

## Platform notes

- The first Essence 2 render downloads a shared audio encoder (about 66 MB) to `%USERPROFILE%\.bithuman\deps`, once.
- `BITHUMAN_CACHE_DIR` moves the download cache from `%USERPROFILE%\.cache\bithuman`.
- `python -m bithuman render <AGENT_CODE> <audio>` downloads your own agent's model by code and renders it.

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| `Activate.ps1 cannot be loaded because running scripts is disabled` | PowerShell's execution policy | `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`, or run `.venv\Scripts\python.exe` directly |
| `pip` finds no wheel | 32-bit Python, Windows on Arm, or Python outside 3.10–3.14 | install 64-bit Python 3.10–3.14 on an x86_64 PC |
| `'curl' is not recognized` or a PowerShell `Invoke-WebRequest` error | `curl` in Windows PowerShell 5.1 is an alias | type `curl.exe`, as above |
| `NotSupported` opening an Expression 2 file | the extra is missing | `pip install "bithuman[expression-2]"` |
| `NotAuthorised` at `open`: *that key was not accepted (401)* | the secret was rejected | create a new one under [API secrets](https://www.bithuman.ai/developer/api-keys) |

## Reference

- [Python](https://docs.bithuman.ai/platforms/python) and the [Python API reference](https://docs.bithuman.ai/platforms/python/reference): every public class and function.
- [Changelog](https://docs.bithuman.ai/changelog) and [Downloads & versions](https://docs.bithuman.ai/downloads).

---

# Build a Python app

URL: https://docs.bithuman.ai/platforms/python/app

> Stream audio into an avatar from Python and take its frames live.

## Integrate into your app

For a live conversation, `AsyncBithuman` takes audio as it arrives and yields frames and audio at the model's rate:

```python
# excerpt: show() and play() are your own display and audio output
import asyncio, soundfile as sf
from bithuman import AsyncBithuman

async def main():
    avatar = await AsyncBithuman.create(model_path="wise-pup.imx")   # reads BITHUMAN_API_SECRET
    pcm, rate = sf.read("speech.wav", dtype="int16")

    async def speak():
        for i in range(0, len(pcm), rate // 10):                     # 100 ms chunks, as they arrive
            await avatar.push_audio(pcm[i:i + rate // 10].tobytes(), rate, last_chunk=False)
        await avatar.flush()                                          # end of the reply

    task = asyncio.create_task(speak())
    try:
        async for frame in avatar.run():                              # paced at the model's play rate
            if frame.has_image:
                show(frame.bgr_image)                                 # BGR numpy array
            if frame.audio_chunk:
                play(frame.audio_chunk.array)                         # audio in sync with the frame
    finally:
        task.cancel()
        await avatar.shutdown()                                       # frees the model and the credential

asyncio.run(main())
```

| Job | Call |
|---|---|
| Stream audio | `await avatar.push_audio(int16_bytes, sample_rate, last_chunk=False)` |
| End of a reply | `await avatar.flush()` |
| Interrupt the reply | `avatar.interrupt()` |
| Idle between replies | keep reading `run()`: it yields idle frames when there is no speech |
| Stop | `await avatar.shutdown()` in a `finally` (`stop()` keeps the model loaded) |

A voice agent on your own LiveKit server: [Voice agent in Python](https://docs.bithuman.ai/build/voice-agent/python).

## Complete example

The quickstart from the examples repository: open an avatar and watch it speak in a window.

### Requirements

| You need | Notes |
|---|---|
| Python 3.10–3.14 | on macOS (Apple silicon) or Linux (x86_64, arm64) |
| An [API secret](https://docs.bithuman.ai/start/api-secret) | |
| A desktop session | the example opens a window |

### Run it

```bash
git clone https://github.com/bithuman-product/bithuman-examples.git
cd bithuman-examples/python/quickstart
python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt
export BITHUMAN_API_SECRET="<your API secret>"
python local-avatar.py
```

### Expected output

A window titled **bitHuman avatar** opens and the avatar speaks the bundled `speech.wav`. The first run downloads the sample avatar (about 150 MB). To write an MP4 instead of opening a window, run `python -m bithuman render sofia-ramirez speech.wav`: it downloads the `sofia-ramirez` sample and writes `sofia-ramirez.mp4`.

### Make it your own

- **Your own avatar:** pass `--model` with your agent's `.imx`, downloaded with the [Agents API](https://docs.bithuman.ai/api/agents#download-an-agents-model) or `bithuman pull <AGENT_CODE>`.
- **Your own audio:** pass any audio file; or stream microphone audio with `AsyncBithuman` ([Integrate into your app](https://docs.bithuman.ai/platforms/python/app#integrate-into-your-app)).
- **A conversation:** `cloud-avatar.py` in the same folder connects the avatar to an OpenAI voice agent over LiveKit ([LiveKit](https://docs.bithuman.ai/platforms/livekit)).
- **A desktop companion:** `conversation.py` in the same folder talks with you through OpenAI Realtime, with your OpenAI key ([Companion app](https://docs.bithuman.ai/build/companion-app)).
- **A web app:** send the frames from `render()` to your own video stream, or use the [web embed](https://docs.bithuman.ai/platforms/web).

## Platform notes

- The first Essence 2 render downloads a shared audio encoder (about 66 MB) to `~/.bithuman/deps`, once.
- `BITHUMAN_CACHE_DIR` moves the download cache from `~/.cache/bithuman`.
- `python -m bithuman render <AGENT_CODE> <audio>` downloads your own agent's model by code and renders it.
- A process with no API secret, or with a rejected one, refuses at `open` with `NotAuthorised`.

## Reference

- [Python API reference](https://docs.bithuman.ai/platforms/python/reference): every public class and function.
- [Python examples](https://github.com/bithuman-product/bithuman-examples/tree/main/python): quickstart, local conversation, cloud with LiveKit.
- [Changelog](https://docs.bithuman.ai/changelog) and [Downloads & versions](https://docs.bithuman.ai/downloads).

---

# CLI

URL: https://docs.bithuman.ai/platforms/cli

> Render an MP4 or run a live avatar from the terminal, with no code.

One binary, no code: `bithuman run` opens a live conversation with an avatar in your browser.

## Before you start

`bithuman render` turns an audio file into a talking-avatar MP4. Both render on your own machine. To program against the models instead, use [Python](https://docs.bithuman.ai/platforms/python).

> **Note:** On Linux, both models run live on the CPU alone, no GPU. See [CPU only (no GPU)](https://docs.bithuman.ai/deploy/cpu).

| Detail | Expression 2 | Essence 2 |
|---|---|---|
| **Renders** | [any character from one portrait](https://docs.bithuman.ai/models/expression-2) | [a photoreal person from one portrait](https://docs.bithuman.ai/models/essence-2) |
| **`render` and `run`** | both | both |
| **Download per avatar** | about 190 MB | 140–160 MB, plus a shared audio encoder (about 440 MB on Linux) once |

| You need | For | Check |
|---|---|---|
| macOS 14+ on Apple silicon, or Linux on x86_64 or arm64 | the binary | `uname -sm` |
| A bitHuman sign-in or API secret, on the Creator plan or higher (usage bills per second; [pricing](https://docs.bithuman.ai/pricing)) | `run` and `render` (browsing and downloading need none) | `bithuman account` exits 0 |
| `ffmpeg` on `PATH` | `render`, and `run` with an Essence 2 avatar | `ffmpeg -version` |
| `livekit-server` 1.13 or newer for `bithuman run` (the Linux download includes it) | `run` | `livekit-server --version`; update with `brew upgrade livekit` |
| Python 3.11 or newer with `venv` (`python3-venv` on Debian/Ubuntu) | `run` (its voice agent) | `python3 --version` |

## Install

```bash
# macOS (Apple silicon): also installs ffmpeg, livekit-server and Python
brew tap bithuman/bithuman https://gitlab.com/bithuman/sdk/homebrew-bithuman && brew install bithuman/bithuman/bithuman-cli
```

```bash
# 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
```

```powershell
# Windows 10/11 x86_64 (PowerShell): cloud sessions and MCP
irm https://install.bithuman.ai/windows | iex
```

The Linux installer downloads about 190 MB and puts the CLI, its render engines and `livekit-server` (about 350 MB) in `~/.local/bin` (set `BITHUMAN_INSTALL_DIR` to change it). It verifies the checksum. If it asks you to, add `export PATH="$HOME/.local/bin:$PATH"` to your shell profile. On macOS `curl` works too (then `brew install ffmpeg livekit`). `bithuman --version` prints the CLI and engine versions.

Check the install:

```text
$ bithuman --version
libessence 2.11.20 ABI 7
bithuman    2.8.9
build       … x86_64-unknown-linux-gnu/release …
engine      linux 1.0.2 …
```

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

## Authenticate

```bash
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](https://docs.bithuman.ai/start/api-secret)). Listing, downloading and opening avatars need no account.

## Run your first avatar

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

```bash
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:

```bash
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](#before-you-start): `livekit-server` and Python. It starts a local `livekit-server` and the voice agent; the first run installs the agent, about 380 MB on disk, in one to two minutes.

`wise-pup` and `A23WJF0199` are the same avatar, named two ways, and the name decides where it renders: a name (`wise-pup`) or a file renders on this machine, at the lower self-hosted rate; an agent code (`A23WJF0199`) renders in the bitHuman cloud, at the cloud rate ([pricing](https://docs.bithuman.ai/pricing)).

<div class="fig-end">

*Capture: The pip-the-red-panda-barista avatar speaking a line, rendered by bithuman render on a Linux PC with no GPU. Captured on a Linux PC, Intel Core i7-13700F (Ubuntu 24.04) · CLI 2.8.2 (bithuman render) · pip-the-red-panda-barista (Expression 2) · 2026-09-27. Rendered on the CPU alone: the PC's graphics card was hidden from the process.* (https://docs.bithuman.ai/examples/cli-linux/clip.mp4)

### Make it your own

- **Your own avatar:** create one with the [Agents API](https://docs.bithuman.ai/api/agents) (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: a recording, or a WAV or MP3 from any text-to-speech tool you use.
- **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](https://docs.bithuman.ai/platforms/cli/reference#json-output)).
- **A conversation instead of a clip:** `bithuman run wise-pup` — [Talk to an avatar on your machine](https://docs.bithuman.ai/build/voice-agent).

## Performance

| Configuration | Hardware | Essence 2 | Expression 2 |
|---|---|---|---|
| Linux · CLI · CPU only (no GPU) | Intel Core i7-13700F (x86_64) | 2.0× real time | 2.2× real time |
| macOS · CLI | Apple M4 | 4.2× real time | 8.4× real time |

× real time: seconds of video rendered per second; 1.0× or more holds a live conversation ([method](https://docs.bithuman.ai/performance#desktop)).

---

# Serve and script the CLI

URL: https://docs.bithuman.ai/platforms/cli/voice

> 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](#voice-settings)) |
| Run the brain on your own hardware | [local conversation brain](https://docs.bithuman.ai/platforms/cli/local-brain) |
| Drive it from an AI agent | `bithuman mcp` ([MCP server](https://docs.bithuman.ai/build/mcp)) |
| Script it | add `--json`: every failure prints one JSON object with a stable code, and the exit code is the contract ([reference](https://docs.bithuman.ai/platforms/cli/reference#exit-codes)) |

### Voice settings

`bithuman run` starts a voice agent on OpenAI Realtime ([the whole setup, and the same conversation in Python](https://docs.bithuman.ai/build/voice-agent)). 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](https://docs.bithuman.ai/pricing)). |
| `BITHUMAN_INSTRUCTIONS` | a short assistant prompt | The agent's system prompt |

## Platform notes

- Essence 1 avatars work with `run` only; for a file use [Python](https://docs.bithuman.ai/platforms/python) or the [video API](https://docs.bithuman.ai/api/video). Expression 1 runs on the [cloud API](https://docs.bithuman.ai/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](https://docs.bithuman.ai/downloads)) the CLI renders in the cloud; to render on the PC, use [Python on Windows](https://docs.bithuman.ai/platforms/windows).

## Reference

- [CLI reference](https://docs.bithuman.ai/platforms/cli/reference): every command, flag, exit code and environment variable.
- [Local conversation brain](https://docs.bithuman.ai/platforms/cli/local-brain): run the conversation fully on your hardware.
- [CLI example scripts](https://github.com/bithuman-product/bithuman-examples/tree/main/api/cli): live stream, offline render, REST.
- [Changelog](https://docs.bithuman.ai/changelog) and [Downloads & versions](https://docs.bithuman.ai/downloads).

---

# LiveKit

URL: https://docs.bithuman.ai/platforms/livekit

> Give a LiveKit voice agent a face with the bitHuman Python plugin.

To add a talking avatar to a LiveKit voice agent, install the `livekit-plugins-bithuman` Python plugin and start a `bithuman.AvatarSession` beside your agent's session. Pass `avatar_id=` to render the avatar in the bitHuman cloud, or `model_path=` to render it inside your worker; either way the avatar speaks the agent's replies with its lips in sync.

`livekit-plugins-bithuman` works on LiveKit Cloud or your own LiveKit server; the avatar joins the room as a participant.

## Before you start

It is a Python plugin; there is no Node.js plugin. The avatar renders in one of two ways:

| | A bitHuman cloud avatar | The avatar on your server |
|---|---|---|
| **You pass** | `avatar_id=` (an agent code) | `model_path=` (an avatar file) |
| **The avatar renders** | in the bitHuman cloud, in the US | inside your worker's process |
| **Its audio and video** | are published into your room by bitHuman | stay on your machine until your worker publishes them |
| **Price** | the cloud rate ([pricing](https://docs.bithuman.ai/pricing)) | the self-hosted rate |
| **Guide** | this page | [Voice agent](https://docs.bithuman.ai/build/voice-agent/python#with-python) |

Either way, the plugin serves the agent's own model, Essence 2 or Expression 2.

- Python 3.10–3.14 and a LiveKit project (its URL and credentials).
- A bitHuman [agent code](https://docs.bithuman.ai/models/how-it-works#key-terms): `A23WJF0199` (the `wise-pup` sample avatar) or your own ([create your own avatar](https://docs.bithuman.ai/build/create-avatar)).
- An [API secret](https://docs.bithuman.ai/start/api-secret), and an OpenAI key for the voice model in the example.

## Install

```bash
pip install "livekit-agents[openai,silero]" livekit-plugins-bithuman python-dotenv
```

To render the avatar inside your worker with `model_path=`, also install `"bithuman[expression-2]"`.

## Authenticate

In a LiveKit worker, name the secret `BITHUMAN_MASTER_SECRET` and pass a minted token. `BITHUMAN_MASTER_SECRET` is your API secret under another name, so the plugin never finds it and copies it into the room.

For a cloud avatar, the worker mints a one-hour token that can start only this agent's avatar in this room (`POST /v1/runtime-tokens/mint` with `"scope": "livekit-cloud"`), as in the worker below. Pass the minted token as `api_secret=`: for a cloud avatar the plugin requires `api_secret` (`api_token=` is not used for cloud avatars).

> **Warning:** Without `api_secret=`, the plugin reads `BITHUMAN_API_SECRET` from the environment and copies it into the avatar's participant attributes, which everyone in the room can read. Keep `BITHUMAN_API_SECRET` unset in the worker.

```bash
export BITHUMAN_MASTER_SECRET="<your API secret>"
export BITHUMAN_AGENT_ID=A23WJF0199
export LIVEKIT_URL=wss://your-project.livekit.cloud
export LIVEKIT_API_KEY=… LIVEKIT_API_SECRET=…
export OPENAI_API_KEY=…
```

*Diagram: LiveKit: the secret stays on your server.* Your LiveKit agent worker holds the API secret as BITHUMAN_MASTER_SECRET and mints a one-hour runtime token for each session. The bitHuman cloud avatar joins your room with that token and publishes its video and voice. Your app joins the room with a room token from your server and never holds a bitHuman secret.

## Run your first avatar

A complete worker (`agent.py`):

```python
import os

import aiohttp
from dotenv import load_dotenv
from livekit.agents import Agent, AgentSession, JobContext, WorkerOptions, cli
from livekit.agents.voice.room_io import RoomOptions
from livekit.plugins import bithuman, openai, silero
from openai.types.realtime.realtime_audio_input_turn_detection import ServerVad

load_dotenv()

async def livekit_cloud_token(agent_code: str, room_name: str) -> str:
    """A one-hour token that can only start this agent's avatar in this room."""
    async with aiohttp.ClientSession() as http:
        async with http.post(
            "https://api.bithuman.ai/v1/runtime-tokens/mint",
            headers={"api-secret": os.environ["BITHUMAN_MASTER_SECRET"]},
            json={"agent_code": agent_code, "scope": "livekit-cloud",
                  "room_name": room_name, "livekit_url": os.environ["LIVEKIT_URL"]},
        ) as resp:
            resp.raise_for_status()
            return (await resp.json())["scoped_token"]

async def entrypoint(ctx: JobContext):
    await ctx.connect()
    await ctx.wait_for_participant()
    agent_code = os.environ["BITHUMAN_AGENT_ID"]

    session = AgentSession(
        llm=openai.realtime.RealtimeModel(
            voice="coral",
            # end the user's turn after 0.5 s of silence (the default waits longer)
            turn_detection=ServerVad(type="server_vad", silence_duration_ms=500, create_response=True, interrupt_response=True),
        ),
        vad=silero.VAD.load(),
    )
    avatar = bithuman.AvatarSession(
        avatar_id=agent_code,
        api_secret=await livekit_cloud_token(agent_code, ctx.room.name),
    )
    await avatar.start(session, room=ctx.room)
    await session.start(
        agent=Agent(instructions="You are a friendly assistant. Keep answers short."),
        room=ctx.room,
        room_options=RoomOptions(audio_output=False),   # the avatar publishes the audio
    )

if __name__ == "__main__":
    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))
```

```bash
python agent.py dev
# → join the room from the LiveKit Agents Playground (agents-playground.livekit.io); the avatar appears and answers
```

## Performance

A cloud avatar renders in the bitHuman cloud; with `model_path=` the avatar renders where your worker runs, as Python does:

| Configuration | Hardware | Essence 2 | Expression 2 |
|---|---|---|---|
| Cloud API · GPU | NVIDIA RTX 4090 | 4.1× real time | 17.0× real time |
| Linux · Python · CPU only (no GPU) | Intel Core i7-13700F (x86_64) | 1.9× real time | 2.3× real time |
| macOS · Python | Apple M4 | 6.9× real time | 8.4× real time |

× real time: seconds of video rendered per second; 1.0× or more holds a live conversation ([method](https://docs.bithuman.ai/performance#cloud)).

---

# Build a LiveKit agent

URL: https://docs.bithuman.ai/platforms/livekit/app

> Fit the LiveKit plugin into your own client, room and server.

## Integrate into your app

- **Your own client.** The avatar is a normal LiveKit participant: any LiveKit client SDK (JavaScript, Swift, Kotlin) subscribes to its video and audio tracks. The app takes a room token from your server, never a bitHuman secret.
- **Choosing a model.** The plugin serves the agent's own model. Do not pass `model=`; create the agent with the model you want ([Models](https://docs.bithuman.ai/models)).
- **A photo instead of an agent.** `avatar_image=` with no `avatar_id` animates the photo on Expression 1 only. On every other model the launch is refused with `400 VALIDATION_ERROR` before anything is billed: [create an agent](https://docs.bithuman.ai/api/agents#generate-an-agent) from the photo and pass its code as `avatar_id`.
- **Rendering on your own machine.** Pass `model_path=` (an avatar file) instead of `avatar_id=`, and the secret explicitly: `api_secret=os.environ["BITHUMAN_MASTER_SECRET"]`. The avatar renders inside the worker's process, and the secret stays in that process. Runnable example: [Voice agent](https://docs.bithuman.ai/build/voice-agent/python#with-python).
- **Without the plugin.** If your voice pipeline is not a LiveKit Agents worker, start the avatar with one REST call and stream it your audio: [Cloud avatar without the plugin](https://docs.bithuman.ai/platforms/livekit/cloud-avatar).
- **Several agents in one room.** The avatar lip-syncs the agent that calls `AvatarSession.start()` and ignores other agents' audio.
- **Gestures.** Trigger avatar actions from your agent: [Gestures](https://docs.bithuman.ai/build/gestures).

The [cloud example](https://github.com/bithuman-product/bithuman-examples/tree/main/python/cloud-essence) packages this worker with a web UI and Docker Compose.

## Platform notes

- The mint call is one per session. The token starts that session only; it expires after an hour, and a session that runs longer continues.
- `livekit_url` in the mint call must be the URL the plugin connects to (`LIVEKIT_URL`, unless you pass `livekit_url=` to `AvatarSession.start()`).
- If you run your own LiveKit server for your own worker, use `livekit-server` 1.9.12 or newer (`bithuman run` needs 1.13 or newer). With older servers, browsers leave and rejoin the room every 15 s, and the video stalls each time.

## Reference

- [Runtime tokens](https://docs.bithuman.ai/api/reference): `POST /v1/runtime-tokens/mint`.
- [LiveKit Agents docs](https://docs.livekit.io/agents/).
- [Python](https://docs.bithuman.ai/platforms/python): the runtime the plugin builds on.

---

# Pipecat

URL: https://docs.bithuman.ai/platforms/pipecat

> Give a Pipecat voice bot a lip-synced avatar with pipecat-bithuman.

Put `BitHumanVideoService` after your TTS service: the bot's speech goes in, and lip-synced avatar video with the matching audio comes out.

## Before you start

`pipecat-bithuman` is a community integration for Pipecat, maintained by bitHuman, not by the Pipecat team. The avatar renders inside your bot's own process through the [Python SDK](https://docs.bithuman.ai/platforms/python), on your own machine. Your pipeline keeps its own speech-to-text, LLM and TTS services.

| Detail | Expression 2 | Essence 2 |
|---|---|---|
| **Renders** | [any character from one portrait](https://docs.bithuman.ai/models/expression-2) | [a photoreal person from one portrait](https://docs.bithuman.ai/models/essence-2) |
| **Install** | `pip install "pipecat-bithuman[expression-2]"` | included in the same install |
| **Avatar file** | an Expression 2 `.imx` | an Essence 2 `.imx` |

| You need | Check |
|---|---|
| Python 3.11–3.14 | `python3 --version` |
| macOS 14+ on Apple silicon, or Linux x86_64 or arm64 (a PC with no GPU renders both models) | `python3 -c "import platform; print(platform.system(), platform.machine())"` |
| An API secret | [Your API secret](https://docs.bithuman.ai/start/api-secret) |
| A paid plan (Creator or higher): usage bills per second while the avatar runs | [Pricing](https://docs.bithuman.ai/pricing) |
| `ffmpeg` and `git`, for the demo below | `ffmpeg -version`, `git --version` |

## Install

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

The package brings Pipecat (`pipecat-ai` 1.12.0 or newer) and the bitHuman Python SDK (`bithuman`) with it.

## Authenticate

Set `BITHUMAN_API_SECRET` in the shell that runs the bot, or pass `api_secret=` to `BitHumanVideoService`. The service never logs the secret and removes it from error text. Name the avatar file with `model_path=`, or set `BITHUMAN_MODEL_PATH`.

The avatar opens on `StartFrame` and closes on `EndFrame`, `CancelFrame` or cleanup.

## Run your first avatar

The package's demo script sends a WAV file through a Pipecat pipeline as `TTSAudioRawFrame` chunks, as a TTS service would, and writes the avatar frames that come out to an MP4. In the virtual environment from Install:

```bash
export BITHUMAN_API_SECRET="<your API secret>"
git clone https://github.com/bithuman-product/pipecat-bithuman
cd pipecat-bithuman
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
BITHUMAN_MODEL_PATH=wise-pup.imx python examples/render_demo.py speech.wav demo.mp4
# → prints the frame count and size, and demo.mp4 shows wise-pup speaking the sample
```

To see barge-in, add `--interrupt-at 10 --repeat 2`: the reply is interrupted after 10 s, and a new one follows. The [37-second demo](https://github.com/bithuman-product/pipecat-bithuman/blob/main/docs/demo.mp4) in the repository is that run with `wise-pup`.

## Performance

The avatar renders through the Python SDK inside your bot's process. The Python SDK's speed on each machine:

| Configuration | Hardware | Essence 2 | Expression 2 |
|---|---|---|---|
| Linux · Python · CPU only (no GPU) | Intel Core i7-13700F (x86_64) | 1.9× real time | 2.3× real time |
| macOS · Python | Apple M4 | 6.9× real time | 8.4× real time |

× real time: seconds of video rendered per second; 1.0× or more holds a live conversation ([method](https://docs.bithuman.ai/performance#desktop)).

---

# Build a Pipecat bot

URL: https://docs.bithuman.ai/platforms/pipecat/app

> Fit BitHumanVideoService into your Pipecat pipeline, transport and error handling.

## Integrate into your app

- **Where it goes.** After the TTS service, or a speech-to-speech LLM, and before `transport.output()`.
- **The transport.** Turn on video out with `video_out_enabled=True`. The service logs the avatar's frame size on the first frame; set `video_out_width` and `video_out_height` to it to avoid resizing.
- **Voice and picture together.** The service does not forward your TTS audio. It pushes the avatar's copy of the speech, paired with each picture. Each image carries `sync_with_audio`, so keep the transport's `video_out_is_live` off (its default).
- **Barge-in.** On `InterruptionFrame` the avatar drops the reply in flight and goes back to idle. See [Barge-in](https://docs.bithuman.ai/build/barge-in).
- **The end of a reply.** `TTSStoppedFrame` is held until the avatar has finished speaking the reply.
- **Session time.** The avatar opens on `StartFrame` and closes on `EndFrame`, `CancelFrame` or cleanup; it is billed while open, talking or idle. End the pipeline when the user leaves, as the example below does.
- **When the avatar fails.** The service pushes one `ErrorFrame` upstream and, by default, passes TTS audio through unchanged, so the bot keeps talking without video. `audio_passthrough_on_error=False` drops the audio instead.
- **Metrics.** With `enable_metrics=True` in `PipelineParams`, the service reports TTFB: from a reply's first audio in to its first voiced avatar frame out.

### What the service does with frames

| In | Out |
|---|---|
| `TTSAudioRawFrame` | sent to the avatar, not forwarded as is |
| (avatar frame) | `OutputImageRawFrame` (RGB), while talking and while idle |
| (avatar audio) | `TTSAudioRawFrame` (16 kHz mono), paired with each picture |
| `TTSStoppedFrame` | held until the avatar has finished speaking the reply |
| `InterruptionFrame` | the avatar drops the reply in flight and goes back to idle |
| anything else | passed on unchanged |

## Complete example

`examples/bot.py` in [pipecat-bithuman](https://github.com/bithuman-product/pipecat-bithuman) is a complete voice bot in a Daily room, with Deepgram speech-to-text, an OpenAI LLM and Cartesia TTS. The avatar sits between the TTS and the output transport:

```python
# excerpt: the transport and the pipeline, from pipecat-bithuman's examples/bot.py
transport = DailyTransport(
    os.environ["DAILY_ROOM_URL"],
    None,
    "Pip",
    DailyParams(
        audio_in_enabled=True,
        audio_out_enabled=True,
        video_out_enabled=True,
        video_out_width=416,   # the wise-pup sample's frame size; the service logs yours
        video_out_height=720,
    ),
)
# …
avatar = BitHumanVideoService()  # BITHUMAN_MODEL_PATH + BITHUMAN_API_SECRET
# …
pipeline = Pipeline(
    [
        transport.input(),
        stt,
        aggregators.user(),
        llm,
        tts,
        avatar,
        transport.output(),
        aggregators.assistant(),
    ]
)
# …
@transport.event_handler("on_participant_left")
async def on_left(transport, participant, reason):
    await worker.cancel()  # close the avatar: session time stops
```

Run it from the repository, with the avatar file from [Pipecat](https://docs.bithuman.ai/platforms/pipecat#run-your-first-avatar). `examples/bot.py` sets the transport to the `wise-pup` frame size, 416×720; for another avatar, use the size the service logs on the first frame:

```bash
pip install "pipecat-bithuman[expression-2]" "pipecat-ai[daily,deepgram,openai,cartesia,silero]"
export BITHUMAN_API_SECRET="<your API secret>" BITHUMAN_MODEL_PATH=wise-pup.imx
export DAILY_ROOM_URL=… DEEPGRAM_API_KEY=… OPENAI_API_KEY=… CARTESIA_API_KEY=… CARTESIA_VOICE_ID=…
python examples/bot.py
# → join the Daily room; the avatar says hello first, then answers
```

## Platform notes

- Requires Python 3.11–3.14 and `pipecat-ai` 1.12.0 or newer.
- Your own avatar: [download an agent's model](https://docs.bithuman.ai/api/agents#download-an-agents-model) and pass the `.imx` file as `model_path=`.
- The service has no settings to change at runtime. The avatar is chosen when the service is built.
- For tests, or to wrap the SDK, pass `runtime_factory=`: an async callable that returns an object implementing `BitHumanRuntime`. The package's own tests run on fakes, with no network, secret or model file.
- Report bugs in the [pipecat-bithuman issues](https://github.com/bithuman-product/pipecat-bithuman/issues). The Pipecat team does not maintain this package.

## Reference

### `BitHumanVideoService` options

| Argument | Default | Meaning |
|---|---|---|
| `model_path` | `BITHUMAN_MODEL_PATH` | the `.imx` avatar file |
| `api_secret` | `BITHUMAN_API_SECRET` | the API secret, read by the SDK when not passed |
| `sync_video_to_audio` | `True` | sets `sync_with_audio` on each image |
| `audio_passthrough_on_error` | `True` | keep the voice if the avatar fails |
| `stop_frame_timeout_s` | `2.0` | release a held `TTSStoppedFrame` after this much quiet |
| `end_drain_timeout_s` | `30.0` | the longest wait on `EndFrame` for queued speech |
| `runtime_factory` | the SDK | advanced: your own `BitHumanRuntime` |

Properties: `is_avatar_ready` (the avatar is open and rendering) and `frame_size` (`(width, height)` of the first frame, or `None` before it).

### How it maps to the Python SDK

| Pipecat | `bithuman.AsyncBithuman` |
|---|---|
| `StartFrame` | `AsyncBithuman.create(model_path=..., api_secret=...)`, then `run()` |
| `TTSAudioRawFrame` | `push_audio(pcm, sample_rate, last_chunk=False)` |
| `TTSStoppedFrame` | `flush()` |
| `InterruptionFrame` | `interrupt()` |
| `EndFrame`, `CancelFrame`, cleanup | `shutdown()` |

The SDK side of each call: [Python reference](https://docs.bithuman.ai/platforms/python/reference).

---

# REST API

URL: https://docs.bithuman.ai/platforms/rest

> Call bitHuman from any backend over HTTPS with your API secret.

The REST API creates agents, drives live sessions and renders talking videos from your audio, from any language.

## Before you start

- An [API secret](https://docs.bithuman.ai/start/api-secret). API use needs the Creator plan or higher.
- `curl`, or any HTTP client.
- Credits for anything beyond a check: a talking video bills per minute of output ([pricing](https://docs.bithuman.ai/pricing#talking-video--per-minute-of-output)).
- Time: creating an agent of your own takes about 2 hours (Essence 2 or Expression 2). Start with a sample agent meanwhile.

Start with a sample agent: any API secret can read the public samples, such as `A23WJF0199` (`wise-pup`), and render them speaking your audio, [`GET /v1/models/showcase`](https://api.bithuman.ai/v1/models/showcase) lists them; each one's `supported_models` says which `model` to pass. Then create an agent of your own.

To try an avatar with no account first, use the [web embed](https://docs.bithuman.ai/platforms/web).

## Authenticate

Send your API secret in the `api-secret` header on every call. `POST /v1/validate` checks it and spends nothing; it always returns `200`, so read `valid`. The full rules are on [Authentication](https://docs.bithuman.ai/api/authentication).

## Run your first avatar

Render the `wise-pup` sample speaking a 5-second hosted clip (16 kHz mono WAV):

```bash
export BITHUMAN_API_SECRET="<your API secret>"
curl -s -X POST https://api.bithuman.ai/v1/validate -H "api-secret: $BITHUMAN_API_SECRET"
# → {"valid":true}
curl -s -X POST https://api.bithuman.ai/v1/video/generate \
  -H "api-secret: $BITHUMAN_API_SECRET" -H "Content-Type: application/json" \
  -d '{"model": "expression-2", "agent_code": "A23WJF0199", "input": {"type": "audio", "audio_url": "https://docs.bithuman.ai/samples/speech-16k-short.wav"}}'
# → {"success": true, "job_id": "vid_…", "status": "processing"}
curl -s https://api.bithuman.ai/v1/video/vid_… -H "api-secret: $BITHUMAN_API_SECRET"
# → … "status": "completed", "video_url": "https://…mp4"
```

Poll until `status` is `completed`, then open `video_url`. The video costs 4 credits, billed to you; the sample's owner pays nothing. bitHuman renders the audio you bring: a recording, or a WAV or MP3 from any text-to-speech tool, at a public URL. On a sample, only audio input and the models in its `supported_models` work, and `/speak` is the owner's alone. Get an API secret under [Developer → API Secrets](https://www.bithuman.ai/developer/api-keys).

## Complete example

Then make an agent of your own. Four shell scripts from the examples repository: check your secret, check your balance, create an agent from a prompt, then talk to it in the browser.

### Get the code

```bash
git clone https://github.com/bithuman-product/bithuman-examples.git
cd bithuman-examples/api/rest-api/curl
```

### Run it

```bash
./validate.sh && ./check-credits.sh
BITHUMAN_MODEL=expression-2 ./generate-agent.sh "You are a friendly fitness coach."
```

`validate.sh` and `check-credits.sh` spend nothing. `generate-agent.sh` spends one creation charge ([pricing](https://docs.bithuman.ai/pricing#creation--one-time-credits)), then polls until the agent is ready (about 2 to 2.5 hours for a second-generation model; a failed creation is refunded).

### Expected output

```text
{
    "valid": true
}
Checking credit balance...
Balance:        … credits
…
{"success": true, "agent_id": "<agent_id>", "status": "processing"}
  Status: processing  Progress: 10%
…
Agent is ready!
```

Open `https://www.bithuman.ai/embed/<agent_id>` and talk to your agent. While that page is open, `./speak.sh <agent_id> "Hello!"` makes it say a line.

### How it works

| Script | Endpoint |
|---|---|
| `validate.sh` | [`POST /v1/validate`](https://docs.bithuman.ai/api/authentication#post-v1validate): always `200`; read `valid` |
| `check-credits.sh` | [`GET /v2/credit-summaries`](https://docs.bithuman.ai/api/billing): balance and plan |
| `generate-agent.sh` | [`POST /v1/agent/generate`](https://docs.bithuman.ai/api/agents#generate-an-agent), then [`GET /v1/agent/status/{id}`](https://docs.bithuman.ai/api/agents#poll-status) until `ready` or `failed` |
| `speak.sh` | [`POST /v1/agent/{code}/speak`](https://docs.bithuman.ai/api/agents): needs a live session |

### Make it your own

- **A face of your own:** add `"image": "https://…/portrait.jpg"` to the JSON in `generate-agent.sh`.
- **A photoreal person:** `BITHUMAN_MODEL=essence-2`, or `auto` to let the platform choose. Every model except Expression 2 needs a real human face ([Choosing a model](https://docs.bithuman.ai/models#choosing-a-model)).
- **A video instead of a live session:** [`POST /v1/video/generate`](https://docs.bithuman.ai/api/video) renders your agent speaking your audio to an MP4.
- **Other languages:** [`api/rest-api/python`](https://github.com/bithuman-product/bithuman-examples/tree/main/api/rest-api/python) has the same calls in Python.

## Integrate into your app

### Create your own agent

Creation is a one-time charge ([pricing](https://docs.bithuman.ai/pricing#creation--one-time-credits)); a balance below the creation cost returns `402`. Your first own agent takes about 2–2.5 hours for `essence-2` or `expression-2`, or minutes for `expression-1` with a real person's portrait. Always send `model`: `essence-2` for a real person, `expression-2` for any character ([Choosing a model](https://docs.bithuman.ai/models#choosing-a-model)).

```bash
curl -s -X POST https://api.bithuman.ai/v1/agent/generate \
  -H "api-secret: $BITHUMAN_API_SECRET" -H "Content-Type: application/json" \
  -d '{"model": "expression-2", "prompt": "You are a friendly fitness coach.", "image": "https://your-site.example/portrait.jpg"}'
# → {"success": true, "agent_id": "A80HVD8577", "status": "processing"}
```

Poll until `status` is `ready` or `failed`:

```bash
curl -s https://api.bithuman.ai/v1/agent/status/A80HVD8577 -H "api-secret: $BITHUMAN_API_SECRET"
# → {"success": true, "data": {"status": "ready", "progress": 1.0, …}}
```

### Make it speak in a live session

Open `https://www.bithuman.ai/embed/<your agent code>`, then push text from your backend:

```bash
curl -s -X POST https://api.bithuman.ai/v1/agent/A80HVD8577/speak \
  -H "api-secret: $BITHUMAN_API_SECRET" -H "Content-Type: application/json" \
  -d '{"message": "Hello! Great to meet you."}'
# → {"agent_code": "A80HVD8577", "delivered_to_rooms": 1, …}
```

`404` means the agent is not yours, or it has no live session (the message says which).

To show a sample agent with no account, embed it:

```html
<iframe src="https://www.bithuman.ai/embed/A23WJF0199" allow="microphone *" style="width:100%;height:600px;border:0"></iframe>
```

Open the page and talk to it. Keep the `*` in `allow`, or the microphone is blocked. For your own site in production, mint an [embed token](https://docs.bithuman.ai/api/embedding).

### Render a talking video

```bash
curl -s -X POST https://api.bithuman.ai/v1/video/generate \
  -H "api-secret: $BITHUMAN_API_SECRET" -H "Content-Type: application/json" \
  -d '{"agent_code": "A80HVD8577", "model": "expression-2", "input": {"type": "audio", "audio_url": "https://docs.bithuman.ai/samples/speech-16k-short.wav"}}'
```

Poll `GET /v1/video/{job_id}` until `status` is `completed`, then download `video_url` ([Talking video](https://docs.bithuman.ai/api/video)).

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| `402 INSUFFICIENT_BALANCE` | the balance is below the creation cost | [top up](https://www.bithuman.ai/billing#credits) |
| `validate.sh` prints `"valid": false` | the secret is wrong or revoked | create a new one |
| The status stays at `lip_sync` for a long time | that is the training step (about 2 hours) | keep polling |
| `422 MODEL_SUBJECT_MISMATCH` | the model needs a real human face; the image or prompt is a character, or has no face | use `expression-2`, or `auto`; nothing was charged |
| `404` for `A23WJF0199` on `/speak`, an update or a delete | on a sample, only reads and audio-input talking video are open to you | create an agent of your own |
| `400 VALIDATION_ERROR` *renders from audio only* on a sample | samples render your audio, not text | send `"input": {"type": "audio", "audio_url": "…"}` |
| `409 MODEL_NOT_GENERATED` on a sample | the `model` is not in the sample's `supported_models` | pass a model it lists (`wise-pup`: `expression-2`) |
| `404` from `speak.sh` or `/v1/agent/{code}/speak` | the agent is not yours, or it has no live session | the message says which; open its embed page first |

All error codes: [Errors](https://docs.bithuman.ai/api/errors).

## Reference

- [API reference](https://docs.bithuman.ai/api/reference): every endpoint, generated from the OpenAPI spec.
- [Agents](https://docs.bithuman.ai/api/agents) · [Talking video API](https://docs.bithuman.ai/api/video) · [Embedding](https://docs.bithuman.ai/api/embedding) · [Errors](https://docs.bithuman.ai/api/errors)

---

# Cloud avatar in your room

URL: https://docs.bithuman.ai/platforms/livekit/cloud-avatar

> Start a bitHuman cloud avatar in your own LiveKit room with one REST call.

## Overview

A cloud avatar is a participant in your LiveKit room. It lip-syncs the audio you send it, and it publishes the video and that audio as its own tracks. The [LiveKit plugin](https://docs.bithuman.ai/platforms/livekit) does all of this for a Python LiveKit Agents worker. Use this page when your voice pipeline is something else. You will:

1. Mint a LiveKit join token for the avatar.
2. Start the session with `POST /v1/runtime-tokens/request`. The avatar then joins your room.
3. Send each reply's audio to the avatar as a LiveKit byte stream.

Your clients subscribe to the avatar like any other participant. Call the endpoint from your server, because it takes your API secret.

## Mint the avatar's join token

Mint the token with your LiveKit credentials, not with a bitHuman credential. It needs:

- **Identity:** `bithuman-avatar-agent`.
- **Kind:** `agent`.
- **Grant:** permission to join the room.
- **Attribute `lk.publish_on_behalf`:** the identity of the participant that sends the audio. The avatar takes audio only from that participant. If you leave this attribute out, the avatar takes audio from the first agent participant in the room.

```python
from livekit import api

avatar_token = (
    api.AccessToken(LIVEKIT_API_KEY, LIVEKIT_API_SECRET)
    .with_identity("bithuman-avatar-agent")
    .with_kind("agent")
    .with_grants(api.VideoGrants(room_join=True, room=room_name))
    .with_attributes({"lk.publish_on_behalf": sender_identity})
    .to_jwt()
)
```

Don't put a bitHuman secret in the token or in its attributes. Everyone in the room can read attributes.

Join your sender to the room as an agent participant too (kind `agent`). The avatar treats standard participants as users, and it stays in the room while any user is there.

## Start the session

`POST https://api.bithuman.ai/v1/runtime-tokens/request` with the `api-secret` header:

```bash
curl -X POST https://api.bithuman.ai/v1/runtime-tokens/request \
  -H "api-secret: $BITHUMAN_API_SECRET" \
  -H "content-type: application/json" \
  -d '{
    "mode": "gpu",
    "model": "essence-2",
    "agent_id": "<your agent code>",
    "livekit_url": "wss://your-project.livekit.cloud",
    "livekit_token": "<the avatar join token>",
    "room_name": "your-room"
  }'
# → {"avatar_session_started": true, "model": "essence-2", ...}
```

| Field | Required | What it is |
|---|---|---|
| `mode` | yes | `"gpu"`. This field is what makes the call start an avatar; without it, the endpoint only issues a runtime token. The older value `"cpu"` also works but requires `agent_id`. |
| `model` | recommended | `essence-1`, `essence-2`, `expression-1` or `expression-2`. If you leave it out, the server picks the model from `mode` and the agent's models, so check `model` in the response. |
| `agent_id` | yes, unless `image` is sent | The agent code. |
| `image` | for photo sessions | A portrait, for Expression 1 only. See [A photo instead of an agent](#a-photo-instead-of-an-agent). |
| `livekit_url` | yes | Your LiveKit server URL. |
| `livekit_token` | yes | The avatar's join token from the step above. |
| `room_name` | yes | The room the avatar joins. |

A `200` response means the session is starting. `avatar_session_started` is `true`, and `model` is the model the session launched as. `session_id` is the session's handle: [end it or read it](https://docs.bithuman.ai/api/runtime-sessions#end-a-cloud-avatar-session) by that id. The response also echoes `mode`, `agent_id` and `image`, and includes your `user_id`.

The session is billed at the model's cloud rate for as long as it runs ([Pricing](https://docs.bithuman.ai/pricing)). It ends in any of these cases:

- The last user leaves the room.
- You remove `bithuman-avatar-agent` from the room.
- The room closes.

An ended session stops counting toward your plan's [concurrent sessions](https://docs.bithuman.ai/api/rate-limits#session-concurrency) at once. To end a session yourself, [end it by its `session_id`](https://docs.bithuman.ai/api/runtime-sessions#end-a-cloud-avatar-session): billing stops and its slot frees at once. An Expression 1 avatar ended this way leaves your room within about a minute, unless you delete the room.

## Send the audio

Send each reply as one LiveKit byte stream:

- **Topic:** `lk.audio_stream`.
- **Destination identity:** `bithuman-avatar-agent`.
- **Attributes:** `sample_rate` and `num_channels`, as strings.
- **Payload:** raw 16-bit little-endian PCM.

Closing the stream marks the end of the reply. Mono 16 kHz is the native format. Other sample rates are resampled, and stereo is mixed down to mono.

```python
writer = await room.local_participant.stream_bytes(
    name="reply-1",
    topic="lk.audio_stream",
    destination_identities=["bithuman-avatar-agent"],
    attributes={"sample_rate": "16000", "num_channels": "1"},
)
async for pcm in tts_audio():      # 16-bit mono PCM chunks, as the TTS produces them
    await writer.write(pcm)
await writer.aclose()              # end of this reply
```

- **First reply:** wait until `bithuman-avatar-agent` has joined before you send it. Audio sent before the avatar joins is dropped.
- **Interrupting:** perform the RPC `lk.clear_buffer` on `bithuman-avatar-agent`, then close the stream.
- **Playback events (optional):** the avatar calls the RPCs `lk.playback_started` and `lk.playback_finished` on your sender. Register handlers for them if you want to know when it speaks. If you don't register them, the avatar skips these calls.

## Keep latency low

- **Write each TTS chunk as soon as it exists.** Open the stream on the first chunk. Don't pace the audio to real time: the avatar buffers it and plays it at the right speed. The size of each write doesn't matter.
- **Close the stream as soon as the reply ends.** The avatar renders speech in blocks of up to about a second of audio. A reply shorter than one block, like "Sure!", waits for the close.
- **Keep one session for the whole conversation.** Starting a session connects to the room and loads the avatar, so don't start a new one for each turn.
- **Run your pipeline in the US.** Cloud avatars render in the US. Put your LiveKit server or LiveKit Cloud project and your STT, LLM and TTS in a US region; US East is a good default.
- **Speed up the voice pipeline.** Most of a slow turn is usually spent there: end-of-speech detection, the LLM's first token and the TTS's first audio. Streaming STT and streaming TTS help the most.

## A photo instead of an agent

Expression 1 can animate a photo without an agent. Send `image`, leave out `agent_id`, and set `"model": "expression-1"`.

`image` is a string in one of these forms:

- A public `http(s)` URL. The server fetches it with a plain GET, so it must return `200` without authentication. A pre-signed URL works.
- The image as base64, either raw or as a `data:image/jpeg;base64,…` URI.

The endpoint takes JSON only.

Photo requirements:

- A JPEG or PNG.
- One person, facing the camera, with the face clearly visible.
- Head and shoulders, with room around the head.

The server finds the face and crops a square about twice the face's width, with a little extra room above the head. It scales the crop to 512×512, so a face at least ~256 px wide keeps full detail. A face near the edge of the photo gets a clipped crop. If no face is found, the whole photo is used as it is, and a photo that isn't square looks stretched.

Photo sessions work on Expression 1 only. On every other model, the request is refused with `400 VALIDATION_ERROR`, and nothing is launched or billed. To use another model, [create an agent](https://docs.bithuman.ai/api/agents#generate-an-agent) from the photo first.

## Errors

| Status | Code | Cause |
|---|---|---|
| `400` | `VALIDATION_ERROR` | One of these: a field is missing or invalid; `image` was sent without `agent_id` for a model other than Expression 1; an Essence 1 session was started without `livekit_url`, `livekit_token` and `room_name`. Nothing is launched or billed. |
| `401` | `MISSING_AUTH` / `UNAUTHORIZED` | The `api-secret` header is missing or invalid. |
| `403` | `PLAN_REQUIRED` | The model is not in your plan, or, from 2026-10-12, your account is on the Free plan. Nothing is launched or billed. |
| `403` | `CONCURRENCY_LIMIT_REACHED` | The session would exceed your plan's concurrent sessions ([Rate limits](https://docs.bithuman.ai/api/rate-limits)). |
| `404` | `NOT_FOUND` | No agent with this code that you can start. |
| `409` | `MODEL_NOT_GENERATED` · `AGENT_NOT_READY` | The agent can't be served as the requested model (it was never generated), or its own model isn't ready yet. |
| `503` | `SERVICE_UNAVAILABLE` | No capacity right now, or a temporary failure. Retry after the `Retry-After` header. |

All error codes are listed on [Errors](https://docs.bithuman.ai/api/errors).

---

# API overview

URL: https://docs.bithuman.ai/api

> REST API for avatars, voice, live sessions and embedding, from any language.

## What the API does

Plain HTTPS and JSON from any language, for backends and scripts where a native SDK does not fit. Every request carries your API secret in the `api-secret` header ([Authentication](https://docs.bithuman.ai/api/authentication)).

## Base URL

Every path on these pages is relative to `https://api.bithuman.ai`. First call: [REST API](https://docs.bithuman.ai/platforms/rest#run-your-first-avatar). Every endpoint: [API reference](https://docs.bithuman.ai/api/reference).

## What you can build

- [Agents](https://docs.bithuman.ai/api/agents): Generate avatars, make them speak and ground them in your documents.
- [Media](https://docs.bithuman.ai/api/video): Talking videos from your audio, gestures and files.
- [Embed and realtime](https://docs.bithuman.ai/api/embedding): An agent in any web page, or a Realtime voice session.
- [Account](https://docs.bithuman.ai/api/billing): Credits, API secrets, organizations and your own provider keys.

## How agents are identified

An agent is named by its code (`A80HVD8577`). Request bodies call it `agent_id` (creation, embed tokens, gestures) or `agent_code` (video, runtime tokens), never both.

## Status and versioning

Endpoints change additively. `/v1` and `/v2` are part of each path, not a version switch. Live status: [status.bithuman.ai](https://status.bithuman.ai).

---

# Authentication

URL: https://docs.bithuman.ai/api/authentication

> Authenticate with the api-secret header, check a secret, and use short-lived tokens.

Every REST call carries your API secret in the `api-secret` header. The same secret works for the SDKs and the CLI ([Your API secret](https://docs.bithuman.ai/start/api-secret)). Create one under [Developer → API Secrets](https://www.bithuman.ai/developer/api-keys); the value is shown once.

| Method | Path | Purpose | Credits |
|---|---|---|---|
| `POST` | `/v1/validate` | Check an API secret | free |
| `POST` | `/v1/runtime-tokens/request` | Exchange the secret for a short-lived runtime token (the SDKs do this for you) | free |
| `POST` | `/v1/runtime-tokens/mint` | A one-hour token scoped to one agent: for the LiveKit plugin (`"scope": "livekit-cloud"`, bound to a room when you send `room_name`/`livekit_url`) or, without `scope`, a Bearer credential for downloading that agent's model on a device | free |
| `POST` | `/v1/embed-tokens/request` | A one-hour token for a browser embed ([Embedding](https://docs.bithuman.ai/api/embedding)) | free |

## POST /v1/validate

`POST /v1/validate`

Checks the secret in the `api-secret` header. Always returns `200`; read `valid`. A request with no header, or with the secret in `Authorization: Bearer` instead of `api-secret`, also answers `200 {"valid": false}`, not `401`.

### Example

```bash tab="curl"
curl -s -X POST https://api.bithuman.ai/v1/validate -H "api-secret: $BITHUMAN_API_SECRET"
```

```python tab="Python"
import os, requests

r = requests.post("https://api.bithuman.ai/v1/validate", headers={"api-secret": os.environ["BITHUMAN_API_SECRET"]})
print(r.json())
```

### Response

```json
{"valid": true}
```

## POST /v1/runtime-tokens/request

`POST /v1/runtime-tokens/request`

Exchanges the API secret for a short-lived runtime token that authorizes rendering for your account. The Python SDK and the LiveKit plugin call it for you and renew the token while a session runs; call it yourself only when you build your own runtime integration. A runtime token cannot create other tokens or call other endpoints.

```bash
curl -X POST https://api.bithuman.ai/v1/runtime-tokens/request \
  -H "api-secret: $BITHUMAN_API_SECRET" -H "Content-Type: application/json" \
  -d '{"agent_code": "'"$BITHUMAN_AGENT_CODE"'"}'
```

Sent with `mode`, the same endpoint starts a cloud avatar in your LiveKit room instead: [Cloud avatar without the plugin](https://docs.bithuman.ai/platforms/livekit/cloud-avatar).

## POST /v1/runtime-tokens/mint

`POST /v1/runtime-tokens/mint`

Mints a one-hour token for `"scope": "livekit-cloud"` that can only start one agent's avatar in one LiveKit room. Pass it to the LiveKit plugin instead of your secret, because the plugin writes its credential into room attributes every participant can read. Send `room_name` and `livekit_url` to bind the LiveKit token to one room and server. A complete worker is on [LiveKit](https://docs.bithuman.ai/platforms/livekit#authenticate).

```bash
curl -X POST https://api.bithuman.ai/v1/runtime-tokens/mint \
  -H "api-secret: $BITHUMAN_API_SECRET" -H "Content-Type: application/json" \
  -d '{"agent_code": "'"$BITHUMAN_AGENT_CODE"'", "scope": "livekit-cloud", "room_name": "your-room", "livekit_url": "wss://your-project.livekit.cloud"}'
```

## Keep the secret safe

- Keep it in the environment or a secrets manager, never in source, a command line or an app bundle.
- Browsers get an [embed token](https://docs.bithuman.ai/api/embedding); LiveKit rooms get a minted token; shipped apps fetch a credential from your backend.
- `BITHUMAN_API_KEY` is a deprecated alias of `BITHUMAN_API_SECRET`.

## Rotate a secret

Create the new secret, move your services to it, then revoke the old one under [API Secrets](https://www.bithuman.ai/developer/api-keys). Revocation is immediate: sessions still using the old secret stop at their next usage report. The CLI's per-device secrets (`cli@<hostname>`) revoke one machine at a time. The API equivalents are on [API secrets](https://docs.bithuman.ai/api/api-keys).

## Errors

| Status | Code | Cause | Fix |
|---|---|---|---|
| `401` | `MISSING_AUTH` | no `api-secret` header (`/v1/validate` answers `valid: false` instead) | send the header on every request |
| `401` | `UNAUTHORIZED` | the secret is invalid, or a revoked secret on a REST endpoint | check it with `/v1/validate`; create a new one |
| `403` | `RUNTIME_SUSPENDED` | a revoked secret on a token endpoint (`/v1/runtime-tokens/*`, `/v1/embed-tokens/request`) | create a new secret and move your services to it |
| `403` | `RUNTIME_SUSPENDED` | runtime access is suspended for the account; the message says so | contact support |
| `403` | `PLAN_REQUIRED` | from 2026-10-12, any API secret of a Free account | [choose a plan](https://www.bithuman.ai/pricing?from=docs); a new secret does not help |
| `403` | `SECRET_REVEAL_CONSOLE_ONLY` | reading a stored secret's value with an API secret | reveal secrets in the console |

All codes: [Errors](https://docs.bithuman.ai/api/errors).

---

# Errors

URL: https://docs.bithuman.ai/api/errors

> The error format, HTTP status codes and every error code, with fixes.

## Error response format

Every error follows the same structured envelope:

```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of what went wrong.",
    "httpStatus": 401
  },
  "status": "error",
  "status_code": 401
}
```

The HTTP status always matches `status_code` and `error.httpStatus`; there is no "200 on error". Branch on either the status or `error.code`.

Successful responses do not share one envelope: some wrap the result as `{"success": true, "data": …}` (agents, credits, video), some as `{"status": "success", "status_code": 200, "data": …}` (`/v1/me`, embed tokens), and some return a bare object (`/v1/validate`, `/speak`). Each endpoint's page shows its response.

### 502 and 504 may not be JSON

A `502` or `504` comes either from the API (the envelope above, code
`UPSTREAM_UNAVAILABLE` or `UPSTREAM_TIMEOUT`) or from the delivery network in
front of it (an HTML page). Check `Content-Type` before parsing any error, and
fall back to the HTTP status line when it is not `application/json`. Both are
transient: retry after `Retry-After` seconds when present, otherwise back off.

## HTTP status codes

| Status | Meaning | [Codes](#error-codes) |
|---|---|---|
| `302` | Redirect, not an error | [Model download](https://docs.bithuman.ai/api/agents#download-an-agents-model) redirects to the artifact URL. |
| `400` | Bad Request | `MISSING_PARAM`, `VALIDATION_ERROR`, `MODEL_NOT_DOWNLOADABLE`, `MODEL_NOT_OFFERED` |
| `401` | Unauthorized | `UNAUTHORIZED`, `MISSING_AUTH` |
| `402` | Payment Required | `INSUFFICIENT_BALANCE`, `PAYWALL` |
| `403` | Forbidden | [Plan limits](#plan-and-credit-refusals), `FORBIDDEN`, `RUNTIME_SUSPENDED`, `SESSION_DURATION_LIMIT`, `SECRET_REVEAL_CONSOLE_ONLY` |
| `404` | Not Found | `NOT_FOUND`, `MODEL_ARTIFACT_NOT_READY`, `VOICE_NOT_FOUND` |
| `409` | Conflict: agent not ready for it, or a build already running | `MODEL_NOT_GENERATED`, `AGENT_NOT_READY`, `BUILD_IN_PROGRESS`, `BUILD_CONCURRENCY`, `BUILD_DAILY_CAP` |
| `410` | Gone | `AGENT_DELETED`, `AGENT_PURGED`, `ENDPOINT_RETIRED` |
| `413` / `415` | File too large / unsupported type | `FILE_TOO_LARGE`, `UNSUPPORTED_TYPE` |
| `422` | Input doesn't fit the model | `MODEL_SUBJECT_MISMATCH`, `MODEL_PREREQUISITE_MISSING`, `IMAGE_FACE_UNSUITABLE`, `KB_EMPTY` |
| `429` | Rate Limited | `RATE_LIMITED` ([rate limits](https://docs.bithuman.ai/api/rate-limits)) |
| `500` | Internal Error | `INTERNAL_ERROR`, `UPSTREAM_ERROR`. Retry, or contact support. |
| `502` / `504` | Bad Gateway / Gateway Timeout | Transient; may be HTML ([above](#502-and-504-may-not-be-json)). Retry after `Retry-After`. |
| `503` | Service Unavailable | `SERVICE_UNAVAILABLE`, `MODEL_NOT_YET_AVAILABLE`. Retry after `Retry-After`, with backoff. |

## Error codes

### Authentication

| Code | HTTP | Resolution |
|---|---|---|
| `UNAUTHORIZED` | 401 | The `api-secret` header is present but invalid. Get a valid secret from [Developer → API Secrets](https://www.bithuman.ai/developer/api-keys). |
| `MISSING_AUTH` | 401 | The `api-secret` header is absent. Add it to your request. |
| `SECRET_REVEAL_CONSOLE_ONLY` | 403 | An API secret tried to read a stored secret's value. Reveal it in the console, or create a new secret. |
| `FORBIDDEN` | 403 | A `/v2/{user_id}/…` path names another account's `user_id`. Read your own from [`GET /v1/me`](https://docs.bithuman.ai/api/billing#account-status). |

### Plan and credit refusals

A plan or credit refusal names its fix in a link field of `error`: send the user there rather than retrying.

| Code | HTTP | Resolution |
|---|---|---|
| `PLAN_REQUIRED` | 403 | Your plan does not include this; the `message` says what, and `upgrade_url` links the fix. From **2026-10-12 00:00 UTC**, a Free account's API secret is refused, and Free accounts cannot create agents or buy top-ups. A model outside your plan: the message names the plan; [contact sales](https://www.bithuman.ai/enterprise?topic=api-errors#contact). |
| `AGENT_LIMIT_REACHED` | 403 | A new agent would pass your plan's agent limit (Creator 7, Pro 40, Business 200, Enterprise unlimited): "Your {Plan} plan includes {N} agents and you have {M}. Existing agents keep working; delete one or upgrade at https://www.bithuman.ai/pricing to create more." Link: `upgrade_url`. |
| `CONCURRENCY_LIMIT_REACHED` | 403 | A new session would pass your plan's [concurrent cloud sessions](https://docs.bithuman.ai/api/rate-limits#session-concurrency); the message names the limit and how many are running. End a session or upgrade; live sessions are never cut off. An ended session frees its slot at once; to end one, [terminate it](https://docs.bithuman.ai/api/runtime-sessions#terminate-a-session). Link: `upgrade_url`, also in `details`. |
| `INSUFFICIENT_BALANCE` | 402 | Not enough credits for this action. Top up (Creator plan or higher; on Free, choose a plan), then retry. Link: `topup_url`. |
| `PAYWALL` | 402 | The account has no minutes left for a voice session: its plan's credits, its free trial and its top-ups are spent. bitHuman returns it for bitHuman Live sign-ins; an API secret that runs out of credits gets `INSUFFICIENT_BALANCE` instead. A retry does not help: choose a plan or top up, then start a new session. |
| `ACCOUNT_SUSPENDED` | 403 | Your balance is too far below zero. Top up; contact support if it persists. No link. |
| `RUNTIME_SUSPENDED` | 403 | A token endpoint refused the secret: it was revoked (create a new one), or runtime access is suspended (contact support). A plan change does not clear it. No link. |

Until 2026-10-12, a Free account's runtime-token and meter responses carry a `plan_notice` field and an `X-Bithuman-Plan-Notice` header: "Free-plan API and SDK access ends on 2026-10-12. Upgrade at https://www.bithuman.ai/pricing to keep it." A Free account with top-up credits bought before 2026-09-27 keeps access until those credits are spent, and its notice says so. Show `plan_notice` as sent. [Choose a plan](https://www.bithuman.ai/pricing?from=docs) · [top up](https://www.bithuman.ai/billing#credits).

### Agent operations

| Code | HTTP | Resolution |
|---|---|---|
| `NOT_FOUND` | 404 | Returned both when no agent matches the code **and** when an agent has no active session for `/speak` / `/add-context`. Distinguish by the `message` string: `"Agent not found for code: <code>"` vs `"No active rooms found for agent <code>"`. |
| `VALIDATION_ERROR` | 400 | Body failed schema validation. Include all required fields. |
| `VIDEO_INPUT_NOT_SUPPORTED` | 400 | [Agent creation](https://docs.bithuman.ai/api/agents#generate-an-agent) with a `video` input. Creation is **image-only** for every model — provide a portrait `image`; bitHuman generates the 10-second identity video internally so it loops without a seam (first frame == last frame). Nothing is charged; never send `video`. |
| `MISSING_PARAM` | 400 | A required parameter was not provided, or an agent update has nothing to change. |
| `IMAGE_FACE_UNSUITABLE` | 422 | Essence 2 creation or add, for a real person: the face is too small in frame, or one of several similar faces. Upload a closer waist-up or head-and-shoulders photo of one person. Nothing is charged. A photo with no face at all is `MODEL_SUBJECT_MISMATCH`. |
| `MODEL_DEFAULT_DEPRECATED` | 200 (warning) | [Agent creation](https://docs.bithuman.ai/api/agents#generate-an-agent) without `model`: the agent is created as `expression-1` and the response carries this warning. From 2026-12-26 `model` is required. Send `model` explicitly. |
| `AGENT_DELETED` / `AGENT_PURGED` | 410 | The agent was deleted; model download, gestures and talking video refuse it. Create a new agent. |

### Model errors

[Agent creation](https://docs.bithuman.ai/api/agents#generate-an-agent),
[adding a model](https://docs.bithuman.ai/api/agents#add-a-model-to-an-existing-agent),
[model download](https://docs.bithuman.ai/api/agents#download-an-agents-model),
[embed tokens](https://docs.bithuman.ai/api/embedding) and
[talking video](https://docs.bithuman.ai/api/video) share these codes:

| Code | HTTP | Resolution |
|---|---|---|
| `MODEL_NOT_GENERATED` | 409 | The agent does not have that model yet. **The message gives the fix**: the exact [add-a-model](https://docs.bithuman.ai/api/agents#add-a-model-to-an-existing-agent) call and its cost (adding `expression-1` is free and immediate), or the missing input when the agent cannot get it. Nothing is charged. |
| `AGENT_NOT_READY` | 409 | [`POST /v1/agent/{code}/models`](https://docs.bithuman.ai/api/agents#add-a-model-to-an-existing-agent) on an agent that is still generating or failed. Wait for the current generation to finish, or fix/re-create a failed agent first. |
| `MODEL_SUBJECT_MISMATCH` | 422 | Every model except Expression 2 needs a clear, real human face. A creation or model add for `essence-2`, `essence-1` or `expression-1` (also when `model` is omitted) is refused when the photo or prompt is a cartoon, a stylized character, an animal, a robot or a creature, or when no face can be found in the photo — e.g. `"Expression 1 needs a clear, real human face, and this image looks like an animal. Use Expression 2, which animates any character: cartoons, animals, robots and stylized art. Nothing was charged."` Nothing is billed and no agent is created. Use `expression-2`, or `model: "auto"` to route automatically. See [Choosing a model](https://docs.bithuman.ai/models#choosing-a-model). |
| `MODEL_PREREQUISITE_MISSING` | 422 | Adding that model needs an input this agent lacks: for `essence-2`, the video an Essence creation makes; for `expression-2`, a face image; for `expression-1`, an image and a voice; for `essence-1`, an image or that video. Add the missing image or voice, then retry. |
| `MODEL_NOT_DOWNLOADABLE` | 400 | [Model download](https://docs.bithuman.ai/api/agents#download-an-agents-model) for a model with no file: `expression-1` renders in the bitHuman cloud from the agent's image. |
| `MODEL_NOT_OFFERED` | 400 | The request names a model that is not currently offered to any account; the `message` names it. Nothing is launched or charged, and no other model is used in its place. Pick one of the [models](https://docs.bithuman.ai/models). |
| `MODEL_NOT_YET_AVAILABLE` | 503 | A model is paused for your account (not returned in normal operation). Nothing is charged; retry later or use another model. |
| `MODEL_ARTIFACT_NOT_READY` | 404 | [Model download](https://docs.bithuman.ai/api/agents#download-an-agents-model) before the file is published (shortly after the agent is ready). Retry; the message says when. |

### File operations

| Code | HTTP | Resolution |
|---|---|---|
| `FILE_TOO_LARGE` | 413 | Images 10 MB, video 100 MB, audio and documents 25 MB. |
| `UNSUPPORTED_TYPE` | 415 | The bytes are not a supported type, they contradict `file_type`, the filename extension is not one [File upload](https://docs.bithuman.ai/api/files) lists, or the file would run in a browser (SVG, HTML, scripted text). |
| `DOWNLOAD_FAILED` | 400 | Ensure the URL is publicly accessible and returns a valid file. |

### Session & infrastructure

| Code | HTTP | Resolution |
|---|---|---|
| `RATE_LIMITED` | 429 | Back off and retry. See [rate limits](https://docs.bithuman.ai/api/rate-limits). |
| `SESSION_DURATION_LIMIT` | 403 | One session ran past the maximum continuous length. Start a new session; your account is fine. |
| `SERVICE_UNAVAILABLE` | 503 | A dependency is briefly unavailable or at capacity. Nothing was changed. Retry after `Retry-After` seconds, with backoff. |
| `UPSTREAM_UNAVAILABLE` / `UPSTREAM_TIMEOUT` | 502 / 504 | Transient. Retry with backoff. |
| `INTERNAL_ERROR` | 500 | Retry once. If persistent, report via [Discord](https://www.bithuman.ai/discord). |
| `UPSTREAM_ERROR` | 500 | A backing query failed or timed out (seen on [runtime sessions](https://docs.bithuman.ai/api/runtime-sessions)). Nothing was changed. Retry with backoff. |
| `ENDPOINT_RETIRED` | 410 | The endpoint was removed; the message names its replacement. `POST /v1/realtime/ephemeral-token` answers it: connect through the [Realtime relay](https://docs.bithuman.ai/api/realtime). |
| `MODEL_LOCKED` | — | A [Realtime relay](https://docs.bithuman.ai/api/realtime) `error` event: a `session.update` tried to change the model fixed at connect. Reconnect with the new `model`. |

### Knowledge bases

| Code | HTTP | Resolution |
|---|---|---|
| `KB_EMPTY` | 422 | A [build](https://docs.bithuman.ai/api/knowledge) of a knowledge base with no source files. Upload files, then build. |
| `BUILD_IN_PROGRESS` | 409 | A build is already running on this knowledge base; the request is queued as a rebuild when it finishes. |
| `BUILD_CONCURRENCY` | 409 | Another build is running for the account. Retry when it finishes. |
| `BUILD_DAILY_CAP` | 409 | The account reached 20 builds today. Retry tomorrow. |

The CLI's exit codes, such as `PUBLIC_BIND_REFUSED`, are on [CLI troubleshooting](https://docs.bithuman.ai/platforms/cli/troubleshooting). The Flutter plugin's codes, such as `MODEL_REJECTED`, are on [Flutter errors](https://docs.bithuman.ai/platforms/flutter/errors), and the Android SDK's refusals on [Android troubleshooting](https://docs.bithuman.ai/platforms/android/troubleshooting).

## Handling errors in Python

The Python examples use [`requests`](https://pypi.org/project/requests/) (`pip install requests`). This call is free: it asks for the status of an agent that does not exist.

```python
import os, requests

resp = requests.get(
    "https://api.bithuman.ai/v1/agent/status/A00XXX0000",
    headers={"api-secret": os.environ["BITHUMAN_API_SECRET"]},
    timeout=30,
)
if resp.ok:
    print(resp.json()["data"]["status"])
elif resp.headers.get("content-type", "").startswith("application/json") and "error" in resp.json():
    err = resp.json()["error"]
    print(resp.status_code, err["code"], err["message"])  # 404 NOT_FOUND here
else:
    print(resp.status_code, "retry after", resp.headers.get("Retry-After"))
```

Retry `429` and `5xx` with exponential backoff and jitter ([rate limits](https://docs.bithuman.ai/api/rate-limits)). For a [plan or credit refusal](#plan-and-credit-refusals), follow its link field; fix the request for any other `4xx`. Is the API down? Check [status.bithuman.ai](https://status.bithuman.ai).

## API readiness

`GET /readyz`: Whether the API is refusing work right now.

```bash
curl https://api.bithuman.ai/readyz
# → {"status":"ok","families":{"sessions":{"status":"ok"}, ...}}
```

---

# Rate limits

URL: https://docs.bithuman.ai/api/rate-limits

> Request limits per plan and tier, the 429 contract, and a retry strategy.

## Request limits

Requests are limited **per account** (every API secret on the account shares the same buckets), by endpoint cost tier and plan. Each cell is requests per minute; a bucket also allows a burst of that size and refills continuously.

| Cost tier | Free | Creator | Pro | Business | Enterprise* |
|---|---|---|---|---|---|
| **Generate** | 4 | 10 | 30 | 60 | 120 |
| **Write** | 30 | 60 | 180 | 360 | 720 |
| **Read** | 120 | 240 | 720 | 1440 | 2880 |

\* Enterprise defaults; custom limits are available from [sales](https://www.bithuman.ai/enterprise?topic=api-rate-limits#contact).

| Cost tier | Covers |
|---|---|
| **Generate** | heavy jobs: `POST /v1/agent/generate`, `POST /v1/dynamics/generate`, video generation; also `POST /v1/runtime-sessions/{session_id}/end` |
| **Write** | every other `POST`, `PUT`, `PATCH`, `DELETE`, such as `POST /v1/agent/{code}/speak`, plus `GET /v1/agent/{code}/sessions` |
| **Read** | other `GET` requests, such as `GET /v1/agent/status/*` and `GET /v2/credit-summaries` |

A plan change reaches the limiter within about a minute; no new secret is needed. Over the limit, the API returns `429 RATE_LIMITED` with a `Retry-After` header and the standard [error envelope](https://docs.bithuman.ai/api/errors).

**Never limited:** webhook deliveries, and the runtime-token routes (`/v1/runtime-tokens*`, `/v1/runtime/*`) that keep a live session authenticated. A live session is never cut off with a `429`.

**Failed authentication** is throttled per client IP at 30 failures per minute. Routes that check the secret themselves (embed-token and realtime mints, `/v1/me`, CLI sign-in) are limited per client IP, at 120 requests per minute, instead of per account.

## Session concurrency

| Plan | Concurrent cloud avatar sessions |
|---|---|
| Free | 1 |
| Creator | 3 |
| Pro | 10 |
| Business | 50 |
| Enterprise | 200 |
| Custom (contact sales) | Unlimited |

A session over the allowance is refused at start with [`403 CONCURRENCY_LIMIT_REACHED`](https://docs.bithuman.ai/api/errors#plan-and-credit-refusals), whose `upgrade_url` links the plans; a live session is never cut off by this limit. Every cloud avatar counts as its own session, including avatars that share a room name. Agent and dynamics generation jobs queue and run as capacity frees up.

A session stops counting the moment it ends: the room closes, the last user leaves, or you remove the avatar participant (`bithuman-avatar-agent`) from your LiveKit room. That holds for every cloud session: the bitHuman app, the web embed, and a cloud avatar in your own LiveKit room. To end one yourself and free its slot at once, [terminate the session](https://docs.bithuman.ai/api/runtime-sessions#terminate-a-session).

**Session length.** One continuous session can run up to 24 hours in the cloud and 7 days self-hosted. It then ends with `403 SESSION_DURATION_LIMIT`; start a new session to continue. For longer unattended installs (kiosks), [contact sales](https://www.bithuman.ai/enterprise?topic=api-rate-limits#contact).

Sessions you render on your own hardware are limited only by your credits ([self-hosting](https://docs.bithuman.ai/deploy/self-hosted)). Cost: active session time, to the second ([pricing](https://docs.bithuman.ai/pricing)).

## Response headers

Metered endpoints return your current state, so you can slow down before a `429`:

| Header | Meaning |
|---|---|
| `X-RateLimit-Limit` | your plan's limit for this request's cost tier |
| `X-RateLimit-Remaining` | whole requests left right now |
| `X-RateLimit-Reset` | Unix time when the bucket is full again |
| `Retry-After` | on `429` only: seconds to wait |
| `X-Request-Id` | include it when you contact support |

Not every response carries them (`POST /v1/validate` has none); fall back to backoff.

## Recommended retry strategy

Retry `429` and `5xx` with exponential backoff and jitter, honouring `Retry-After`:

```python
import time, random, requests

def call(method, url, max_retries=5, **kw):
    for attempt in range(max_retries):
        resp = requests.request(method, url, timeout=30, **kw)
        if resp.status_code not in (429, 502, 503, 504):
            return resp
        wait = float(resp.headers.get("Retry-After", 2 ** attempt))
        time.sleep(wait + random.uniform(0, 1))
    return resp
```

Usage: `call("POST", "https://api.bithuman.ai/v1/video/generate", headers=h, json={...})`.

## Best practices

- **Use [webhooks](https://docs.bithuman.ai/api/webhooks), not polling,** for `agent.ready` and `agent.failed`. If you poll status, poll every 5 seconds or slower.
- **Cache agent details** from `GET /v1/agent/{code}`; they rarely change.
- **Reuse a session** for back-to-back conversations rather than starting a new one; note that an open session bills its time, talking or idle.
- **Check your balance** with `GET /v2/credit-summaries` before creating an agent ([creation costs](https://docs.bithuman.ai/pricing#creation--one-time-credits)), to avoid a `402`.

More capacity comes with a higher [plan](https://docs.bithuman.ai/pricing#plans); for more than Enterprise, [contact sales](https://www.bithuman.ai/enterprise?topic=api-rate-limits#contact).

---

# Realtime relay

URL: https://docs.bithuman.ai/api/realtime

> Open a metered OpenAI-Realtime voice session through bitHuman, over WebSocket or WebRTC.

## Overview

A voice conversation (speech in, speech out) with no OpenAI key of your own: the relay opens an
OpenAI-Realtime voice session **through bitHuman** and bills it in bitHuman credits as the chat
line, 10 credits a minute, all-inclusive ([Limits & billing](#limits--billing)). Your API secret
never leaves your server or app. Pair it with an on-device avatar to give the voice a face, as
the Flutter plugin and the CLI do. There are two ways in:

- **WebSocket relay:** `wss://api.bithuman.ai/v1/realtime`, the OpenAI Realtime WebSocket
  protocol, unchanged.
- **WebRTC:** `POST /v1/realtime/connect` with your SDP offer; bitHuman places the call and
  returns the SDP answer.

Authenticate with the `api-secret` header (or `Authorization: Bearer <api-secret>`).

## WebSocket relay

`wss://api.bithuman.ai/v1/realtime?model=gpt-realtime-mini`

Speak the [OpenAI Realtime events](https://platform.openai.com/docs/api-reference/realtime)
exactly as you would to OpenAI: `session.update`, `input_audio_buffer.append`,
`response.create`, and so on. The model is fixed when you connect: a `session.update` that
repeats it is accepted, and one that changes it is answered with an `error` event whose
code is `MODEL_LOCKED`.

```python
import asyncio, json, os, websockets

async def main():
    async with websockets.connect(
        "wss://api.bithuman.ai/v1/realtime?model=gpt-realtime-mini",
        additional_headers={"api-secret": os.environ["BITHUMAN_API_SECRET"]},
    ) as ws:
        print(json.loads(await ws.recv())["type"])   # session.created
        await ws.send(json.dumps({"type": "session.update", "session": {
            "type": "realtime", "instructions": "Answer in one sentence.",
            "output_modalities": ["audio"]}}))
        print(json.loads(await ws.recv())["type"])   # session.updated

asyncio.run(main())
```

The Flutter plugin (2.6.20+) and the CLI (2.8.1+) connect this way for you.

## WebRTC

`POST /v1/realtime/connect`

`POST /v1/realtime/connect?model=gpt-realtime-mini`, with the SDP offer as the request body
(`Content-Type: application/sdp`). A `201` carries the SDP answer; set it as the remote
description on your peer connection. The `X-Bithuman-Call` response header names the call.

**End the call when you are done.** Billing stops the moment you hang up:

```bash
curl -X POST https://api.bithuman.ai/v1/realtime/connect \
  -H "api-secret: $BITHUMAN_API_SECRET" -H "content-type: application/json" \
  -d '{"action": "hangup", "call": "<X-Bithuman-Call>"}'
```

```js
// browser: start the call from your server (it holds the api-secret), then on close:
pc.close();
await fetch("/your-server/hangup", { method: "POST", body: JSON.stringify({ call }) });
// your server: POST https://api.bithuman.ai/v1/realtime/connect
//   {"action": "hangup", "call": call}  with the same api-secret that started it
```

If a client only closes its peer connection without hanging up, the call ends when the
connection times out, usually 8–10 seconds later, and those seconds are billed.

## Limits & billing

- **Billing:** the chat line, **10 credits per minute, all-inclusive**, for every active
  second of the session (talking or idle). A self-hosted avatar rendering the same session
  is included: it is not billed on top.
- **Balance:** a session needs a positive balance to start (`402 INSUFFICIENT_BALANCE`) and
  is closed when the balance runs out.
- **Models:** a standard API secret uses `gpt-realtime-mini`; `gpt-realtime` needs an
  entitlement on your account (`403 PLAN_REQUIRED` otherwise; contact sales).
- **Length:** one session lasts at most one hour.
- **How a session ends on an error:** an `error` event with `type: bithuman_relay` names the
  code, then the socket closes with code 1008: `INSUFFICIENT_BALANCE` (the credits ran out),
  `FORBIDDEN` (bitHuman stopped the session) or `SESSION_DURATION_LIMIT` (the hour is up). Build a
  new session; a retry of the same one does not help. The Flutter plugin reports these codes on
  `errorStream` ([Flutter errors](https://docs.bithuman.ai/platforms/flutter/errors#voice-session)).
- **`PAYWALL`:** bitHuman Live's refusal (HTTP 402) when an account has no minutes left: its
  plan's credits, its free trial and its top-ups are spent. An API secret that runs out gets
  `INSUFFICIENT_BALANCE` instead ([Errors](https://docs.bithuman.ai/api/errors#plan-and-credit-refusals)).
- Other errors: `401` missing or invalid key · `503` the relay is at capacity (retry after the
  `Retry-After` seconds).

---

# Agents

URL: https://docs.bithuman.ai/api/agents

> Create an avatar agent from a portrait, then manage it and make it speak.

An agent is an avatar (face, voice and persona) identified by a short code such as `A23WJF0199`. Create one, poll until it is `ready`, then use it everywhere: the [web embed](https://docs.bithuman.ai/platforms/web), the SDKs, [talking video](https://docs.bithuman.ai/api/video) and live sessions. Creation and model adds cost credits per model ([pricing](https://docs.bithuman.ai/pricing)); everything else on this page is free.

The sample avatars (such as `A23WJF0199`, `wise-pup`) only [download](#download-an-agents-model); every other call on this page needs an agent you own, and returns `404` for a sample.

To add knowledge to a live session, see [Knowledge](https://docs.bithuman.ai/api/knowledge#inject-knowledge); every operation is also in the [API reference index](https://docs.bithuman.ai/api/reference).

## Generate an agent

`POST /v1/agent/generate`

Starts an asynchronous creation and returns an `agent_id` at once. Credits are reserved at submit and refunded automatically if creation fails. Pick the model from the subject: a real person → `essence-2`; a cartoon, animal, robot or any other character → `expression-2` ([Choosing a model](https://docs.bithuman.ai/models#choosing-a-model)).

### Request

| Parameter | Type | Required | Description |
|---|---|---|---|
| `model` | string | always send it | `essence-2` (a real person), `expression-2` (any character) or `auto` (picks from the image). `essence-1` and `expression-1` are the first generation. Always send it: it becomes required on 2026-12-26 (see Notes). |
| `image` | string | no | Portrait URL (publicly fetchable) or base64. Used as a reference; a portrait is generated from `prompt` when omitted |
| `prompt` | string | no | System prompt and personality |
| `audio` | string | no | Voice sample URL or base64, for voice cloning |
| `aspect_ratio` | string | no | `16:9` (default), `9:16` or `1:1` |
| `framing` | string | no | `portrait` (default) or `full_body` |
| `transparency` | boolean | no | `true` generates on a green-screen background for chroma key |
| `agent_id` | string | no | Leave it out; a fresh code is generated. If it names an agent you already own, that agent is regenerated in place (it returns to `processing`); another account's code returns `404` |

A model outside your plan gets `403 PLAN_REQUIRED`.

Headers: `api-secret`, and optionally `Idempotency-Key`: a repeated request with the same key returns the first response and starts no second creation.

### Example

```bash tab="curl"
curl -X POST https://api.bithuman.ai/v1/agent/generate \
  -H "Content-Type: application/json" \
  -H "api-secret: $BITHUMAN_API_SECRET" \
  -H "Idempotency-Key: museum-guide-1" \
  -d '{"model": "expression-2", "prompt": "You are a cheerful museum guide.", "image": "https://example.com/portrait.jpg"}'
```

```python tab="Python"
import os, requests

resp = requests.post(
    "https://api.bithuman.ai/v1/agent/generate",
    headers={"api-secret": os.environ["BITHUMAN_API_SECRET"]},
    json={"model": "expression-2", "prompt": "You are a cheerful museum guide.", "image": "https://example.com/portrait.jpg"},
)
print(resp.json())
```

### Response

```json
{"success": true, "message": "Agent generation started", "agent_id": "A80HVD8577", "status": "processing"}
```

### Notes

- Omitted, `model` still creates an `expression-1` agent and warns (`MODEL_DEFAULT_DEPRECATED`), so a character is refused with `422`. From 2026-12-26 `model` is required, and the bare names `essence` and `expression` (and the `version` field) are refused with a `400` naming the replacement.
- Creation takes minutes for `essence-1` and `expression-1`, and about 2–2.5 hours for `essence-2` and `expression-2`. Set your polling timeout per model.
- Every model except `expression-2` needs a clear, real human face. For `essence-2`, `essence-1` or `expression-1`, a cartoon, stylized character, animal, robot or creature in the photo or prompt, or a photo with no face found, returns `422 MODEL_SUBJECT_MISMATCH` before anything is charged; the message tells you to use Expression 2. An `essence-2` creation or add also checks the photo's face before charging: a face too small in frame, or several similar-sized faces, returns `422 IMAGE_FACE_UNSUITABLE` — upload a closer photo of one person. `auto` routes people to `essence-2` and everything else to `expression-2`.
- A `200` does not mean the image was fetched. An unreachable `image` fails the creation a few seconds later (refunded); poll [status](#poll-status) to confirm. Creation is image-only: a `video` field returns `400 VIDEO_INPUT_NOT_SUPPORTED`.
- At most two `essence-2` creations run at once per account; a third fails at once with a capacity message and no charge.

## Poll status

`GET /v1/agent/status/{agent_id}`

Reports a creation's progress. Poll every 5 seconds until `status` is `ready` or `failed`; every other value is intermediate. The response is the agent's full record, the same as [Get an agent](#get-an-agent); the fields below are the ones to poll.

```bash
curl https://api.bithuman.ai/v1/agent/status/A80HVD8577 -H "api-secret: $BITHUMAN_API_SECRET"
```

```json
{"success": true, "data": {"agent_id": "A80HVD8577", "status": "ready", "progress": 1.0, "current_step": "done", "error_message": null, "supported_models": ["expression-2"], "model_status": {"expression-2": {"state": "ready", "reason": null}}, "name": "Museum Guide"}}
```

| `current_step` | Progress | Stage |
|---|---|---|
| `payment` | about 2% | credits reserved |
| `persona` | 5–15% | persona prepared |
| `voice_image` | about 20% | voice and portrait |
| `video` | about 45% | identity video (Essence models) |
| `lip_sync` | 70–99% | the model step; the longest for second-generation models |
| `done` | 100% | `ready` |

```python
import os, time, requests

def wait_until_ready(agent_id, timeout_s=3 * 3600):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"https://api.bithuman.ai/v1/agent/status/{agent_id}",
                         headers={"api-secret": os.environ["BITHUMAN_API_SECRET"]}, timeout=30)
        if r.ok:
            data = r.json()["data"]
            if data["status"] == "ready":
                return data
            if data["status"] == "failed":
                raise RuntimeError(data["error_message"])
        time.sleep(5)   # creation continues server-side through transient errors
    raise TimeoutError(agent_id)
```

### Notes

- `supported_models` lists the models the agent can be launched as, spelled as `model` values you can send back.
- `model_status` gives each requested model's state (`pending`, `ready`, `failed`). Models never requested are absent.
- For second-generation models `model_url` is a storage reference, not a link: fetch the file with [Download an agent's model](#download-an-agents-model).
- The downloadable model file is published shortly after `ready`; until then the [download](#download-an-agents-model) returns `404 MODEL_ARTIFACT_NOT_READY`. Retry.

## Get an agent

`GET /v1/agent/{code}`

Returns the agent's full record: persona (`system_prompt`, `name`, `language`), `voice_id`, media URLs, creation state, `model` and `supported_models`.

```bash
curl https://api.bithuman.ai/v1/agent/A80HVD8577 -H "api-secret: $BITHUMAN_API_SECRET"
```

```json
{"success": true, "data": {"code": "A80HVD8577", "status": "ready", "model": "expression-2", "supported_models": ["expression-2"], "name": "Museum Guide", "system_prompt": "You are a cheerful museum guide.", "language": "en", "voice_id": "bf0a246a-8642-498a-9950-80c35e9276b5", "image_url": "https://…/image.jpg"}}
```

## List your agents

`GET /v1/agents`

Lists your agents, newest first. Query: `limit` (default 20, max 100), `offset`, `status` (for example `ready`). Items are summaries (`code`, `name`, `model`, `status`, `supported_models`, `created_at` and a few more); read the full record with [Get an agent](#get-an-agent). Deleted agents appear with `status: "deleted"`. Older agents can also show `completed`, `success` or `unknown`; read `supported_models` to see what they can launch as.

```bash
curl "https://api.bithuman.ai/v1/agents?status=ready&limit=20" -H "api-secret: $BITHUMAN_API_SECRET"
```

```json
{"success": true, "data": [{"code": "A80HVD8577", "name": "Museum Guide", "model": "expression-2", "status": "ready"}], "pagination": {"limit": 20, "offset": 0, "total": 1, "has_more": false}}
```

## Update an agent

`POST /v1/agent/{code}` (not `PATCH`, which returns `404`) changes the `system_prompt`, the voice-provider selection (`providers`, see [Voice providers](https://docs.bithuman.ai/api/providers)), or both. Send at least one, or the call returns `400 MISSING_PARAM`. The name is generated and cannot be set. The voice cannot be set here: change it in the bitHuman app ([Voices](https://docs.bithuman.ai/build/voices#change-the-voice)).

```bash
curl -X POST https://api.bithuman.ai/v1/agent/A80HVD8577 \
  -H "Content-Type: application/json" -H "api-secret: $BITHUMAN_API_SECRET" \
  -d '{"system_prompt": "You are a concise sales assistant."}'
```

```json
{"agent_code": "A80HVD8577", "updated": true}
```

## Delete an agent

`DELETE /v1/agent/{code}`

Deletes an agent you own. Usage history is kept. An unknown or unowned code returns `404`.

```bash
curl -X DELETE https://api.bithuman.ai/v1/agent/A80HVD8577 -H "api-secret: $BITHUMAN_API_SECRET"
```

```json
{"success": true, "agent_code": "A80HVD8577", "deleted": true}
```

## Add a model to an existing agent

`POST /v1/agent/{code}/models`

Adds a model to a `ready` agent without re-creating it; the body is `{"model": "<model>"}`. Re-adding a model the agent has costs nothing, and a failed add is refunded.

| `model` | Needs | Time | Credits |
|---|---|---|---|
| `expression-1` | a stored image and voice, of a real person | immediate | free |
| `expression-2` | a stored image | about 2–2.5 h | 2000 |
| `essence-2` | a stored identity video and a photoreal person | about 2–2.5 h | 500 |
| `essence-1` | a stored image or identity video, of a real person | 10–20 min | 250 |

```bash
curl -X POST https://api.bithuman.ai/v1/agent/A80HVD8577/models \
  -H "Content-Type: application/json" -H "api-secret: $BITHUMAN_API_SECRET" \
  -d '{"model": "essence-2"}'
```

```json
{"success": true, "agent_id": "A80HVD8577", "model": "essence-2", "status": "processing", "supported_models": ["expression-2"]}
```

Poll [status](#poll-status) until `model_status["essence-2"].state` is `ready` or `failed`. The top-level `status` stays `ready` during an add. A failed add is refunded, and its `reason` says why. Errors: `409 AGENT_NOT_READY`, `422 MODEL_PREREQUISITE_MISSING`, `422 MODEL_SUBJECT_MISMATCH` (an `essence-2`, `essence-1` or `expression-1` add for an agent that isn't a real person; nothing is charged, see [Choosing a model](https://docs.bithuman.ai/models#choosing-a-model)).

## Download an agent's model

`GET /v1/agent/{code}/model/download`

Redirects (`302`) to the agent's model file, a `.imx` container, for the [SDKs](https://docs.bithuman.ai/platforms) and [CLI](https://docs.bithuman.ai/platforms/cli). Pass `?model=` to choose a model when the agent has several; the default is the model it was created with. Sample avatars download with no credential; your own agents need the `api-secret` header.

```bash
curl -fL -o A80HVD8577.imx -H "api-secret: $BITHUMAN_API_SECRET" \
  "https://api.bithuman.ai/v1/agent/A80HVD8577/model/download?model=expression-2"
```

Name the output file yourself (`-o`). Add `?redirect=false` to get the URL as JSON:

```json
{"success": true, "data": {"code": "A80HVD8577", "model": "expression-2", "filename": "A80HVD8577.imx", "url": "https://…", "expires_in": 3600}}
```

| Status | Code | Meaning |
|---|---|---|
| `400` | `MODEL_NOT_DOWNLOADABLE` | the model has no file (`expression-1`) |
| `403` | `PLAN_REQUIRED` | the model is not in your plan; the message names the plan |
| `404` | `MODEL_ARTIFACT_NOT_READY` | published shortly after `ready`; retry |
| `409` | `MODEL_NOT_GENERATED` | the agent does not have that model; [add it](#add-a-model-to-an-existing-agent) |

## List the freely downloadable showcase models

`GET /v1/models/showcase`

Lists the sample avatars anyone can download, with no API secret and no account: slug, agent code, model and size. Each entry's `url` is [Download an agent's model](#download-an-agents-model). `bithuman list` and `bithuman pull` read this list.

```bash
curl https://api.bithuman.ai/v1/models/showcase
```

```json
{"version": 2, "updated": "2026-09-10", "models": [{"slug": "bolt", "name": "Bolt", "model": "expression-2", "agent_code": "X03BOLT", "url": "https://api.bithuman.ai/v1/agent/X03BOLT/model/download?model=expression-2", "size": 198106157}]}
```

## List an agent's live sessions

`GET /v1/agent/{code}/sessions`

Lists the agent's open sessions. Use a `room_id` whose `deliverable` is `true` with [speak](#make-an-agent-speak) or [add-context](https://docs.bithuman.ai/api/knowledge#inject-knowledge).

```bash
curl https://api.bithuman.ai/v1/agent/A80HVD8577/sessions -H "api-secret: $BITHUMAN_API_SECRET"
```

```json
{"agent_code": "A80HVD8577", "sessions": [{"room_id": "room-A80HVD8577-x1y2", "num_participants": 2, "created_at": 1788480000, "deliverable": true}]}
```

## Make an agent speak

`POST /v1/agent/{code}/speak`

Makes the avatar say `message` in its live sessions: one session with `room_id`, or every deliverable session without it. With no live session it returns `404 NOT_FOUND`.

```bash
curl -X POST https://api.bithuman.ai/v1/agent/A80HVD8577/speak \
  -H "Content-Type: application/json" -H "api-secret: $BITHUMAN_API_SECRET" \
  -d '{"message": "We have a 20% discount today.", "room_id": "room-A80HVD8577-x1y2"}'
```

```json
{"agent_code": "A80HVD8577", "delivered_to_rooms": 1, "rooms": ["room-A80HVD8577-x1y2"], "rooms_skipped": [], "rooms_failed": []}
```

---

# Embedding

URL: https://docs.bithuman.ai/api/embedding

> Mint short-lived tokens on your backend and embed an avatar in any website.

## Embed an avatar

Drop an agent onto any page as an iframe — no SDK install required:

```html
<iframe src="https://www.bithuman.ai/embed/A23WJF0199" allow="microphone *; camera *; autoplay *" style="width:100%;height:100vh;border:0"></iframe>
```

`A23WJF0199` is the `wise-pup` sample avatar (Expression 2). Replace it with your agent code — find it in the
[Library](https://www.bithuman.ai/#library) or the Deploy & Share dialog.

> **Warning** Keep `microphone *` (and `camera *` for camera chat) in `allow`, with the `*`. The embed redirects to another origin, so a bare `allow="microphone"` leaves the microphone silently blocked. A restrictive `Permissions-Policy` on your page blocks it too.

## Production: mint a token

`POST /v1/embed-tokens/request`

For per-visitor session tracking and rate limiting, mint a short-lived embed
token on your **backend** (never expose your API secret in frontend code) and
append it to the iframe URL.

`POST /v1/embed-tokens/request`

| Field | Type | Required | Description |
|---|---|---|---|
| `agent_id` | string | yes | Your agent's code. This endpoint reads `agent_id` only: `agent_code` returns `400`. |
| `fingerprint` | string | yes | Stable per-visitor string (any format). Used for per-visitor rate limiting and — if you run your own LLM — sent to your endpoint as the OpenAI `user` field so you can tell whose call it is ([details](https://docs.bithuman.ai/api/providers#knowing-which-end-user-a-call-belongs-to)). Supply one value per end user and reuse it across their visits. |
| `model` | string | no | `essence-1`, `essence-2`, `expression-1` or `expression-2`; defaults to the agent's model. A model the agent does not have returns [`409 MODEL_NOT_GENERATED`](https://docs.bithuman.ai/api/errors#model-errors); one outside your plan, `403 PLAN_REQUIRED`. |

Every entry of `supported_models` in the mint response (and in `GET /v1/agent/status/{id}`) is a model name you can send back as `model` unchanged.

Call it from your server, so the API secret never reaches the browser; `data.token` goes on the iframe URL.

```bash
curl -X POST https://api.bithuman.ai/v1/embed-tokens/request \
  -H "api-secret: $BITHUMAN_API_SECRET" -H "Content-Type: application/json" \
  -d '{"agent_id": "A23WJF0199", "fingerprint": "3f9a2c1b8e7d4a6f0b21c4d5e6f70812"}'
```

### Response

```json
{
  "status": "success",
  "status_code": 200,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "sid": "f3c9...",
    "model": "expression-2",
    "supported_models": ["expression-2"]
  }
}
```

The `token` is a **1-hour, HS256-signed JWT**. Mint one per visitor session.
`supported_models` lists the canonical model families the agent can be
launched as right now (useful for building your own model picker). The
response always includes the `model` baked into the token (the agent's own
model when you omit it).

### Use the token in the iframe

Pass it as a query string:

```html
<iframe src="https://www.bithuman.ai/embed/YOUR_AGENT_CODE?token=THE_TOKEN" allow="microphone *; camera *; autoplay *" style="width:100%;height:100vh;border:0"></iframe>
```

## Session events

Every conversation on an embed of your agent can POST `room.join` and `chat.push`
events, including the text of every message, to a URL on your account. See
[session events](https://docs.bithuman.ai/api/webhooks#session-events).

## Notes

- The embed token is more constrained than a [runtime token](https://docs.bithuman.ai/api/authentication)
  — it's purpose-built for cross-origin iframe authentication.
- WebRTC requires a secure context: serve the embedding page over **HTTPS** or
  the browser will block microphone access (except on `localhost`).
- The `fingerprint` should be generated once per device and persisted, so
  per-visitor rate limits track the same visitor across sessions.
- An embedded session bills to the agent's owner at the rates on
  [pricing](https://docs.bithuman.ai/pricing).

See the interactive [API reference](https://docs.bithuman.ai/api/reference) for the full request and
response schema.

---

# Talking video API

URL: https://docs.bithuman.ai/api/video

> Render a talking-video MP4 from your own hosted audio.

## Overview

Renders an MP4 of one of your agents speaking **your audio**: a WAV or MP3 at a public URL, from a recording or any text-to-speech tool. Submit a job and poll for the URL, or pass [`wait: true`](#blocking-mode-wait-true) to get the MP4 in the response.

`essence-2` renders at up to 1080p, `1080×1920` or `1920×1080` to match the source; `expression-2` renders at `416×720`.

Renders bill **per minute of output, rounded up**: 4 credits/min for `essence-2`, `expression-2` and `expression-1`, 2 for `essence-1`. A job charges the 120-second maximum up front and refunds the difference when it finishes, so your balance must cover that maximum at submit time. A failed render is refunded in full.

Limits: up to **120 seconds** of output.

## Generate a talking video

`POST /v1/video/generate`

**Before you start:** you need an agent code. Any API secret can render a public sample, such as `A23WJF0199` (`wise-pup`, `expression-2`), from audio; [`GET /v1/models/showcase`](https://api.bithuman.ai/v1/models/showcase) lists them, and each one's `supported_models` says which `model` to pass. The video bills you, never the sample's owner. Or list your own agents with `curl https://api.bithuman.ai/v1/agents -H "api-secret: $BITHUMAN_API_SECRET"`. Then `export BITHUMAN_AGENT_CODE=A…`. Creating an agent needs the Creator plan or higher ([Pricing](https://docs.bithuman.ai/pricing#plans)).

`POST /v1/video/generate` returns a `job_id` with `status: "processing"`; poll [`GET /v1/video/{job_id}`](#get-talking-video-status) until it completes, or register a [webhook](https://docs.bithuman.ai/api/webhooks) for `video.completed` / `video.failed`.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `model` | string | yes | Model: `essence-1`, `expression-1`, `expression-2`, or `essence-2`. All four render talking video today. A model outside your plan returns `403 PLAN_REQUIRED`. |
| `agent_code` | string | yes | An agent you own, or a public sample — supplies the avatar identity. |
| `input` | object | yes | The render source — see below. |
| `input.type` | string | yes | `audio`. |
| `input.audio_url` | string | yes | Public URL to a WAV or MP3 file. |
| `wait` | boolean | no | `true` returns the finished video in this response (up to ~90 s, else a `job_id`); `false` (default) returns a `job_id` to poll. See [Blocking mode](#blocking-mode-wait-true). |

### Audio input

Bring your own audio: a recording, or a WAV or MP3 from any text-to-speech tool, at a public URL. To try it, use the 5-second sample, `https://docs.bithuman.ai/samples/speech-16k-short.wav`.

```bash
curl -X POST https://api.bithuman.ai/v1/video/generate \
  -H "api-secret: $BITHUMAN_API_SECRET" -H "Content-Type: application/json" \
  -d '{"model": "expression-2", "agent_code": "'"$BITHUMAN_AGENT_CODE"'", "input": {"type": "audio", "audio_url": "https://docs.bithuman.ai/samples/speech-16k-short.wav"}}'
```

```json
{
  "success": true,
  "job_id": "vid_3f9a2c1b8e7d4a6f0b21",
  "status": "processing"
}
```

### Blocking mode (`wait: true`)

Add `"wait": true` (a JSON/multipart field, or `?wait=true` as a query
parameter) to hold the connection until the render finishes and get the mp4 back
in the same response — no polling. If the render exceeds the ~90-second cap you
get the async `{ job_id }` to poll instead.

```bash
curl -X POST https://api.bithuman.ai/v1/video/generate \
  -H "api-secret: $BITHUMAN_API_SECRET" -H "Content-Type: application/json" \
  -d '{"model": "essence-2", "agent_code": "'"$BITHUMAN_AGENT_CODE"'", "input": {"type": "audio", "audio_url": "https://docs.bithuman.ai/samples/speech-16k-short.wav"}, "wait": true}'
```

```json
{
  "success": true,
  "job_id": "vid_3f9a2c1b8e7d4a6f0b21",
  "status": "completed",
  "video_url": "https://assets.bithuman.ai/.../vid_3f9a2c1b8e7d4a6f0b21.mp4",
  "duration_seconds": 6.5,
  "credits_charged": 4
}
```

Errors are returned at submit time, before any charge: `402 INSUFFICIENT_BALANCE` if your balance cannot cover the up-front maximum; `400` for an invalid `model` or `input`; [`409 MODEL_NOT_GENERATED`](https://docs.bithuman.ai/api/errors#model-errors) if the agent does not have that model yet. Check the agent's `supported_models` ([poll status](https://docs.bithuman.ai/api/agents#poll-status)) or [add the model](https://docs.bithuman.ai/api/agents#add-a-model-to-an-existing-agent).

## Get talking-video status

`GET /v1/video/{job_id}`

Poll a render job.

```bash
curl https://api.bithuman.ai/v1/video/vid_3f9a2c1b8e7d4a6f0b21 -H "api-secret: $BITHUMAN_API_SECRET"
```

While rendering:

```json
{ "success": true, "job_id": "vid_3f9a2c1b8e7d4a6f0b21", "status": "processing", "model": "essence-2" }
```

When complete:

```json
{
  "success": true,
  "job_id": "vid_3f9a2c1b8e7d4a6f0b21",
  "status": "completed",
  "model": "essence-2",
  "video_url": "https://assets.bithuman.ai/.../vid_3f9a2c1b8e7d4a6f0b21.mp4",
  "duration_seconds": 6.5,
  "credits_charged": 4
}
```

| Field | Type | Description |
|---|---|---|
| `status` | string | `processing`, `completed`, or `failed`. |
| `model` | string | The engine used. |
| `video_url` | string | Public mp4 URL (present when `completed`). |
| `duration_seconds` | number | Output duration (present when `completed`). |
| `credits_charged` | integer | Credits charged for this render (present when `completed`). |
| `error` | object | Failure detail (present when `failed`); the charge is refunded. |

> **Note** Read `video_url` from the response; never construct it. The storage host can change, so allowlist what the API returns.

## Polling pattern

```python
import time, requests

def wait_for_video(job_id, api_secret, timeout=600):
    while timeout > 0:
        r = requests.get(
            f"https://api.bithuman.ai/v1/video/{job_id}",
            headers={"api-secret": api_secret},
        ).json()
        if r["status"] == "completed":
            return r["video_url"]
        if r["status"] == "failed":
            raise RuntimeError(r.get("error"))
        time.sleep(3)
        timeout -= 3
    raise TimeoutError("render did not finish in time")
```

See [pricing](https://docs.bithuman.ai/pricing) for how credits are consumed.