Skip to main content

​
1. Get Credentials

1

Sign up

Create an account at www.bithuman.ai
2

Copy your API Secret

Go to Developer → API Keys and copy your API Secret.API Keys
3

Download an avatar model

Download an avatar model (.imx file) from the Explore page — click the ⋮ menu on any agent and select Download.Download Model

​
2. Install

pip install bithuman --upgrade
The SDK includes opencv-python-headless automatically. Do not install opencv-python (full) separately — it conflicts with PyAV and causes FFmpeg warnings on macOS.

​
3. Run Your First Avatar

You need a .wav audio file to drive the avatar. A sample speech.wav is included in each example directory, or generate your own with any TTS service. 
import asyncio
import cv2
from bithuman import AsyncBithuman
from bithuman.audio import load_audio, float32_to_int16

async def main():
    # Initialize
    runtime = await AsyncBithuman.create(
        model_path="avatar.imx",
        api_secret="your_api_secret"
    )
    await runtime.start()

    # Load and push audio
    audio, sr = load_audio("speech.wav")
    await runtime.push_audio(
        float32_to_int16(audio).tobytes(), sr
    )
    await runtime.flush()

    # Display animated frames
    async for frame in runtime.run():
        if frame.has_image:
            cv2.imshow("Avatar", frame.bgr_image)  # numpy (H, W, 3)
            cv2.waitKey(1)

asyncio.run(main())
Full working example on GitHub

​
Key Concepts

ConceptDescription
RuntimeAsyncBithuman instance that processes audio into video
push_audioFeed audio bytes — avatar lip-syncs in real-time
flushSignals end of audio input
run()Async generator that yields frames at 25 FPS
FrameContains .bgr_image (numpy), .audio_chunk, .end_of_speech

​
Troubleshooting

The SDK is not installed. Run:
pip install bithuman --upgrade
Make sure you’re using the correct Python environment (virtualenv, conda, etc.).
Your API secret is invalid or missing. Check:
  1. You copied the full secret from Developer → API Keys
  2. The api_secret parameter or BITHUMAN_API_SECRET env var is set correctly
  3. Your account is active with available credits
Quick test:
curl -X POST https://api.bithuman.ai/v1/validate \
  -H "api-secret: YOUR_SECRET"
The avatar needs audio input to animate:
  1. Ensure you’re calling push_audio() with valid audio data
  2. Call flush() after pushing all audio
  3. Check that the audio is 16-bit PCM format (use float32_to_int16() helper)
  4. Verify audio sample rate matches the file (typically 16000 or 44100)
This is normal for the first session — the .imx model takes time to load and initialize. Subsequent sessions in the same process start instantly.To reduce perceived latency, keep the runtime alive between sessions instead of recreating it.
The model file path is wrong. Check:
  1. The .imx file exists at the path you specified
  2. Use an absolute path if running from a different directory
  3. Download a model from the Explore page if you don’t have one

​
Next Steps

Audio Clip

Play audio file through avatar (5 min)

Live Microphone

Real-time mic input (10 min)

AI Conversation

OpenAI voice chat (15 min)
Or jump straight to the Docker App for a complete end-to-end setup.

​
Guides

​
System Requirements

  • Python 3.9+, 4+ CPU cores, 8GB RAM
  • macOS (M2+), Linux (x64/ARM64), or Windows (WSL)