bitHuman

Developers · Python

Real-time avatars from Python on Mac and Linux

pip install bithuman, load an avatar, push audio, and get lip-synced frames on your own machine — for desktop companions, kiosks and server pipelines. On Linux it renders both models on the CPU alone; a standard PC needs no GPU.

From 12 October 2026, API and SDK use requires the Creator plan or higher.

First frame in the docsGet an API secret

Install

Install

pip (in a virtual environment)
pip install "bithuman[expression-2]"

What you need: API secret (from the docs)

Your first frame, step by step The full Python guide

Conversation

Add a conversation

The Python SDK renders: audio in, lip-synced frames out. The conversation comes from your own code.

  • conversation.py in the quickstart

    Your microphone goes to OpenAI Realtime with your own key, and the avatar answers in a window on your machine.

    python/quickstart

  • The LiveKit plugin, for servers

    Give a LiveKit voice agent a face rendered on your own server, or a bitHuman cloud avatar. The worker holds your API secret as BITHUMAN_MASTER_SECRET and, for a cloud avatar, mints a one-hour token per session, so the secret stays on your server.

    LiveKit

When the avatar renders in your app on the device and you use your own voice and language services, bitHuman receives usage metering only, never audio, video or conversation text.

Requirements

Requirements

  • Python 3.10–3.14 on macOS 14 or newer with Apple silicon, or on Linux x86_64 or arm64.
  • Install into a virtual environment; the package installs no command-line tool (the CLI is a separate binary).

Performance

Measured on real hardware

Every configuration we publish for this platform renders faster than real time.
Seconds of avatar video rendered per second, Python
DeviceEssence 2Expression 2
macOS · PythonApple M46.96× real time2026-09-258.45× real time2026-09-25
Linux · PythonIntel Core i7-13700F (x86_64)1.96× real time2026-09-262.35× real time2026-09-26
“× real time” is seconds of avatar video rendered per second of wall-clock time: end-to-end audio in to frame out, one session, unpaced; the slowest of three quiet runs at least ten minutes apart on the published release. Read from docs performance.json (generated 2026-09-27). How we measure →

Pricing

What it costs

What it costs to run an avatar in your app
ItemOn the device (Essence 2, Expression 2)bitHuman cloud avatarManaged voice chat (all-inclusive)
Credits per minute of active session time2410
At top-up rates ($1 = 100 credits)about $0.02about $0.04about $0.10

From 12 October 2026, API and SDK use requires the Creator plan or higher.

Rates from GET https://api.bithuman.ai/v1/pricing, as published on docs.bithuman.ai/pricing.

The full table, with a worked example Budget an app (docs)

Examples

Examples you can clone

  • Python quickstart: a still from the recording

    Python quickstart

    Open an avatar, play speech through it and watch it talk; conversation.py adds a voice conversation.

    Runs on
    Mac, Linux
    Conversation
    Yes, in conversation.py (with your own OpenAI key)
    Needs
    API secret

    python/quickstart Walkthrough

  • Screenshot coming

    Python with LiveKit

    A voice agent with a face: rendered on your own machine, or a bitHuman cloud avatar in your LiveKit room.

    Runs on
    Mac, Linux, LiveKit
    Conversation
    Yes
    Needs
    API secret, LiveKit, an OpenAI key

    python/self-host python/cloud-essence Walkthrough

  • Screenshot coming

    Gradio web demo

    Talk to an avatar in the browser through a Gradio page.

    Runs on
    Web (Python)
    Conversation
    Yes
    Needs
    API secret, an OpenAI key

    integrations/gradio-web

All examples

Checklist

Before you ship

Keep the API secret on the machine that renders, in an environment variable or a secret store, never in source control. Give each app its own secret so you can rotate one without touching the others.

The full checklist

Limits

Not available on this platform

  • Native Windows: use WSL2.
  • Intel Macs.

More

Other platforms