# bitHuman — Build: integrations (website widget, companion app, kiosk, Claude & Cursor (MCP))

> 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/openapi.json · other sections: https://docs.bithuman.ai/llms/start.txt · https://docs.bithuman.ai/llms/platforms.txt · 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/build-media.txt · https://docs.bithuman.ai/llms/troubleshooting.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 every 5 s until `status` is `ready` or `failed` (`success` is not final; a `final` field is coming). New Essence 2 agent: minutes; Expression 2: longer.
- API and SDK use requires the Creator plan or higher. Never tell a user they can build on a free plan.
- In a LiveKit worker, name the secret `BITHUMAN_MASTER_SECRET` and pass a minted token (https://docs.bithuman.ai/platforms/livekit.md).
- Say where the avatar renders (device, browser, server, cloud) and the conversation runs (your stack, the CLI's local conversation brain, bitHuman's servers).
- Quote prices only from https://docs.bithuman.ai/pricing.md and speed only from https://docs.bithuman.ai/performance.json (× real time, with the device).
- Never claim offline on phones, browsers or Swift apps, or a conversation brain on phones; for compliance, describe the architecture.

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

## Contents

- 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
- Claude & Cursor (MCP) — https://docs.bithuman.ai/build/mcp

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
- Built with bitHuman — https://docs.bithuman.ai/examples/built-with-bithuman.md

---

# Website widget

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

> Add a floating, talking avatar to any website with one script tag.

To add a talking AI avatar to a website, paste one `<script>` tag before `</body>`. It works on any page, in any framework, with no npm package and no server to run.

## 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.

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 **Let anyone talk without signing in** on in the agent's Share Agent dialog: the widgets open the agent's public link, and its sessions bill your account.

**Sample agents end after 1 minute.** bitHuman pays for sessions on its sample and showcase agents, such as `wise-pup`, so each one ends about a minute after the avatar appears (or 5 minutes after it starts, if the avatar never appears), with an end-of-demo card.

**Your own agent has no visitor limits by default.** Chats run until the visitor closes them and bill by the second, talking or idle; set a limit for a kiosk that runs all day. You can set a per-session and a daily limit. Sessions start only when the visitor taps, so a page view costs nothing.

Set them in the Console: open the agent's **Embed Agent** tab, then **Visitor limits**, to set a daily limit in minutes for all visitors together, a limit per chat (5 to 60 minutes, or no limit) and an optional list of allowed websites. When the daily limit is used up, new visitors see a *Resting for Today* card until the next day.

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&render=auto",
    position: "bottom-right",
    buttonText: "Talk to us",
  });
</script>
```

`render=auto`: web render by default; devices that can't web-render use cloud render automatically. `render=cloud` forces cloud.

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?render=auto",
    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.

### Make the AI character stand on your page

Add `transparent: true` and the character's backdrop is removed, so it floats over your page with no box around it. Try it with the `Biscuit` sample (agent code `G10BISCUIT`):

```html
<script src="https://www.bithuman.ai/widgets/bithuman-gadget.js"></script>
<script>
  BitHumanGadget.init({
    agentUrl: "https://bithuman.ai/G10BISCUIT?deployment=gadget&render=auto",
    transparent: true,
    size: 360,
  });
</script>
```

Expected:

The button opens Biscuit standing directly on your page, with your page's background around it.

Transparent mode works for AI characters filmed or generated on a plain green backdrop. For any other character the frame stays as it is, so turning it on never breaks a page. In your own `<iframe>`, add `transparent=1` to the embed URL instead.

### 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=auto` })}
    />
  );
}
```

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/app#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. With `render=auto` the avatar renders in the visitor's tab where the device can; otherwise it 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. Managed voice chat bills 10 credits per minute, all-inclusive: the avatar is part of it. Billing: [How billing works](https://docs.bithuman.ai/pricing#how-billing-works). Every rate: [Pricing and credits](https://docs.bithuman.ai/pricing).

## Make it your own

The embed dialog in the Console 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&render=auto` (`render=cloud` forces cloud render) |
| `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 ([Transparent background](#transparent-background)) |
| `keyColor`, `keySimilarity`, `keySmoothness`, `keySpill`, `keyErode`, `keyer` | fine-tune `transparent` ([Transparent background](#transparent-background)) |
| `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>?render=auto` (`render=cloud` forces cloud render) |
| `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)).

### Transparent background

`transparent: true` ([Make the AI character stand on your page](#make-the-ai-character-stand-on-your-page)) removes a plain green backdrop, so the AI character stands right on your page with no box around it.

![The same AI character in the default frame on its green backdrop, and with transparent: true standing on the page behind it](https://docs.bithuman.ai/images/transparent/transparent-background.webp)

**When it applies.** The character's backdrop must be one even green, as it is for the showcase characters Biscuit (`G10BISCUIT`) and Marmalade (`G06MARMALAD`). In the Console, the embed dialog suggests the option when your character's picture stands on a green backdrop.

The visitor's browser looks at the edges of the first frames. When they are one saturated colour, it removes that colour from every frame; when they are not (a photo backdrop, a room, a grey wall), it keeps the normal frame, so the option never damages a character. The green is removed in the browser, so nothing extra is sent over the network. A browser without WebGL 2 shows the normal frame.

**Tuning.** The defaults suit most green backdrops. Each option below is also a query parameter of the web embed URL (in brackets), for an `<iframe>` with `transparent=1`:

| Option | Values |
|---|---|
| `keyColor` (`keyColor`) | the backdrop colour, such as `00b140`; default: measured from the video. Setting it also skips the edge check |
| `keySimilarity` (`similarity`) | how close to the key a colour must be to disappear, 0.01 to 0.5 (default 0.08) |
| `keySmoothness` (`smoothness`) | the width of the soft edge, 0.001 to 0.5 (default 0.08) |
| `keySpill` (`spill`) | how strongly green light on the character's edges is removed, 0 to 1 (default 0.8) |
| `keyErode` (`erode`) | how far the edge is pulled in, 0 to 1 (default 0.5) |
| `keyer` (`keyer`) | `classic` uses the earlier, simpler keying (default: the current one, with smoothed edges and only the central character kept) |

## 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 **Let anyone talk without signing in** back on in the agent's Share Agent dialog. |
| The frame shows `Agent not found` | The agent code is wrong: copy it from the agent's **Embed Agent** dialog in the Console. |
| 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. |
| The session ends after a minute with *That's the end of this demo* | The widget points at a bitHuman sample agent, whose sessions end after about a minute. Point `agentUrl` at your own agent. |
| A visitor's chat ends early, or new visitors see *Resting for Today* | A visitor limit you set on the agent: a limit per chat, or the daily limit for all visitors (it resets the next day). There are no limits by default; change or remove them in the agent's **Embed Agent** tab, **Visitor limits**. |
| The avatar says *Voice is off on this site* | Your own `<iframe>` is missing `allow="microphone"`. Add it, as in the [Web](https://docs.bithuman.ai/platforms/web) embed. |

---

# Companion app

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

> An AI companion in your iPhone, iPad or Android app, rendered on the phone.

## 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 in bithuman-examples: [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/api/billing#check-credit-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.startAudio(r)
            }
            if let cg = makeCGImage(bgr: f.bgr, f.width, f.height) {
                self.sink.show(cg)
                self.hasFrame = true
            }
    // …
private func startAudio(_ reply: AVAudioPCMBuffer) {
    player.stop()
    player.scheduleBuffer(reply, completionHandler: nil)
    player.play()
}
    // …
    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"
    // …
    // pull() returns false until frames are ready, so poll. Stop after 5 s
    // with no new frame — but give the FIRST frame longer (30 s): a cold
    // first render on a slower phone can take more than a few seconds, and
    // giving up before it arrives is a blank screen, not a result.
    var quietMs = 0
    while (quietMs < (if (out.isEmpty()) 30_000 else 5_000)) {
        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/swift/app#integrate-into-your-app) and [Android](https://docs.bithuman.ai/platforms/android/app#integrate-into-your-app).

Expected:

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

### Close the avatar with the screen

What bills, and from which versions: [Pricing](https://docs.bithuman.ai/pricing). Close the avatar with the screen anyway, as below.

- 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.
- If the app does not, the session ends on its own after 60 seconds in the background (Swift package 2.20.4, `essence2-android` 0.9.5, `expression2-android` 0.6.1 and Flutter plugin 2.6.37 or newer). Current SDKs bill only the seconds the avatar speaks. The next frame the app asks for while it is on screen starts a new session.
- 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. Essence 2 and the Android SDK need a physical device; Expression 2 also runs in the iOS Simulator.

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.

The overview to share with your team is on bithuman.ai: [AI avatars for app developers](https://www.bithuman.ai/developers).

## 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 for Essence 2 and Expression 2, about $0.02 a minute at the top-up rate of $1 = 100 credits. Billing: [How billing works](https://docs.bithuman.ai/pricing#how-billing-works). 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: Essence 2 and the Android SDK need a physical device; Expression 2 also runs in the iOS Simulator. |
| 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, full-screen avatar on a standard Linux PC with no GPU.

To run a kiosk with no GPU, start the avatar with the bitHuman CLI and show it full screen in Chrome. Both models run live on a standard Linux PC with no GPU ([Performance](https://docs.bithuman.ai/performance)).

## 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)    # your own agent: AVATAR=$(python -m bithuman pull <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 x86_64: Expression 2 now; Essence 1 and Essence 2 come later. 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/enterprise?topic=offline#contact) 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 `python -m bithuman pull <agent code>` (bithuman 2.12.8 or newer; it needs `BITHUMAN_API_SECRET`).
- **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:** rates and what bills are on [Pricing](https://docs.bithuman.ai/pricing). The avatar bills only the seconds it speaks; 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. |

---

# Claude & Cursor (MCP)

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

> Let Claude, Cursor and other MCP clients drive bitHuman as tools.

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

## What you'll build

Your MCP client can create avatars, render talking videos, embed agents and check your credits by calling bitHuman tools.

You need:

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

### In ChatGPT or Claude, with no install

bitHuman also runs a hosted MCP server at `https://mcp.bithuman.ai/mcp`. It needs no account and no API secret. Add it as a custom connector in Claude or ChatGPT (step by step: [ChatGPT](https://docs.bithuman.ai/build/chatgpt), [Claude](https://docs.bithuman.ai/build/claude)), then ask for a bitHuman character to say something: the clip plays in the chat, labelled as AI-generated.

| Tool | What it does |
|---|---|
| `list_characters` | Lists the bitHuman characters that can speak, with a picture of each |
| `make_character_video` | Makes a short clip of one character saying your words, 3 to 200 characters, in its own voice |
| `talk_to_character` | Opens a live conversation with a character in the chat |

The hosted server speaks only as bitHuman's own characters. To use your own avatar, run the CLI's server below with your API secret. What the hosted server stores, and for how long: [bitHuman in ChatGPT and Claude](https://docs.bithuman.ai/legal/mcp-server).

## Steps

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

Expected:

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

Expected:

After `bithuman login`, `bithuman account` shows your plan and credit balance.

### Connect your client

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}`.

Expected:

The client reports `{"valid": true}` from `validate_api_secret`.

## How it works

- Agent creation is asynchronous: an Essence 2 agent takes minutes, an Expression 2 agent takes longer to build. 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).

## Make it your own

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` |
| "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 |
| `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 gestures; creating new ones is paused for now (`503 CREATION_PAUSED`, nothing charged) |
| `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 |

There is no text-to-speech tool: bitHuman does not synthesize speech. Make a WAV with any TTS and pass it to `render`, or send it to the [talking-video API](https://docs.bithuman.ai/build/talking-video). CLI 2.8.7 and earlier still list `list_voices` and `text_to_speech`; both now return 410 `ENDPOINT_RETIRED`.

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

## 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 MODEL_SUBJECT_MISMATCH` when creating an agent | the subject is not a real person, or no face was found; every model but Expression 2 needs one | choose Expression 2 ([Choosing a model](https://docs.bithuman.ai/models#choosing-a-model)) |

## Next

- [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)