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.

Complete chatbot with avatar that users can talk to on the web.

​
Quick Start

1

Install

pip install bithuman --upgrade openai sounddevice loguru
The SDK includes opencv-python-headless automatically. Do not install opencv-python (full) separately.
2

Get accounts

3

Set environment

export BITHUMAN_API_SECRET="your_secret"
export BITHUMAN_MODEL_PATH="/path/to/model.imx"
export OPENAI_API_KEY="your_openai_key"
4

Run

git clone https://github.com/bithuman-product/bithuman-examples.git
cd bithuman-examples/essence-selfhosted
python conversation.py --model /path/to/model.imx
View source code on GitHubSpeak into your microphone. The AI responds via OpenAI Realtime and the avatar lip-syncs in real time. Press Q to quit.

​
What It Does

  1. Captures audio from your microphone
  2. Sends speech to OpenAI Realtime API for AI conversation
  3. Receives AI response audio and feeds it to the avatar
  4. Avatar lip-syncs in real time — no LiveKit server needed
Built with:
  • OpenAI Realtime API for voice conversation
  • bitHuman SDK for avatar animation
  • sounddevice for mic capture and speaker output
For a full web-based setup with LiveKit and a browser UI, see the Docker example — run docker compose up and open http://localhost:4202.

​
Customization

Change the agent’s personality by editing the instructions: 
agent=Agent(
    instructions=(
        "You are a helpful customer service assistant. "
        "Be friendly, professional, and solve problems quickly."
    )
)
Example personalities:
  • Tech Support: “You are a patient tech expert who explains things simply”
  • Sales Assistant: “You are an enthusiastic product advisor”
  • Teacher: “You are an encouraging tutor who makes learning fun”

​
Common Issues

ProblemSolution
Agent won’t startCheck all API keys are set
No audio in browserAllow microphone permissions, try Chrome
Can’t connectCheck LiveKit URL format: wss://your-project.livekit.cloud

​
Next Steps

Apple Local Agent

Full privacy — speech never leaves your Mac

Raspberry Pi

Edge deployment on IoT devices