# bitHuman — Build (voice agent, companion app, kiosk, talking video, avatars, personas, voices, gestures, MCP, troubleshooting)

> Realtime 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 · other sections: https://docs.bithuman.ai/llms/start.txt · https://docs.bithuman.ai/llms/platforms.txt · https://docs.bithuman.ai/llms/deploy.txt · https://docs.bithuman.ai/llms/models.txt · https://docs.bithuman.ai/llms/api.txt

## 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 things happen: the avatar renders (device, browser, server, cloud); the conversation runs (your stack, the CLI's local conversation brain, or bitHuman's servers).
- Quote speed only from https://docs.bithuman.ai/performance.json (× real time, with the device). Quote prices only from GET https://api.bithuman.ai/v1/pricing.
- Do not claim offline on phones, Mac or the browser, a conversation brain on phones, or any certification.

Where each model runs, the key facts and one command per path: https://docs.bithuman.ai/llms.txt

## Contents

- Create your own avatar — https://docs.bithuman.ai/build/create-avatar
- Persona — https://docs.bithuman.ai/build/persona
- Voices — https://docs.bithuman.ai/build/voices
- Gestures (Essence 1) — https://docs.bithuman.ai/build/gestures
- Voice agent — https://docs.bithuman.ai/build/voice-agent
- Website widget — https://docs.bithuman.ai/build/website-widget
- Companion app — https://docs.bithuman.ai/build/companion-app
- Kiosk on a Linux PC — https://docs.bithuman.ai/build/kiosk
- Talking video — https://docs.bithuman.ai/build/talking-video
- Claude & Cursor (MCP) — https://docs.bithuman.ai/build/mcp
- Troubleshooting — https://docs.bithuman.ai/resources/troubleshooting

Linked, not inlined (read the .md twin):
- 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

---

# Create your own avatar

URL: https://docs.bithuman.ai/build/create-avatar

> Turn a portrait, a voice sample and a prompt into your own avatar: what to upload, how to write the persona, and the API call.

An avatar is a face, a voice and a personality, packaged as one agent with a short code. Use a [sample avatar](https://docs.bithuman.ai/examples#ready-made-avatars) to start, or create your own from one portrait.

*Diagram: Creating an avatar.* You upload one portrait. Avatar creation happens in the bitHuman cloud and takes about 2 to 2.5 hours. The finished avatar model then runs on your devices (iPhone, iPad, Mac, Android, a Linux PC or a WebGPU browser) or in the bitHuman cloud.

## Before you start

- An [API secret](https://docs.bithuman.ai/start/api-secret) on the Creator plan or higher, and credits for the creation ([pricing](https://docs.bithuman.ai/pricing#creation--one-time-credits)).
- A portrait image at a public URL (or create one from a prompt).
- Optionally, 3–10 seconds of clean speech for voice cloning.

## 1. Choose a model

| You have | Use |
|---|---|
| A photo of a real person | `essence-2`: photoreal, up to 1080p |
| A character, animal, robot or illustration | `expression-2`: any subject |
| Not sure | `auto`: people go to `essence-2`, everything else to `expression-2` |

More on the difference: [Models](https://docs.bithuman.ai/models).

## 2. Pick the inputs

| Input | Use for | Limits |
|---|---|---|
| Image | the face | under 10 MB; one clear figure, neutral expression, facing the camera, face unobstructed |
| Voice | voice cloning | under 1 minute of clean speech (MP3, WAV or M4A), no music |
| Prompt | the personality | required when there is no image |

### What makes a good photo

One subject, in focus, facing the camera with a resting expression and the whole face visible (eyes, nose and mouth). Photos are not checked; these are the conditions the models are built for. For an animal, use a well-lit, front-facing photo with the face filling the frame.

Without a voice sample, a voice is generated to match the persona. Without a prompt, a persona is generated from the image.

## 3. Create the agent

```bash
curl -X POST https://api.bithuman.ai/v1/agent/generate \
  -H "Content-Type: application/json" -H "api-secret: $BITHUMAN_API_SECRET" \
  -d '{"model": "auto", "prompt": "You are a friendly receptionist.", "image": "https://example.com/headshot.jpg"}'
```

The response carries an `agent_id`. Creation takes about 2–2.5 hours for the second-generation models. You can also create an agent in the dashboard at [bithuman.ai](https://www.bithuman.ai/explore), which starts on Expression 2.

## 4. Wait until it is ready

Poll [`GET /v1/agent/status/{agent_id}`](https://docs.bithuman.ai/api/agents#poll-status) every few seconds until `status` is `ready` or `failed`.

## Check it worked

Open `https://www.bithuman.ai/embed/<agent_id>` in a browser and talk to it, or `bithuman run <agent_id>`.

## Variations

- **Write a better persona** with [the persona guide](https://docs.bithuman.ai/build/persona).
- **Add another model** later without re-creating the agent: [add a model](https://docs.bithuman.ai/api/agents#add-a-model-to-an-existing-agent).
- **Change the prompt** at any time: [update an agent](https://docs.bithuman.ai/api/agents#update-an-agent).

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| `402 INSUFFICIENT_BALANCE` | not enough credits | top up or choose a plan |
| `422 MODEL_SUBJECT_MISMATCH` | `essence-2` for a subject that is not a photoreal person | use `expression-2` or `auto` |
| `failed` with an image error | the image URL is not publicly fetchable | host the image publicly and create again (the failed creation is refunded) |
| The likeness is off | a side profile, several people or poor light | crop to one front-facing person in good light |
| The voice sounds noisy | background noise or music in the sample | re-record in a quiet room |

## Next

- [Agents API](https://docs.bithuman.ai/api/agents) · [Persona](https://docs.bithuman.ai/build/persona) · [Voices](https://docs.bithuman.ai/build/voices)

---

# Persona

URL: https://docs.bithuman.ai/build/persona

> Write the system prompt that gives an avatar its personality, with the CO-STAR framework and a worked example.

The persona is the avatar's system prompt: who it is, what it is for, and how it answers. Set it as `prompt` when you [create the agent](https://docs.bithuman.ai/build/create-avatar), or change it later by sending it as `system_prompt` ([update an agent](https://docs.bithuman.ai/api/agents#update-an-agent)):

```bash
curl -X POST https://api.bithuman.ai/v1/agent/<code> -H "Content-Type: application/json" \
  -H "api-secret: $BITHUMAN_API_SECRET" -d '{"system_prompt": "CONTEXT: ..."}'
```

## Before you start

- An agent, or one you are about to create.

## 1. Fill in the six fields

| Field | Defines | Weak → strong |
|---|---|---|
| **C**ontext | setting and situation | "customer service" → "second-level support for a cloud product, handling escalated cases" |
| **O**bjective | the goal | "be helpful" → "resolve the issue in the first conversation" |
| **S**tyle | how it communicates | "professional" → "like a patient in-store technician who uses analogies" |
| **T**one | emotional attitude | patient, empathetic, calm under frustration |
| **A**udience | who it talks to | "everyone" → "everyday users, beginner to intermediate" |
| **R**esponse | the shape of answers | "acknowledge → clarify → step by step → confirm → offer more" |

## 2. Write it as a prompt

```text
CONTEXT:   Online tutor helping high-school students with exam-season math.
OBJECTIVE: Explain concepts clearly, solve specific problems, build confidence.
STYLE:     Like an award-winning teacher: real-world examples, step by step.
TONE:      Encouraging and patient; mistakes are part of learning.
AUDIENCE:  Ages 14–18, mixed ability, some test anxiety.
RESPONSE:  Acknowledge, break into steps, encourage, use an analogy, close with confidence.
```

Keep spoken answers short: an avatar speaks every word, so two or three sentences per turn feel natural.

## Check it worked

Talk to the agent (`https://www.bithuman.ai/embed/<code>`) and ask three questions your users would ask. Adjust the field that produced the weakest answer.

## Troubleshooting

| Symptom | Fix |
|---|---|
| Answers are long and read like text | add "Answer in two or three spoken sentences" to RESPONSE |
| The tone swings between formal and casual | pick one tone; remove the conflicting words |
| Answers are generic | make CONTEXT and AUDIENCE specific |

## Next

- [Create your own avatar](https://docs.bithuman.ai/build/create-avatar) · [Knowledge](https://docs.bithuman.ai/api/knowledge) · [Voices](https://docs.bithuman.ai/build/voices)

---

# Voices

URL: https://docs.bithuman.ai/build/voices

> Every agent speaks every language on bitHuman's built-in voice pipeline, included in the voice chat rate — or bring your own OpenAI, Grok, ElevenLabs, or Cartesia key for premium voices.

## Two ways to give your agent a voice

| Option | What you get | Cost |
|------|--------------|------|
| **bitHuman default** | The built-in voice pipeline. Your agent detects the caller's language and replies in it. No setup, no keys. | Included in the voice chat rate ([pricing](https://docs.bithuman.ai/pricing)) |
| **Bring your own provider** | Connect your **own** OpenAI, Grok (xAI), ElevenLabs, or Cartesia key and pick that provider's premium voices — including low-latency speech-to-speech (realtime). | The same voice chat rate, plus your provider's charges on your key |

You never *have* to bring a key. The default pipeline already speaks every language. Bring your own only when you want a specific premium voice or a provider's realtime engine.

## Use the default (nothing to do)

Open any agent's voice settings at [bithuman.ai](https://www.bithuman.ai/explore). The **bitHuman voice** section is marked *Included* — design a voice, clone one, or pick from the gallery. It's multilingual automatically, so there's no language toggle to manage.

## Bring your own voice provider

### 1. Connect your key

Go to **Developer → Integrations**, add your provider, and paste that provider's key; bitHuman checks the key there before saving and rejects an invalid one. The [Providers API](https://docs.bithuman.ai/api/providers) stores a key as sent, without a check, so start one session to confirm it works. Keys are encrypted at rest and never leave the platform in plaintext.

### 2. Pick a premium voice

Back in the agent's voice settings, the premium providers you've connected unlock. Choose a voice; a provider you haven't connected stays locked with a shortcut to Integrations. Your selection runs that voice on your key.

## Supported providers

| Provider | Voices you can select | Realtime (speech-to-speech) |
|----------|-----------------------|:---------------------------:|
| **OpenAI** | Realtime voices (alloy, ash, ballad, cedar, …) | ✓ |
| **Grok (xAI)** | Grok voices (ara, eve, rex, …) | ✓ |
| **ElevenLabs** | Your ElevenLabs voice library | — |
| **Cartesia** | Cartesia voices | — |

> **Tip** Realtime providers (OpenAI, Grok) give the lowest-latency, most expressive speech-to-speech — great for kiosks and live demos. ElevenLabs and Cartesia give you a specific voice on the standard pipeline.

## How billing works

- Every managed-agent conversation bills the voice chat rate, whichever voice it uses ([pricing](https://docs.bithuman.ai/pricing)).
- A bring-your-own voice or realtime model is also billed by your provider on your key.

If a bring-your-own key ever fails or is removed, the agent automatically falls back to the built-in multilingual pipeline — it never silently stops talking.

---

# Gestures (Essence 1)

URL: https://docs.bithuman.ai/build/gestures

> Play a named gesture (wave, nod, clap) on an avatar exactly when your code asks, on a cloud avatar or a self-hosted one.

Gestures are named clips baked into an avatar, such as `mini_wave_hello` or `clap_cheer`. Your code plays one by name, when it chooses: on an app event, a timer, or an allow-listed tool call. Nothing plays at random.

Gestures are an Essence 1 feature; Essence 2 and Expression 2 avatars have no gesture clips.

## Before you start

- An Essence 1 agent of yours with gestures generated ([Gestures API](https://docs.bithuman.ai/api/dynamics)).
- A LiveKit agent worker with the bitHuman plugin ([LiveKit](https://docs.bithuman.ai/platforms/livekit)).

## 1. List the gesture names

```bash
curl -s https://api.bithuman.ai/v1/dynamics/$AGENT_CODE -H "api-secret: $BITHUMAN_API_SECRET"
# → {"success": true, "data": {"status": "ready", "gestures": {"mini_wave_hello": "…", "clap_cheer": "…"}}}
```

The keys of `gestures` are the names you play, for example `mini_wave_hello` or `clap_cheer`.

## 2. Play one

Cloud avatar (`AvatarSession(avatar_id=…)`): send the avatar participant a `trigger_dynamics` call.

```python
import json

resp = await ctx.room.local_participant.perform_rpc(
    destination_identity=avatar.avatar_identity,
    method="trigger_dynamics",
    payload=json.dumps({"action": "mini_wave_hello"}),
)
# → {"action": "mini_wave_hello", "animation_triggered": true, "status": "success"}
```

Self-hosted avatar (`AvatarSession(model_path="avatar.imx")`): push a `VideoControl` to the runtime.

```python
from bithuman import VideoControl

await avatar.runtime.push(VideoControl(action="mini_wave_hello"))
```

## 3. Wire it to your events

As an allow-listed tool, so the language model can ask for a gesture only from your set. This tool is for a self-hosted avatar (`AvatarSession(model_path=…)`). For a cloud avatar, put the `perform_rpc` call from step 2 in the tool body instead.

```python
from livekit.agents import function_tool, RunContext

ALLOWED = {"mini_wave_hello", "clap_cheer", "thumbs_up_pulse"}

@function_tool()
async def play_gesture(context: RunContext, gesture: str) -> str:
    if gesture not in ALLOWED:
        return f"Unknown gesture. Options: {sorted(ALLOWED)}"
    await avatar.runtime.push(VideoControl(action=gesture, force_action=True))
    return f"Played {gesture}"
```

Other triggers work the same way: a LiveKit data message, a participant event or a timer calls the same line.

## Check it worked

The cloud call returns `animation_triggered: true`; the avatar plays the clip, then returns to idle or speech.

## Variations

| `VideoControl` field | Effect |
|---|---|
| `force_action=True` | play even if another gesture is running |
| `stop_on_user_speech=True` | stop the gesture when the user starts talking |
| `stop_on_agent_speech=True` | stop the gesture when the agent starts talking |
| `target_video="<clip>"` | switch the idle loop to another base clip |

`avatar.runtime.interrupt()` stops a gesture at once.

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| `animation_triggered: false` | the name is not one of the avatar's gestures, or it has none | list the names (step 1); generate gestures with the [Gestures API](https://docs.bithuman.ai/api/dynamics) |
| Nothing plays on a self-hosted avatar | the `.imx` was downloaded before gestures were generated | download the model again after generation |

## Next

- [Gestures API](https://docs.bithuman.ai/api/dynamics) · [LiveKit](https://docs.bithuman.ai/platforms/livekit) · [Python](https://docs.bithuman.ai/platforms/python)

---

# Voice agent

URL: https://docs.bithuman.ai/build/voice-agent

> A voice avatar on your own computer: LiveKit runs locally, OpenAI Realtime listens and speaks on your own key, and the bitHuman avatar renders on your CPU. One CLI command, or a short Python agent.

Everything except the voice model runs on your computer. LiveKit is the stock `livekit-server`, OpenAI Realtime listens, thinks and speaks on your own `OPENAI_API_KEY`, and the bitHuman avatar renders on your CPU — no GPU needed.

The avatar name picks the model: `wise-pup` is Expression 2, `sofia-ramirez` is Essence 2, or pass your own agent code or avatar file. You need two secrets: your bitHuman API secret (both models refuse to render without it) and `OPENAI_API_KEY`.

*Diagram: A voice agent on your machine.* Your browser, a local livekit-server and the agent all run on your machine; the agent renders the avatar from the reply's voice, and the API secret stays in its process. The agent sends your speech to OpenAI Realtime with your key, and sends bitHuman a credential check and usage reports with no audio, video, images or conversation text.

Use [the CLI](#with-the-cli) for a talking avatar with no code, [Python](#with-python) for your own agent code, or the [Python voice conversation](#python-voice-conversation) for a desktop window with no LiveKit server.

## With the CLI

The CLI starts `livekit-server`, the voice agent and the avatar, then opens its page in your browser.

```bash
# macOS (Apple silicon): installs livekit-server too
brew install bithuman-product/bithuman/bithuman-cli
# Linux x86_64 or arm64: the download includes livekit-server
sudo apt install -y ffmpeg python3-venv            # Ubuntu/Debian; macOS gets both from brew
curl -fsSL https://install.bithuman.ai | sh

bithuman login                                   # opens your browser; in CI, export BITHUMAN_API_SECRET instead
export OPENAI_API_KEY="<your OpenAI key>"
bithuman run wise-pup                            # Expression 2; `bithuman run sofia-ramirez` for Essence 2
```

Expected output:

```text
      http://127.0.0.1:8088/WISEPUP
  Opening your browser… (Ctrl-C to stop.)
```

The first run downloads the avatar and sets up the voice agent, which takes a minute or two and needs Python 3.11 or newer. Allow the microphone and say "hi": the avatar answers, lip-synced, and stops when you talk over it. The voice settings are on [CLI](https://docs.bithuman.ai/platforms/cli#voice-settings).

## With Python

A plain [LiveKit Agents](https://docs.livekit.io/agents/) program: you run `livekit-server` (1.9.12 or newer; check with `livekit-server --version`), and the avatar renders inside `agent.py`. Use Python 3.10–3.14. The CLI checks its `livekit-server` version for you.

```bash
# 1. LiveKit server
brew install livekit python@3.13                  # macOS
curl -sSL https://get.livekit.io | bash           # Linux (Ubuntu 24.04 also: sudo apt install python3.12-venv)

# 2. The example
git clone https://github.com/bithuman-product/bithuman-examples
cd bithuman-examples/python/self-host
python3.13 -m venv .venv && . .venv/bin/activate  # Ubuntu 24.04: python3.12
pip install -r requirements.txt

# 3. Keys: in .env, never on the command line
cp .env.example .env                              # fill BITHUMAN_MASTER_SECRET and OPENAI_API_KEY

# 4. Run, in two terminals
livekit-server --dev                              # terminal 1
python agent.py dev                               # terminal 2
```

Expected output in terminal 2:

```text
Open in Chrome: http://localhost:8089/?liveKitUrl=ws%3A%2F%2Flocalhost%3A7880&token=…
```

Open that link, click **Start** and allow the microphone. The heart of `agent.py`:

```python
# excerpt: python/self-host/agent.py
@server.rtc_session()
async def entrypoint(ctx: JobContext):
    await ctx.connect(auto_subscribe=AutoSubscribe.AUDIO_ONLY)  # the agent listens; it never needs your camera
    session = AgentSession(llm=openai.realtime.RealtimeModel(
        model=os.getenv("BITHUMAN_REALTIME_MODEL", "gpt-realtime-2.1-mini"),
        voice=os.getenv("BITHUMAN_VOICE", "coral"),
        # reply 0.5 s after you stop (the plugin's default semantic VAD can wait ~4 s)
        turn_detection=ServerVad(type="server_vad", silence_duration_ms=500, create_response=True,
                                 interrupt_response=True)))
    # Local mode: the avatar renders in this process and publishes the lip-synced video AND audio.
    avatar = bithuman.AvatarSession(model_path=os.environ["BITHUMAN_MODEL_PATH"],
                                    api_secret=os.environ["BITHUMAN_MASTER_SECRET"])
    await avatar.start(session, room=ctx.room)
    await session.start(
        agent=Agent(instructions=os.getenv("BITHUMAN_INSTRUCTIONS", "You are a friendly assistant. Keep answers short.")),
        room=ctx.room, room_options=RoomOptions(audio_output=False, close_on_disconnect=False))
```

Swap the `RealtimeModel` for any LiveKit speech-to-text, LLM and text-to-speech plugins; the avatar lines stay the same.

## Python voice conversation

The same conversation in a desktop window, with no LiveKit server and no browser: your microphone goes to OpenAI Realtime, and the reply's voice drives a bitHuman avatar rendered on your machine.

### Requirements

- A bitHuman API secret ([Developer → API Secrets](https://www.bithuman.ai/developer/api-keys)) and an `OPENAI_API_KEY`.
- Python 3.10–3.14 in a virtualenv, a microphone and speakers.
- On Linux, the PortAudio library: `sudo apt install libportaudio2`.

### Get the code

```bash
git clone https://github.com/bithuman-product/bithuman-examples.git
cd bithuman-examples/python/quickstart
python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
bithuman pull sofia-ramirez 2>/dev/null || curl -fsSL --create-dirs -o ~/.cache/bithuman/showcase/sofia-ramirez.imx \
  "https://api.bithuman.ai/v1/agent/A52DHS2219/model/download?model=essence-2"
```

`sofia-ramirez` is a sample avatar (Essence 2, about 148 MB); downloading it needs no credential.

```bash
export BITHUMAN_API_SECRET="<your API secret>" OPENAI_API_KEY="<your OpenAI key>"
```

### Run it

```bash
python conversation.py --model ~/.cache/bithuman/showcase/sofia-ramirez.imx
```

Speak into your microphone; press `Q` in the window to quit.

A window opens with the avatar at rest. When you stop speaking, the avatar answers, lip-synced, and you hear the reply through your speakers.

### How it works

The pipeline: microphone → OpenAI Realtime (24 kHz PCM16) → `push_audio`/`flush` into the runtime → lip-synced frames and audio out. The heart of `conversation.py`:

```python
# excerpt: python/quickstart/conversation.py
async with client.realtime.connect(model="gpt-realtime-2.1-mini") as conn:
    await conn.session.update(session={
        "type": "realtime",
        "instructions": "You are a friendly AI assistant. Keep responses concise.",
        "output_modalities": ["audio"],
        "audio": {
            "input": {"format": {"type": "audio/pcm", "rate": OPENAI_SAMPLE_RATE},
                      "turn_detection": {"type": "server_vad"}},
            "output": {"format": {"type": "audio/pcm", "rate": OPENAI_SAMPLE_RATE},
                       "voice": args.voice},
        },
    })
# …
async for event in conn:
    if event.type == "response.output_audio.delta":
        await ai_audio_queue.put(base64.b64decode(event.delta))
    elif event.type == "response.output_audio.done":
        await ai_audio_queue.put(None)
# …
async def push_to_bithuman():
    while True:
        data = await ai_audio_queue.get()
        if data is None:
            await runtime.flush()
        else:
            await runtime.push_audio(data, OPENAI_SAMPLE_RATE, last_chunk=False)
# …
async for frame in runtime.run():
    if frame.has_image:
        cv2.imshow(WINDOW, frame.bgr_image)
        if cv2.waitKey(1) & 0xFF == ord("q"):
            break

    if frame.audio_chunk:
        with speaker_lock:
            speaker_buf.extend(frame.audio_chunk.array.tobytes())
```

- **Personality:** edit the `instructions` string.
- **Voice:** pass `--voice` with any OpenAI Realtime voice.
- **Another avatar:** `bithuman list` prints every sample slug; pass the file with `--model`.

## Barge-in

Talk over the avatar and it stops mid-sentence, then listens: that is barge-in.

- **The CLI and the Python agent:** the voice model's turn detection hears you start talking and cancels its reply; LiveKit Agents then clears the avatar's buffered audio and frames, so the mouth stops with the voice. In the Python agent it is `interrupt_response=True` on the turn detection, shown above.
- **Your own loop in Python:** when your speech detection fires, call `interrupt()` on the runtime and clear any reply audio you still hold. `run()` carries on with idle frames. With OpenAI Realtime, the event to watch is `input_audio_buffer.speech_started`:

```python
# excerpt: barge-in, in the event loop of conversation.py
elif event.type == "input_audio_buffer.speech_started":   # the user started talking
    runtime.interrupt()                                     # drop the rest of the reply
```

- **On the device:** `interrupt()` in Swift and Flutter; `resetState(true)` for Expression 2 and `resetAudio()` for Essence 2 on Android ([Companion app](https://docs.bithuman.ai/build/companion-app#let-the-user-interrupt)).
- **A cloud avatar without the plugin:** perform the RPC `lk.clear_buffer` on the avatar ([Cloud avatar](https://docs.bithuman.ai/api/cloud-avatar)).

Barge-in does not change billing: a session bills active session time, talking or idle, to the second.

## Pick the avatar

`bithuman run <value>`, or `BITHUMAN_AVATAR=<value>` in the Python example's `.env`:

| Value | You get |
|---|---|
| `wise-pup` | Expression 2, a sample avatar |
| `sofia-ramirez` | Essence 2, a sample avatar |
| your agent code, e.g. `A24EKJ8433` | your own avatar, downloaded with your API secret |
| a path to an avatar file | a file you already have |

## Configuration

The Python example reads these from `.env`:

| Variable | Default | What it does |
|---|---|---|
| `BITHUMAN_MASTER_SECRET` | — | Your API secret, passed to the plugin explicitly. Rendering is metered on it. In a LiveKit worker, name the secret `BITHUMAN_MASTER_SECRET`, never `BITHUMAN_API_SECRET`; `agent.py` refuses to start while `BITHUMAN_API_SECRET` is set. |
| `OPENAI_API_KEY` | — | Your OpenAI key. |
| `BITHUMAN_AVATAR` | `wise-pup` | Which avatar ([table above](#pick-the-avatar)). |
| `BITHUMAN_REALTIME_MODEL` | `gpt-realtime-2.1-mini` | The OpenAI Realtime model. |
| `BITHUMAN_VOICE` | `coral` | Any OpenAI Realtime voice. |
| `BITHUMAN_INSTRUCTIONS` | a short assistant prompt | The agent's system prompt. |
| `LIVEKIT_URL`, `LIVEKIT_API_KEY`, `LIVEKIT_API_SECRET` | `ws://localhost:7880`, `devkey`, `secret` | Your LiveKit server (`livekit-server --dev`). |

## What you pay

Session time, talking or idle, bills bitHuman credits; OpenAI bills your own key. See [Pricing](https://docs.bithuman.ai/pricing).

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| `bithuman run` exits 69: `livekit-server 1.8.0 at …/livekit-server is too old for `bithuman run`` | The CLI needs livekit-server 1.13 or newer | `brew upgrade livekit` (macOS), or reinstall the CLI (Linux: its download includes one) |
| The video stalls for 1–2 s every 15 s, or a LiveKit Meet tile goes black | `livekit-server` older than 1.9.12: the browser leaves and rejoins the room every 15 s | `brew upgrade livekit` (macOS) or `curl -sSL https://get.livekit.io \| bash` (Linux), then restart `livekit-server` |
| `livekit-server not found` (exit 69) | LiveKit is not installed | `brew install livekit` (macOS) or `curl -sSL https://get.livekit.io \| bash` (Linux) |
| The avatar never appears | No or invalid API secret | CLI: `bithuman login`. Python example: set `BITHUMAN_MASTER_SECRET` in `.env` |
| The avatar never appears; the terminal shows `essence-2: ffmpeg not found` | Essence 2 unpacks its avatar with `ffmpeg` | `sudo apt install -y ffmpeg`, then run again |
| The page says it could not connect | `livekit-server --dev` is not running | Start it, then click **Start** again |
| Nothing happens after joining | `livekit-server --dev` or `agent.py` is not running | Start both, `livekit-server` first |
| Another device on your network cannot join | `--dev` listens on `localhost` only | `livekit-server --dev --bind 0.0.0.0 --node-ip <your LAN IP>`; other browsers also need HTTPS for the microphone |
| On a Mac, your own page with no microphone, on the same machine as the avatar, fails with `could not establish pc connection` | Chrome hides the machine's local addresses until the page has microphone permission | call `navigator.mediaDevices.getUserMedia({ audio: true })` before connecting, or open the page from another device |
| `OSError: PortAudio library not found` | the system library is missing | `sudo apt install libportaudio2` (Debian, Ubuntu) |
| `cv2.error: … The function is not implemented` | the headless OpenCV build won the install | `pip install --force-reinstall --no-deps opencv-python` |
| `error: externally-managed-environment` | outside the virtualenv | `. .venv/bin/activate` |
| No microphone input on macOS | the terminal has no microphone permission | System Settings → Privacy & Security → Microphone |

---

# Website widget

URL: https://docs.bithuman.ai/build/website-widget

> Add a floating, talking avatar to any website with one script tag: the floating widget or the chat widget, every option, React and Next.js, and your own persona and model with no server.

## What you'll build

A talking avatar in the corner of your website. Visitors open it, allow the microphone and talk to it; it answers out loud with its lips in sync. One script tag adds it to any page, in any framework. There is no npm package and no server to run.

You need:

- a website you can add a `<script>` tag to, served over HTTPS (or `http://localhost` while you build);
- an agent code: `A23WJF0199` (the `wise-pup` sample) or your own agent's.

## Steps

### Pick the agent

Use the `wise-pup` sample (agent code `A23WJF0199`) while you build. For your own agent, keep **Anonymous Share** on in its sharing settings: the widgets open the agent's public link, and its sessions bill your account.

Expected:

`https://bithuman.ai/A23WJF0199` opens the avatar in a browser tab.

### Add the floating widget

Paste this before `</body>`:

```html
<script src="https://www.bithuman.ai/widgets/bithuman-gadget.js"></script>
<script>
  BitHumanGadget.init({
    agentUrl: "https://bithuman.ai/A23WJF0199?deployment=gadget",
    position: "bottom-right",
    buttonText: "Talk to us",
  });
</script>
```

Expected:

A button in the bottom-right corner. Select it: the avatar opens in a floating frame you can drag and resize, asks for the microphone, and answers when you speak.

### Or add the chat widget

The chat widget opens a side panel where visitors type, talk, or switch to video:

```html
<script src="https://www.bithuman.ai/widgets/bithuman-chat-widget.js"></script>
<script>
  BitHumanChat.init({
    agentUrl: "https://bithuman.ai/A23WJF0199",
    defaultChatMode: "text",
    welcomeMessage: "Hi! How can I help?",
  });
</script>
```

Expected:

A floating card in the corner. Opening it shows the panel with the welcome message; the mode switch moves between text, voice and video.

### Load it in React or Next.js

In Next.js, load the script with `next/script` and call `init` when it has loaded:

```tsx
"use client";
import Script from "next/script";

declare global {
  interface Window { BitHumanGadget?: { init: (options: Record<string, unknown>) => void } }
}

export function AvatarWidget({ code }: { code: string }) {
  return (
    <Script
      src="https://www.bithuman.ai/widgets/bithuman-gadget.js"
      strategy="afterInteractive"
      onLoad={() => window.BitHumanGadget?.init({ agentUrl: `https://bithuman.ai/${code}?deployment=gadget` })}
    />
  );
}
```

Render `<AvatarWidget code="A23WJF0199" />` once, in your root layout. In other React apps, add the two `<script>` tags to the page's HTML, or put the web embed in an `<iframe>` ([Web](https://docs.bithuman.ai/platforms/web#react-and-other-frameworks)).

Expected:

The widget's button appears on every page of the app. A second `init` call is ignored, so a re-render does not add a second widget.

### Give it your persona and model

The widget runs the agent's managed conversation, so the persona and the model are settings on the agent, not code on your page. Set the persona as the agent's `system_prompt` ([Persona](https://docs.bithuman.ai/build/persona)). To answer with your own model, connect any OpenAI-compatible endpoint with [Providers](https://docs.bithuman.ai/api/providers#openai-compatible-endpoints-self-hosted-proxies-gateways) and point the agent's `llm` at it.

Expected:

The next session answers in the new persona, with your model. Nothing on your page changed.

## How it works

*Diagram: bitHuman cloud.* In the bitHuman cloud the avatar renders on bitHuman's servers, in the US, and the conversation runs on bitHuman's voice service or with the provider keys you connect. The browser or app sends the microphone and shows the video. Your API secret stays on your server; browsers get scoped embed tokens.

The script adds a button to your page. Opening it loads the web embed for your agent in a frame. The avatar renders in the bitHuman cloud, in the US, and streams to the visitor. With the web embed, the conversation runs on bitHuman's servers, even when the avatar renders in the tab.

4 credits per minute of active session time for Essence 2 and Expression 2, about $0.04 a minute at the top-up rate of $1 = 100 credits. A managed agent's voice chat bills 10 credits per minute, all-inclusive: the avatar is part of it. Realtime usage bills active session time, talking or idle, to the second. Every rate: [Pricing and credits](https://docs.bithuman.ai/pricing).

## Make it your own

The embed dialog in the bitHuman app writes these options for you. `agentUrl` is required; the rest are optional.

**Floating widget** (`BitHumanGadget.init`):

| Option | Values |
|---|---|
| `agentUrl` | `https://bithuman.ai/<agent code>?deployment=gadget` |
| `theme` | `light` (default) or `dark` |
| `position` | `bottom-right` (default), `bottom-left`, `top-right`, `top-left`, `center` |
| `size` | the frame's starting size in pixels (default 200) |
| `transparent` | `true` removes a green-screen backdrop, so the avatar stands on your page |
| `keyColor`, `keySimilarity`, `keySmoothness`, `keySpill`, `keyErode` | fine-tune `transparent`: the key color, such as `00ff00` (default: sampled from the video), and the edge settings |
| `buttonStyle` | `pill` (default; image and text), `circle`, `square` |
| `buttonText` | the button label, for `pill` (default "Chat") |
| `imageUrl` | the button's image (default: the bitHuman logo) |
| `frameStyle` | `rounded` (default), `circular`, `portrait` (9:16) |
| `draggable`, `resizable` | `true` (default) or `false` |
| `minSize`, `maxSize` | size limits in pixels (defaults 50 and 400) |
| `margin` | distance from the screen edge in pixels (default 60) |
| `autoLoad` | `true` opens the avatar when the page loads (default `false`) |
| `greetingLanguage` | `auto` (default; from the page's `<html lang>`) or a code such as `es` |
| `greetingMessage` | the first thing the avatar says |

**Chat widget** (`BitHumanChat.init`):

| Option | Values |
|---|---|
| `agentUrl` | `https://bithuman.ai/<agent code>` |
| `theme` | `light` (default) or `dark` |
| `themeColor` | `blue` (default), `purple`, `green`, `red`, `orange`, `teal`, `pink`, `indigo` |
| `position` | `bottom-right` (default) or `bottom-left` |
| `fabStyle` | `preview` (default; a card with the avatar), `bar`, `circle` |
| `fabText`, `fabSubtext` | the button's label and the line under it |
| `fabSize` | the circle's diameter in pixels (default 60) |
| `imageUrl` | the image on the button (default: the bitHuman logo) |
| `attentionPulse` | `true` (default) pulses rings around the avatar |
| `topBanner`, `topBannerText`, `topBannerQuestions` | a banner across the top of the page, its headline and its question chips |
| `defaultChatMode` | `text` (default), `voice`, `video` |
| `allowModeSwitch` | `true` (default) lets visitors switch modes |
| `autoLoad` | `true` opens the panel when the page loads (default `false`) |
| `headerTitle` | the panel title (default: the agent's name) |
| `welcomeMessage` | the first message in the panel |
| `suggestedQuestions` | starter questions in the panel |
| `teaserEnabled`, `teaserMessage`, `teaserDelay`, `teaserAutoHide` | a bubble shown after a delay and hidden again, in milliseconds (default on, 2200, 12000) |
| `expandedWidth` | the panel's width on a desktop, in pixels (default 420) |
| `margin`, `zIndex` | distance from the edge in pixels (default 20), and stacking order (default 99999) |
| `greetingLanguage`, `greetingMessage` | as for the floating widget |

For a private agent, or your own layout, use the web embed in an `<iframe>` with an [embed token](https://docs.bithuman.ai/api/embedding) instead ([Web](https://docs.bithuman.ai/platforms/web)).

## Troubleshooting

| Symptom | Fix |
|---|---|
| Nothing appears, and the browser console says `agentUrl is required` | Pass `agentUrl` to `init`. |
| The microphone never activates | Serve the page over HTTPS, or `http://localhost` while you build. |
| The frame shows `Embedding is disabled for this agent` | Turn Anonymous Share back on in the agent's sharing settings. |
| The frame shows a browser error page | Remove the `Cross-Origin-Embedder-Policy` header from your page. |
| The console says the widget is already initialized | Call `init` once per page. |

---

# Companion app

URL: https://docs.bithuman.ai/build/companion-app

> An AI companion in your iPhone, iPad or Android app: a photoreal Essence 2 avatar that renders on the phone and speaks the replies your own voice stack produces.

## What you'll build

A companion screen in your own app: an avatar that idles while the user talks, then speaks your app's reply with its lips in sync. The avatar renders on the phone; your app keeps its own speech recognition, language model and voice.

You need:

- Xcode 26 and a physical iPhone or iPad, or Android Studio and a physical arm64 Android phone;
- an [API secret](https://docs.bithuman.ai/start/api-secret) on the Creator plan or higher;
- the speech recognition, language model and voice your app already uses.

*Capture: The sofia-ramirez avatar speaking in the essence2-hello app on a Galaxy S25+, at 1080×1920. Captured on Samsung Galaxy S25+ (Android) · essence2-android 0.5.14 · sofia-ramirez (Essence 2) · 2026-09-23.* (https://docs.bithuman.ai/examples/android-essence-2/clip.mp4)

## Steps

The code in each step is from two example apps that bithuman-examples builds in CI: [iOS Essence 2](https://docs.bithuman.ai/examples/ios-essence-2) (Swift) and [Android Essence 2](https://docs.bithuman.ai/examples/android-essence-2) (Kotlin); the resample converter is one you add to your app. Expression 2, for a character instead of a person, has the same shape.

### Pick the avatar

Use the `sofia-ramirez` sample (agent code `A52DHS2219`) while you build, or [create your own](https://docs.bithuman.ai/build/create-avatar) from one portrait.

Expected:

An agent code for an Essence 2 avatar.

### Add the SDK

- **iPhone and iPad:** the Swift package, product `Essence2Kit` ([install](https://docs.bithuman.ai/platforms/ios#install)).
- **Android:** the Android SDK, `essence2-android` ([install](https://docs.bithuman.ai/platforms/android#install)).

Expected:

Your app builds with `import Essence2Kit`, or with `ai.bithuman.essence2` on the classpath.

### Set your API secret

One call covers the avatar's download and the session. Set it before anything downloads:

```swift tab="Swift"
// excerpt: swift/ios-essence2/Sources/App.swift
Essence2Credential.set(ProcessInfo.processInfo.environment["BITHUMAN_API_SECRET"])
```

```kotlin tab="Kotlin"
// excerpt: android/essence2-hello/app/src/main/java/com/example/e2hello/MainActivity.kt
// 1. The CREDENTIAL, once, before anything downloads or opens an engine.
//    One setter covers the store's download and the engine's meter;
//    create() refuses without it.
Essence2Credential.set(secret)
```

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/pricing#check-your-balance), and rotate the secret at once if usage looks wrong.

Expected:

No refusal when the avatar opens in the next step. Without a secret, opening it fails and says why.

### Open the avatar

```swift tab="Swift"
// excerpt: swift/ios-essence2/Sources/App.swift
let e = try await Essence2Engine.create(identity: imx, resourcesDirectory: Payload.resources)
```

```kotlin tab="Kotlin"
// excerpt: android/essence2-hello/app/src/main/java/com/example/e2hello/MainActivity.kt
// 2. The STORE downloads with the credential set above.
//    Blocks on the network the first time; that is why this is a worker thread.
val store = Essence2ModelStore(this)
val identity = store.fetch(agentCode, progress = { member, done, total ->
    if (done == total) Log.i(TAG, "fetched $member ($total B)")
})
// …
Essence2Avatar.create(identity.dir).use { avatar ->
```

Expected:

The first run downloads the avatar once, then it stays on the device. The avatar shows idle motion before it says anything.

### Resample speech to 16 kHz

The engines take 16 kHz mono speech. A voice service that returns another rate needs one conversion first: OpenAI Realtime, for example, returns 24 kHz 16-bit PCM. Keep one converter for the whole reply and pass each chunk through it before you feed the avatar:

```swift tab="Swift"
// Add to your app: 24 kHz 16-bit mono PCM in, the 16 kHz [Float] that feed(_:) takes out.
import AVFoundation

final class To16k {
    private let from = AVAudioFormat(commonFormat: .pcmFormatInt16, sampleRate: 24_000, channels: 1, interleaved: false)!
    private let to = AVAudioFormat(commonFormat: .pcmFormatFloat32, sampleRate: 16_000, channels: 1, interleaved: false)!
    private lazy var converter = AVAudioConverter(from: from, to: to)!

    func convert(_ pcm24k: Data) -> [Float] {
        let n = AVAudioFrameCount(pcm24k.count / 2)
        guard n > 0, let input = AVAudioPCMBuffer(pcmFormat: from, frameCapacity: n),
              let output = AVAudioPCMBuffer(pcmFormat: to, frameCapacity: n) else { return [] }
        input.frameLength = n
        pcm24k.withUnsafeBytes { input.int16ChannelData![0].update(from: $0.bindMemory(to: Int16.self).baseAddress!, count: Int(n)) }
        var given = false
        _ = converter.convert(to: output, error: nil) { _, status in
            if given { status.pointee = .noDataNow; return nil }
            given = true
            status.pointee = .haveData
            return input
        }
        return Array(UnsafeBufferPointer(start: output.floatChannelData![0], count: Int(output.frameLength)))
    }
}
```

```kotlin tab="Kotlin"
// Add to your app: 24 kHz 16-bit mono PCM in; floats() for Expression 2, pcm16() for Essence 2.
import java.nio.ByteBuffer
import java.nio.ByteOrder

class To16k {
    private var rest = FloatArray(0)   // input not used yet
    private var pos = 0.0              // read position in the input, in samples

    fun floats(pcm24k: ByteArray): FloatArray {
        val s = ByteBuffer.wrap(pcm24k).order(ByteOrder.LITTLE_ENDIAN).asShortBuffer()
        val input = rest + FloatArray(s.remaining()) { s.get() / 32768f }
        val out = ArrayList<Float>()
        while (pos + 1 < input.size) {
            val i = pos.toInt()
            val f = (pos - i).toFloat()
            out.add(input[i] * (1 - f) + input[i + 1] * f)
            pos += 1.5                   // 24 000 / 16 000
        }
        rest = input.copyOfRange(pos.toInt(), input.size)
        pos -= pos.toInt()
        return out.toFloatArray()
    }

    fun pcm16(pcm24k: ByteArray): ByteArray {
        val f = floats(pcm24k)
        val b = ByteBuffer.allocate(f.size * 2).order(ByteOrder.LITTLE_ENDIAN)
        for (x in f) b.putShort((x.coerceIn(-1f, 1f) * 32767).toInt().toShort())
        return b.array()
    }
}
```

Expected:

Each 24 kHz chunk comes out as two thirds as many 16 kHz samples, and the lips keep pace with the voice. Speech fed at the wrong rate makes the mouth run slow and long.

### Speak a reply

Your speech recognition hears the user, your language model writes the reply, and your voice turns it into audio. Feed that audio as 16 kHz mono, say where the reply ends, and draw the frames the avatar hands back:

```swift tab="Swift"
// excerpt: swift/ios-essence2/Sources/App.swift
private func startLoop(_ e: Essence2Engine) {
    loop?.cancel()
    let frames = e.frames(following: player)
    loop = Task { [weak self] in
        for await f in frames {
            guard let self else { return }
            if f.audioTime == 0, let r = self.reply {
                self.player.stop()
                self.player.scheduleBuffer(r)
                self.player.play()
            }
            if let cg = makeCGImage(bgr: f.bgr, f.width, f.height) {
                self.sink.show(cg)
                self.hasFrame = true
            }
    // …
    e.feed(samples)
    e.flushTail()
```

```kotlin tab="Kotlin"
// excerpt: android/essence2-hello/app/src/main/java/com/example/e2hello/MainActivity.kt
Essence2Avatar.create(identity.dir).use { avatar ->
    // …
    val frame = avatar.newFrameBuffer()   // direct, width * height * 4, RGBA
    // …
    avatar.feed(pcm)                      // 16-bit little-endian PCM bytes, as read
    avatar.endOfAudio()                   // "that is the whole utterance"
    // …
    var quietMs = 0
    while (quietMs < 5_000) {             // 5 s with no frame at all = finished
        frame.clear()
        if (avatar.pull(frame)) {         // true = a frame was written
            quietMs = 0
            frame.rewind()
```

Expected:

The lips follow the reply's audio from its first word, and idle motion returns when the reply ends.

### Let the user interrupt

When your speech recognition hears the user start talking over the avatar, stop your audio player and drop the rest of the reply: `interrupt()` in Swift, `resetAudio()` in Kotlin. Idle motion continues from the current frame. The full list of calls is under *Integrate into your app* on [iOS & iPadOS](https://docs.bithuman.ai/platforms/ios#integrate-into-your-app) and [Android](https://docs.bithuman.ai/platforms/android#integrate-into-your-app).

Expected:

The mouth stops with the voice, and the next reply starts cleanly.

### Close the avatar with the screen

A session bills active session time, talking or idle, for as long as the avatar is open, so a companion left on screen keeps billing.

- When the app moves to the background, shut the avatar down: `shutdown()` in Swift, `close()` in Kotlin. Create it again when the app returns; the avatar file stays on the device, so nothing downloads again.
- When nobody has spoken for a while, show a still frame and close the avatar.
- When the app quits, call `Essence2Engine.quiesceAll()` in Swift, from `applicationWillTerminate`.

Expected:

The avatar closes while the app is in the background, and comes back without a new download when the user returns.

### Run it on a phone

Build to a physical iPhone or iPad (iOS 26), or to a physical arm64 Android phone. The iOS Simulator and Android emulators cannot run the engine.

Expected:

The companion idles, answers and can be interrupted, rendered on the phone.

## How it works

*Diagram: On the device.* On the device, your app renders the avatar on the iPhone, iPad, Mac or Android phone and brings its own voice and language services. The avatar model downloads once. When you use your own voice and language services, bitHuman receives usage metering only, never audio, video or conversation text.

The avatar renders inside your app, from 16 kHz mono speech to picture frames. When you use your own voice and language services, bitHuman receives usage metering only, never audio, video or conversation text. A session checks your API secret when it starts and keeps rendering through a network drop of up to 5 minutes.

## Make it your own

- **A character instead of a person:** Expression 2 renders any character from one portrait, with the same calls ([iOS & iPadOS](https://docs.bithuman.ai/platforms/ios), [Android](https://docs.bithuman.ai/platforms/android)).
- **One codebase:** the [Flutter plugin](https://docs.bithuman.ai/platforms/flutter) wraps both engines.
- **Its personality:** it lives in your language model's prompt. The avatar only renders the speech it is given.
- **The conversation on bitHuman's servers instead:** the [web embed](https://docs.bithuman.ai/platforms/web) runs a managed agent with your persona (`system_prompt`) and, through [Providers](https://docs.bithuman.ai/api/providers#openai-compatible-endpoints-self-hosted-proxies-gateways), your own OpenAI-compatible model. A [LiveKit](https://docs.bithuman.ai/platforms/livekit) agent can use a bitHuman cloud avatar. Both render in the cloud (the web embed can also render in the tab); their rates are on [Pricing](https://docs.bithuman.ai/pricing).

What it costs on the device:

2 credits per minute of active session time for Essence 2 and Expression 2, about $0.02 a minute at the top-up rate of $1 = 100 credits. Realtime usage bills active session time, talking or idle, to the second. Every rate: [Pricing and credits](https://docs.bithuman.ai/pricing).

One user whose sessions add up to 20 minutes a day on the device uses about 1,200 credits a month ($12.00 at the top-up rate).

## Troubleshooting

| Symptom | Fix |
|---|---|
| Opening the avatar fails with a metering refusal | Set the API secret before the download and the first `create`, on the Creator plan or higher. |
| It works on a phone but not in the Simulator or an emulator | Expected: the engine needs a physical device. |
| The lips run ahead of the voice | Start the reply's audio with its first speech frame (`audioTime == 0` in Swift), not when you feed it. |
| The reply is cut short | Mark the end of each reply once: `flushTail()` in Swift, `endOfAudio()` in Kotlin. |
| The mouth runs slow and the reply lasts too long | The speech is not 16 kHz: [resample it](#resample-speech-to-16-khz) before you feed it. |
| The first start is slow | The first run downloads the avatar; later starts open it from the device. |

---

# Kiosk on a Linux PC

URL: https://docs.bithuman.ai/build/kiosk

> A live avatar full screen on a standard Linux PC with no GPU: the CLI renders it on the CPU, Chrome shows it in kiosk mode, and visitors talk to it.

## What you'll build

A screen that greets visitors with a live avatar that listens and answers. The avatar renders on the PC's CPU, so a standard Linux PC with no GPU is enough.

You need:

- a Linux PC (x86_64 or arm64) with a screen, speakers and a microphone;
- Google Chrome;
- an [API secret](https://docs.bithuman.ai/start/api-secret) on the Creator plan or higher.

*Capture: The kwame-warm-museum-guide avatar answering a visitor, full screen in Chrome on a Linux PC, from bithuman run. Captured on a Linux PC, Intel Core i7-13700F (Ubuntu 24.04) · CLI 2.8.2 (bithuman run) · kwame-warm-museum-guide (Essence 2) · 2026-09-27. Rendered on the CPU alone: the PC's graphics card was hidden from the process. The visitor's question is the microphone input, mixed into the recording.* (https://docs.bithuman.ai/examples/kiosk-linux/clip.mp4)

## Steps

### Install the CLI

```bash
curl -fsSL https://install.bithuman.ai | sh
sudo apt install -y ffmpeg python3-venv     # Ubuntu/Debian
```

The Linux download includes `livekit-server`, which `bithuman run` starts for you.

Expected:

`bithuman --version` prints the CLI and engine versions.

### Give the kiosk its own API secret

Create a secret for this kiosk alone, so you can revoke it without touching anything else ([API secrets](https://www.bithuman.ai/developer/api-keys)). Put it in the kiosk's environment:

```bash
export BITHUMAN_API_SECRET="<this kiosk's API secret>"
```

Expected:

`bithuman account` shows your plan and credit balance.

### Download the avatar

Download it once, ahead of the first visitor. `bithuman pull` prints the file's path:

```bash
AVATAR=$(bithuman pull kwame-warm-museum-guide)    # or your own agent code
echo "$AVATAR"
```

A file always renders on this machine. Any Essence 2 or Expression 2 avatar works on the CPU.

Expected:

A path ending in `kwame-warm-museum-guide.imx`. The next runs reuse it.

### Start the avatar

```bash
bithuman run "$AVATAR"
```

The first run also installs the conversation brain (about 350 MB). By default the conversation runs on bitHuman's voice chat; set `OPENAI_API_KEY` to use your own OpenAI account, or `BITHUMAN_LOCAL=1` for the [local conversation brain](https://docs.bithuman.ai/platforms/cli/local-brain).

Expected:

The CLI prints the page's URL, such as `http://127.0.0.1:8088/KWAMEWARMMUSEUMGUIDE`. Open it in a browser, press the start button and allow the microphone: the avatar answers when you speak.

### Show it full screen

Open the URL in Chrome's kiosk mode, with a profile of its own so the microphone permission is remembered:

```bash
google-chrome --kiosk --user-data-dir="$HOME/.kiosk-chrome" "http://127.0.0.1:8088/KWAMEWARMMUSEUMGUIDE"
```

Expected:

The avatar fills the screen with no browser chrome. The first time, allow the microphone once; `Alt+F4` leaves kiosk mode.

### Choose online or fully offline

A session checks your API secret when it starts and keeps rendering through a network drop of up to 5 minutes, so this kiosk needs the network to start a conversation.

For a site with no internet at all: 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 PCs and terminals; arranged through sales. See [Fully offline](https://docs.bithuman.ai/deploy/offline).

Expected:

Online, the kiosk is ready: it needs the network each time a session starts. For fully offline, talk to [sales](https://www.bithuman.ai/sales) before you deploy.

## How it works

*Diagram: CPU only (no GPU).* On a standard Linux PC with no GPU, both models render live on the CPU, and the avatar's audio and video stay on the PC. The conversation runs where you choose: the CLI's local conversation brain, your own services, or bitHuman's. For the rendering, bitHuman receives a credential check, the avatar download and usage reports with no audio, video, images or conversation text.

`bithuman run` starts a local `livekit-server`, the conversation brain and the avatar on this PC. Chrome joins as the visitor: it sends the microphone and shows the avatar's video, all on `127.0.0.1`. The page is served on the loopback address only; `--host 0.0.0.0` (with `BITHUMAN_ALLOW_PUBLIC_BIND=1`) opens it to the network.

## Make it your own

- **Your avatar:** create one from a portrait ([Create your own avatar](https://docs.bithuman.ai/build/create-avatar)), then `bithuman pull <agent code>`.
- **Its persona and voice:** [Persona](https://docs.bithuman.ai/build/persona) and [Voices](https://docs.bithuman.ai/build/voices).
- **Start at boot:** run `bithuman run "$AVATAR"` from a service with `BITHUMAN_API_SECRET` in its environment, and start the kiosk browser from the desktop session's autostart.
- **What it costs:** active session time, talking or idle, billed to the second at the rates on [Pricing](https://docs.bithuman.ai/pricing). The conversation's rate depends on the brain you choose.
- **Speed on your PC:** the CPU-only rows on [Performance](https://docs.bithuman.ai/performance) are measured on a standard desktop CPU.

## Troubleshooting

| Symptom | Fix |
|---|---|
| `bithuman` exits with code 77 | No API secret: export `BITHUMAN_API_SECRET`, or run `bithuman login` once. |
| `livekit-server` is not found | Install again with the one-line installer; the Linux download includes it. |
| The avatar does not answer | Run `bithuman doctor`: it names the missing part (credential, brain, `ffmpeg`). |
| Chrome asks for the microphone every time | Keep the same `--user-data-dir`; the permission is stored in that profile. |
| No sound in kiosk mode | Choose the speaker as the default output in the system's sound settings, then reload the page. |
| The picture stutters | Close other heavy programs; see the CPU-only rows on [Performance](https://docs.bithuman.ai/performance) for the reference machine. |

---

# Talking video

URL: https://docs.bithuman.ai/build/talking-video

> Turn one audio file into an MP4 of your avatar speaking it: with the CLI or Python on your own machine, CPU only on Linux, or with one REST call to the bitHuman cloud.

## What you'll build

An MP4 of an avatar saying the words in an audio file, with the lips in sync. Nobody watches it live, so it suits greetings, lessons and product videos.

You need:

- an audio file of speech, or a script for the REST API;
- an [API secret](https://docs.bithuman.ai/start/api-secret) on the Creator plan or higher;
- for the CLI or Python: Linux (x86_64 or arm64) or a Mac with Apple silicon, and `ffmpeg`.

*Capture: The kwame-warm-museum-guide avatar in a talking video, rendered from one audio file by bithuman render on a Linux PC. Captured on a Linux PC, Intel Core i7-13700F (Ubuntu 24.04) · CLI 2.8.2 (bithuman render) · kwame-warm-museum-guide (Essence 2) · 2026-09-27. Rendered on the CPU alone: the PC's graphics card was hidden from the process.* (https://docs.bithuman.ai/examples/talking-video-linux/clip.mp4)

## Steps

### Get the speech

Any audio file `ffmpeg` reads works on your machine; the REST API takes a file at a public URL, or text in the agent's voice. This sample is 15 seconds of speech:

```bash
curl -fsSLo speech.wav https://docs.bithuman.ai/samples/speech.wav
```

Expected:

`speech.wav` in the current directory.

### Render the video

Pick where it renders. The CLI and Python render on your own machine, and on Linux they need no GPU. The REST API renders in the bitHuman cloud.

```bash tab="CLI"
curl -fsSL https://install.bithuman.ai | sh
export BITHUMAN_API_SECRET="<your API secret>"
bithuman render kwame-warm-museum-guide speech.wav -o kwame.mp4
```

```python tab="Python"
# Needs the bithuman package, ffmpeg on PATH and BITHUMAN_API_SECRET in the environment.
# The avatar file comes from `bithuman pull sofia-ramirez`, or the download URL on /platforms/python.
import bithuman
frames = bithuman.open("sofia-ramirez.imx").render("speech.wav", out_mp4="out.mp4")
print(frames, "frames written")
```

```bash tab="REST"
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.wav"}, "wait": true}'
```

Expected:

An MP4 as long as the speech: `kwame.mp4`, or `out.mp4` with the number of frames written, on your machine; or a `video_url` in the REST response (`"status": "completed"`). A render that takes longer than the wait returns a `job_id` to [poll](https://docs.bithuman.ai/api/video#get-talking-video-status).

### Check the file

```bash
ffprobe -v error -show_entries stream=width,height -show_entries format=duration -of compact kwame.mp4
```

Expected:

An Essence 2 video is up to 1080×1920 or 1920×1080, following the portrait; an Expression 2 video is 416×720. The duration matches the speech, and the file has one video and one audio track.

## How it works

*Diagram: The engine: speech in, frames out.* Your app pushes 16 kHz mono speech into the bitHuman engine and pulls lip-synced frames out. The same engine sits inside the Swift package, the Android SDK, the Python SDK, the CLI and the web embed.

The same engine renders a live conversation and a file: speech goes in and lip-synced frames come out, then `ffmpeg` writes them with the audio into an MP4. A file rendered on your machine keeps its audio and video there; the CLI and Python sign in online when the render starts. Through the REST API, the render runs in the bitHuman cloud, in the US.

## Make it your own

- **Your avatar:** [create one](https://docs.bithuman.ai/build/create-avatar) from a portrait, then pass its agent code to `bithuman render`, or to the REST call as `agent_code`.
- **Text instead of audio:** the REST API speaks a script in the agent's voice: `"input": {"type": "text", "text": "…"}` ([Talking video API](https://docs.bithuman.ai/api/video#text-input)).
- **A batch:** loop over files with `bithuman render`; every run reuses the downloaded avatar.
- **What it costs:** on your machine, file rendering bills the length of the video it writes at the self-hosted rate; the REST API bills per minute of output, rounded up ([Pricing](https://docs.bithuman.ai/pricing#talking-video--per-minute-of-output)).

## Troubleshooting

| Symptom | Fix |
|---|---|
| `bithuman render` exits with code 77 | No API secret: export `BITHUMAN_API_SECRET`, or run `bithuman login` once. |
| The render is refused before it starts | Set `BITHUMAN_API_SECRET` for an account on the Creator plan or higher, then render again. |
| `402 INSUFFICIENT_BALANCE` from the REST API | Your balance must cover the longest render up front; the difference is refunded when it finishes ([Talking video API](https://docs.bithuman.ai/api/video)). |
| `409 MODEL_NOT_GENERATED` | The agent has no model of that kind yet: check its `supported_models`, or [add the model](https://docs.bithuman.ai/api/agents#add-a-model-to-an-existing-agent). |

---

# Claude & Cursor (MCP)

URL: https://docs.bithuman.ai/build/mcp

> Let Claude, Cursor and other MCP clients drive bitHuman as tools: create agents, speak, embed, render. The server is built into the CLI (bithuman mcp).

`bithuman mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server built into the [CLI](https://docs.bithuman.ai/platforms/cli). An MCP client such as Claude Code, Claude Desktop or Cursor can then call bitHuman as tools: "make an avatar that explains our pricing, then give me an embed token" becomes a chain of tool calls.

| Detail | Expression 2 | Essence 2 |
|---|---|---|
| **Create agents** | `generate_agent` with `model: "expression-2"` | `generate_agent` with `model: "essence-2"` |
| **Render locally** | `render` tool | `render` tool |

## Before you start

- The [CLI](https://docs.bithuman.ai/platforms/cli#install) on macOS (Apple silicon) or Linux. On Windows or in a hosted agent, call the [REST API](https://docs.bithuman.ai/api) directly.
- An MCP client.

## Install

The server is the CLI; there is nothing else to install.

```bash
curl -fsSL https://install.bithuman.ai | sh
bithuman mcp tools      # prints the tool list and exits
```

## Authenticate

Run `bithuman login` once, or set `BITHUMAN_API_SECRET` in the client's configuration. The server reads the same credential as the CLI and never logs it.

## First frame

Register the server with your client.

Claude Code:

```bash
claude mcp add bithuman -- bithuman mcp
```

Claude Desktop, Cursor (`~/.cursor/mcp.json`) and other clients:

```json
{"mcpServers": {"bithuman": {"command": "bithuman", "args": ["mcp"]}}}
```

If you have not run `bithuman login`, add `"env": {"BITHUMAN_API_SECRET": "<your API secret>"}` to that entry.

Then ask: *"Use the bithuman tools to validate my API secret."* The client calls `validate_api_secret` and reports `{"valid": true}`.

## Integrate into your app

Ask in plain language; the client chooses and chains the tools.

| Ask | Tools it calls |
|---|---|
| "Create an Expression 2 avatar from this image, wait until it is ready, and give me an embed token." | `generate_agent`, `get_agent_status`, `create_embed_token` |
| "List the female voices and read this with F1." | `list_voices`, `text_to_speech` |
| "What is my credit balance, and what did I spend this week?" | `get_credit_balance`, `get_usage` |
| "Register a webhook at https://example.com/hooks and send it a test event." | `create_webhook`, `test_webhook` |
| "Download wise-pup and render this WAV to an MP4." | `pull`, `render` |

### Tools

| Tool | What it does |
|---|---|
| `version`, `doctor` | CLI version and install health (local) |
| `inspect_model`, `list_showcase`, `pull`, `render` | Inspect, list, download and render avatars on this machine (local) |
| `validate_api_secret` | Check the API secret (free) |
| `get_platform_status` | Service status from status.bithuman.ai |
| `get_credit_balance`, `get_usage` | Balance, plan and usage history |
| `list_voices`, `text_to_speech` | Voices, and speech saved as a WAV (free) |
| `generate_agent`, `get_agent_status` | Create an agent from an image (spends credits; always pass `model`), then poll until `ready` or `failed` |
| `get_agent`, `list_agents`, `update_agent_prompt`, `delete_agent` | Manage your agents |
| `agent_speak`, `add_agent_context` | Make a live agent speak, or give it background knowledge |
| `get_dynamics`, `generate_dynamics` | List or create gestures (spends credits) |
| `create_embed_token` | A one-hour token to embed an agent on a website |
| `upload_file` | Upload an asset and get a URL |
| `create_webhook`, `list_webhooks`, `delete_webhook`, `test_webhook` | Webhooks |

Talking video, adding a model to an agent and knowledge bases have no tool; use the [REST API](https://docs.bithuman.ai/api).

## Platform notes

- Agent creation is asynchronous: a second-generation agent takes about 2–2.5 hours. Prices are on [pricing](https://docs.bithuman.ai/pricing).
- Errors come back as structured objects with the HTTP status and a link to [Errors](https://docs.bithuman.ai/api/errors).

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| No bithuman tools in the client | `bithuman` is not on the client's `PATH` | use the full path to the binary in the config, then restart the client |
| `validate_api_secret` returns `valid: false` | no or wrong credential | `bithuman login`, or set `BITHUMAN_API_SECRET` in the config |
| A created agent uses a first-generation model | `model` was not passed | ask for `essence-2` or `expression-2` explicitly |
| `422` when creating an Essence 2 agent | the image is not a photoreal person | use a photo, or choose Expression 2 |

## Reference

- [CLI reference](https://docs.bithuman.ai/platforms/cli/reference#mcp-server)
- [REST API](https://docs.bithuman.ai/api) and the [OpenAPI spec](https://docs.bithuman.ai/api/openapi.yaml)
- [For AI agents](https://docs.bithuman.ai/resources/agents)

---

# Troubleshooting

URL: https://docs.bithuman.ai/resources/troubleshooting

> Where to fix a problem on each platform and recipe, what a working live session looks like, and the fixes for the common session errors.

Every platform and recipe page ends with a Troubleshooting table for its own problems; this page links them all, then covers the live session itself.

## By platform

| Platform | Its Troubleshooting table |
|---|---|
| iOS & iPadOS | [Swift package on iPhone and iPad](https://docs.bithuman.ai/platforms/ios#troubleshooting) |
| macOS | [Swift package on the Mac](https://docs.bithuman.ai/platforms/macos#troubleshooting) |
| Android | [Android SDK](https://docs.bithuman.ai/platforms/android#troubleshooting) |
| Flutter | [Flutter plugin](https://docs.bithuman.ai/platforms/flutter#troubleshooting) |
| Web | [Web embed](https://docs.bithuman.ai/platforms/web#troubleshooting) |
| Python | [Python SDK](https://docs.bithuman.ai/platforms/python#troubleshooting) |
| CLI | [CLI](https://docs.bithuman.ai/platforms/cli#troubleshooting) |
| LiveKit | [LiveKit plugin](https://docs.bithuman.ai/platforms/livekit#troubleshooting) |
| REST API | [REST](https://docs.bithuman.ai/platforms/rest#troubleshooting) · every error code: [Errors](https://docs.bithuman.ai/api/errors) |

## By task

| Task | Its Troubleshooting table |
|---|---|
| Create an avatar | [Create an avatar](https://docs.bithuman.ai/build/create-avatar#troubleshooting) · creation errors: [Agents API](https://docs.bithuman.ai/api/agents#errors) |
| A voice agent | [Voice agent](https://docs.bithuman.ai/build/voice-agent#troubleshooting) |
| A companion app | [Companion app](https://docs.bithuman.ai/build/companion-app#troubleshooting) |
| A kiosk | [Kiosk](https://docs.bithuman.ai/build/kiosk#troubleshooting) |
| A talking video | [Talking video](https://docs.bithuman.ai/build/talking-video#troubleshooting) |
| Persona and gestures | [Persona](https://docs.bithuman.ai/build/persona#troubleshooting) · [Gestures](https://docs.bithuman.ai/build/gestures#troubleshooting) |
| Claude, Cursor and other MCP clients | [MCP server](https://docs.bithuman.ai/build/mcp#troubleshooting) |

## Before you start

- An agent whose status is `ready` ([poll status](https://docs.bithuman.ai/api/agents#poll-status)).

## 1. Connect

| Situation | Expect |
|---|---|
| A session on an agent that has served recently | the avatar appears in a few seconds |
| The first session on a new agent, or at a busy time | up to tens of seconds while capacity starts; later sessions are fast |

If sessions keep failing to connect, check [status.bithuman.ai](https://status.bithuman.ai).

## 2. Idle and speaking

During silence the avatar keeps moving: Expression 2 plays its idle clip and Essence 2 its identity video, both looping smoothly. When speech starts, the lips follow the audio; on Expression 2, the idle motion covers the start of each reply. A running session bills whether the avatar is talking or idle ([pricing](https://docs.bithuman.ai/pricing)); end sessions you are not using.

## Check it worked

The avatar appears, moves while idle, and its lips follow the agent's speech. Frozen frames or motion that looks reversed are faults: report them with the agent code and the time.

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| The agent will not launch right after creation | it is not `ready` yet, or its model is still being prepared for serving | poll until `ready`; retry the first session after a short wait |
| `409 MODEL_NOT_GENERATED` | the session asked for a model the agent does not have | check `supported_models`; [add the model](https://docs.bithuman.ai/api/agents#add-a-model-to-an-existing-agent) |
| The session ends at once with `avatar_error: "model_not_generated"` | a `?model=` in the URL named a model the agent does not have | remove `?model=`, or add the model |
| `404` on `/speak` or `/add-context` | the agent has no live session | start a session first |
| No microphone prompt in an embed | the iframe lacks `allow="microphone *"` | add it ([Web](https://docs.bithuman.ai/platforms/web)) |
| In a room with several agents, the avatar stays silent for one | the avatar follows the agent that called `AvatarSession.start()` | start the avatar from the agent it should speak for |
| Creation stays at `lip_sync` for a long time | that is the training step for Essence 2 and Expression 2 (about 2–2.5 hours) | keep polling |

Creation errors and their fixes are on [Agents](https://docs.bithuman.ai/api/agents#errors).

## Next

- [Models](https://docs.bithuman.ai/models) · [Agents API](https://docs.bithuman.ai/api/agents) · [Errors](https://docs.bithuman.ai/api/errors)