Skip to main content
bitHuman Avatars bitHuman creates digital avatars that lip-sync to audio in real-time. Feed in audio — get back an animated face 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. Three ways to run:
  • Cloud — no GPU, no model files. Just an API secret.
  • Self-Hosted CPU — download an .imx model, run on any machine.
  • Self-Hosted GPU — any face image, 1.3B parameter model, 250+ FPS.

​
Quick Start

git clone https://github.com/bithuman-product/examples.git
cd examples/essence-cloud

# Add your API keys to .env
cp .env.example .env
# Edit .env: set BITHUMAN_API_SECRET, BITHUMAN_AGENT_ID, and OPENAI_API_KEY

docker compose up
# Open http://localhost:4202

​
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

Quick Start

Get an avatar running in 5 minutes

API Reference

REST API for agent generation and management

Examples

10+ working examples from basic to advanced

​
Core SDK API

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
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
Linux (ARM64)Full SupportEdge deployments
macOS (Apple Silicon)Full SupportM2+, M4 ideal
WindowsFull SupportVia WSL

​
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