bitHuman SDK

Turn any face into a talking avatar. Send audio in, get a lip-synced animated face out — in real time, at 25 frames per second.

Use it to build AI assistants with faces, video chatbots, virtual tutors, digital receptionists, or anything that needs a character that speaks.

Before you start

You need a free API key. It takes 30 seconds:

Go to www.bithuman.ai and sign up
Click Developer → API Keys
Copy your key

You get 99 free credits per month (about 50 minutes of avatar time). No credit card required.

Which key name do I use?

Python, CLI, and REST API → set the environment variable BITHUMAN_API_SECRET

Swift SDK (Apple apps) → set the environment variable BITHUMAN_API_KEY

They come from the same dashboard page. The names differ for historical reasons.

Pick how you want to build

I want to...	Tool	Time to first demo	Start here
See it work immediately	Python or CLI	5 min	Examples/quickstart/
Build with Python (web app, server, Raspberry Pi)	`pip install bithuman`	10 min	Examples/python/
Build a native Apple app (Mac, iPad, iPhone)	Swift SDK	15 min	Examples/swift/
Use the command line (no code at all)	`brew install bithuman-product/bithuman/bithuman-cli` (or `pip install bithuman-cli` — macOS only)	2 min	Examples/cli/
Call from any language (Java, Go, JS, etc.)	REST API	5 min	Examples/rest-api/
Talk to it with zero cloud (no OpenAI key, no outbound network)	`pip install 'bithuman-cli[local]'` then `BITHUMAN_LOCAL=1 bithuman run`	5 min after a ~860 MB one-time download	Local mode →

If you're unsure, start with Examples/quickstart/.

Two avatar models

bitHuman has two avatar engines. Start with Essence unless you need custom face-swapping.

	Essence (start here)	Expression (advanced)
How it works	You upload a photo/video on bithuman.ai, it generates a `.imx` avatar file you download	You provide any face image at runtime — no generation step
Hardware needed	Any CPU (laptop, server, Raspberry Pi)	NVIDIA GPU or Mac with M3+ chip
Cost	1 credit/min (self-hosted) or 2 credits/min (cloud)	2 credits/min (self-hosted) or 4 credits/min (cloud)
Best for	Getting started, kiosks, voice agents, 24/7 displays	Apps where users pick their own face, consumer apps

Full comparison: docs.bithuman.ai/getting-started/models

Install

Python (Linux, macOS)

pip install bithuman --upgrade

Works with Python 3.10 through 3.14 on Linux (x86_64 + aarch64) and macOS 26+ (Apple Silicon). Pre-built wheels — no compile step. Windows is planned.

Swift (Mac, iPad, iPhone)

In Xcode: File → Add Package Dependencies → paste this URL:

https://github.com/bithuman-product/bithuman-sdk-public.git

Requires Apple Silicon M3 or newer on macOS 26 (Tahoe) — or iPhone 16 Pro / iPad Pro M4 on iOS / iPadOS 26. See swift/README.md for the full hardware + OS floor.

CLI — talk to an avatar in 2 minutes

Three install paths, same Rust binary:

# Path A: Homebrew (macOS, recommended; pulls native deps).
brew install bithuman-product/bithuman/bithuman-cli

# Path B: universal installer (macOS + Linux, no Python needed).
curl -fsSL https://raw.githubusercontent.com/bithuman-product/homebrew-bithuman/main/install.sh | sh

# Path C: pip — sibling wheel for Python-only environments
# (macOS Apple Silicon only — on Linux use Path B).
pip install bithuman-cli

pip install bithuman is the library — it doesn't ship the CLI since 2.3 (the CLI moved to the standalone bithuman-cli wheel). Either way:

export BITHUMAN_API_SECRET=...   OPENAI_API_KEY=...
bithuman run                                          # auto-downloads a demo avatar
# → http://127.0.0.1:8088/<code> — open in browser, click mic, talk

bithuman run is the full talk-to-your-avatar stack — embedded livekit-server + agent-worker brain + browser UI — from one command. For offline rendering and other modes, see docs.bithuman.ai/cli.

Quick start (Python)

import asyncio, os
import numpy as np
import soundfile as sf
from bithuman import AsyncBithuman

# bithuman 2.3 is library-only — the old bithuman.audio helpers were
# removed. Inline what we need (the SDK resamples to 16 kHz internally).
def load_audio(path):
    audio, sr = sf.read(path, dtype="float32", always_2d=False)
    if audio.ndim > 1:
        audio = audio.mean(axis=1)
    return audio, sr

def float32_to_int16(arr):
    return (np.clip(arr, -1.0, 1.0) * 32767.0).astype(np.int16)

async def main():
    # 1. Load the avatar model and connect to the billing API
    runtime = await AsyncBithuman.create(
        model_path="avatar.imx",                          # your .imx file
        api_secret=os.environ["BITHUMAN_API_SECRET"],     # from bithuman.ai
    )

    # 2. Push audio — the avatar will lip-sync to it
    pcm, sr = load_audio("speech.wav")
    pcm = float32_to_int16(pcm)
    chunk = sr // 25                                       # one chunk per frame
    for i in range(0, len(pcm), chunk):
        await runtime.push_audio(pcm[i : i + chunk].tobytes(), sr, last_chunk=False)
    await runtime.flush()                                  # signal "audio is done"

    # 3. Pull video frames — each frame is a numpy image
    async for frame in runtime.run():
        if frame.has_image:
            image = frame.bgr_image   # numpy array, shape (H, W, 3), BGR format
        if frame.end_of_speech:
            break

    await runtime.stop()

asyncio.run(main())

Don't have an .imx file? Download one from bithuman.ai → Explore (click the ... menu on any agent → Download).

What's in this repo

├── Package.swift              Swift package manifest — distributes the bitHumanKit
│                              framework as a binaryTarget consuming the xcframework
│                              attached to this repo's GitHub Releases.
│
├── python/                    Landing page for the `bithuman` PyPI package — README,
│                              CHANGELOG, LICENSE. The SDK itself installs via
│                              `pip install bithuman` (pre-built wheels).
├── swift/                     Landing page for the `bitHumanKit` Swift package — README,
│                              CHANGELOG, LICENSE. Add via SwiftPM (URL above).
│
├── Examples/                  Working code you can run
│   ├── quickstart/                Your first demo (start here)
│   ├── python/                    6 Python examples (cloud + local)
│   ├── swift/                     4 Swift examples (macOS, iOS, Essence)
│   ├── cli/                       Shell scripts for CLI tools
│   ├── rest-api/                  curl and Python scripts for the HTTP API
│   └── integrations/              Next.js, Java, Gradio, offline Mac
│
├── docs/                      Source for docs.bithuman.ai (Mintlify)
├── AGENTS.md                  Instructions for AI coding agents
└── CONTRIBUTING.md            How to contribute to this repo

About python/ and swift/. These directories are the landing pages and version history for each SDK — install with pip install bithuman or the SwiftPM URL above; the runtimes ship as pre-built wheels and xcframework. File bugs at bithuman-sdk-public/issues — that's where both Swift and Python issues are triaged.

Pricing

What	Cost	Notes
Free tier	99 credits/month	No credit card needed
Essence (you host)	1 credit/min	Runs on CPU
Essence (we host)	2 credits/min	No setup needed
Expression (you host)	2 credits/min	Needs GPU or Mac M3+
Expression (we host)	4 credits/min	No setup needed
Generate a new agent	250 credits	One-time cost

1 credit ~ 1 minute of avatar time. Full pricing details

Documentation

Topic	Link
Python getting started	docs.bithuman.ai/getting-started/quickstart
Swift SDK	docs.bithuman.ai/sdks/swift
REST API reference	docs.bithuman.ai/api-reference/overview
How authentication works	docs.bithuman.ai/getting-started/authentication
Pricing and credits	docs.bithuman.ai/getting-started/pricing
Essence vs Expression	docs.bithuman.ai/getting-started/models

Get help

Questions or bugs → GitHub Issues
Community chat → Discord
Security issues → email hello@bithuman.ai (see SECURITY.md)

License

Example code in this repo: MIT (use it however you want)
Python SDK (bithuman package): commercial license — see bithuman.ai
Swift SDK (bitHumanKit framework): bitHuman Terms of Service

Navigation Menu

Uh oh!

Repository files navigation

bitHuman SDK

Before you start

Pick how you want to build

Two avatar models

Install

Python (Linux, macOS)

Swift (Mac, iPad, iPhone)

CLI — talk to an avatar in 2 minutes

Quick start (Python)

What's in this repo

Pricing

Documentation

Get help

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github		.github
Examples		Examples
mcp		mcp
python		python
scripts		scripts
swift		swift
templates		templates
.cursorrules		.cursorrules
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Package.swift		Package.swift
README.md		README.md
SECURITY.md		SECURITY.md

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

bitHuman SDK

Before you start

Pick how you want to build

Two avatar models

Install

Python (Linux, macOS)

Swift (Mac, iPad, iPhone)

CLI — talk to an avatar in 2 minutes

Quick start (Python)

What's in this repo

Pricing

Documentation

Get help

License

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages