Skip to content
bitHuman
Join DiscordSign inSign up

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

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

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

  • 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).

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 you can clone

All examples

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

Not available on this platform

  • Native Windows: use WSL2.
  • Intel Macs.

Questions? Ask on Discord

Join the bitHuman Discord