Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.bithuman.ai/llms.txt

Use this file to discover all available pages before exploring further.

bitHuman Avatars bitHuman creates digital avatars that lip-sync to audio in real time. Feed audio in, get an animated face out at 25 FPS. Use it to build AI companions, customer-support avatars, virtual tutors, game NPCs, and anything that needs a visual character that speaks.

​
Pick your path

bitHuman ships two models and three runtime surfaces. Your choice depends on what you’re shipping (web, server, or native app) and which avatar style fits.

​
Two models

ModelWhat it isAvatar sourceComputeBest for
EssenceCPU-only pre-rendered animations with real-time lip-sync.imx model file built from a photo or video on bithuman.aiCPU (any laptop, Raspberry Pi, edge box)Kiosks, 24/7 displays, full body + animal mode, custom gestures
ExpressionAI-generated facial animation from a single imageAny face image — no avatar generation stepNVIDIA GPU or Apple Silicon M3+ (on-device)Dynamic conversations, custom faces, native consumer apps

​
Three runtime surfaces

SurfaceWhat it isModels supportedBest for
bitHuman CloudManaged runtime on api.bithuman.ai. Use via the LiveKit plugin (pip install livekit-plugins-bithuman) or the REST API directly.Essence, ExpressionWeb apps, fastest setup, no infra.
Self-hosted serverRun on your own hardware. Python SDK (pip install bithuman) for Essence on CPU, or Docker container for Expression on Linux + NVIDIA.Essence (CPU), Expression (GPU)On-prem privacy, edge devices, high volume.
On-device Apple SiliconbitHumanKit Swift Package + bithuman-cli Homebrew tool. All inference (STT, LLM, TTS, lip-sync) runs locally; only a 1-req/min billing heartbeat goes out.Expression (M3+ Mac, M4+ iPad Pro, A18 Pro+ iPhone)Native consumer / pro-sumer apps where everything must run locally.
The full matrix and decision tree: How it works → · Essence vs Expression →.

​
5-minute quickstart

Pick the surface that matches what you’re building: 
git clone https://github.com/bithuman-product/bithuman-examples.git
cd bithuman-examples/essence-cloud

cp .env.example .env
# Edit .env: set BITHUMAN_API_SECRET, BITHUMAN_AGENT_ID, OPENAI_API_KEY

docker compose up
# Open http://localhost:4202
Each tab maps to a working example in bithuman-examples.

​
What can you build?

Customer Support

Replace hold music with a talking avatar that answers questions.

AI Tutor

A patient virtual teacher that explains and adapts to students.

Digital Receptionist

Lobby kiosks and tablets that greet and direct visitors.

AI Companion

Persistent characters with personality and memory.

Game NPC

Dynamic characters that react to player actions with gestures.

Video Generation

Batch-generate talking-head videos from scripts.
See all use cases with architecture patterns →

​
Developer guides

Quickstart

Python SDK in 5 minutes

Swift SDK

On-device for Mac/iPad/iPhone

REST API

Agent generation, speak, dynamics

Avatar Sessions

LiveKit Cloud, CPU, GPU — every mode

Examples

Working examples for every surface

Chat Widget

Floating chat with text, voice, and video modes

​
Core SDK API (Python)

MethodDescription
AsyncBithuman.create(model_path, api_secret)Initialize the avatar runtime
runtime.start()Begin processing
runtime.push_audio(data, sample_rate)Send audio for lip-sync
runtime.flush()Signal end of audio input
runtime.run()Async generator yielding video + audio frames
runtime.get_frame_size()Returns (width, height) of output

​
REST API

EndpointMethodDescription
/v1/validatePOSTVerify API secret
/v1/agent/generatePOSTGenerate new avatar agent
/v1/agent/{code}GET/POSTGet or update agent
/v1/agent/{code}/speakPOSTMake avatar speak text
/v1/agent/{code}/add-contextPOSTInject silent knowledge
/v1/files/uploadPOSTUpload image/video/audio
/v1/dynamics/generatePOSTGenerate gesture animations
/v2/credit-summariesGETCheck credit balance and plan details
/v1/embed-tokens/requestPOSTGenerate JWT token for website embedding
Base URL: https://api.bithuman.ai — Auth: api-secret header from Developer → API Keys — Full reference →

​
Platform support

PlatformStatusNotes
Linux (x86_64)Full SupportProduction-ready; Essence CPU + Expression GPU container
Linux (ARM64)Full SupportEdge deployments (Essence CPU)
macOS (Apple Silicon)Full SupportEssence on any Apple Silicon; Expression on-device requires M3+
iPadOS / iOSFull SupportExpression on-device — iPad Pro M4+, iPhone 16 Pro+ via Swift SDK
Windows (x86_64)Full SupportEssence native wheels for Python 3.9–3.14, or WSL
NVIDIA GPU containerFull SupportLinux + Docker — Expression with dynamic face from any image

​
AI agent integration

bitHuman provides llms.txt and an OpenAPI specification for AI coding agent discoverability:
  • llms.txt — Curated documentation index for LLM consumption
  • llms-full.txt — Complete documentation in single markdown file
  • OpenAPI Spec — Machine-readable API contract
  • AGENTS.md — Repository-level agent instructions