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.

Use existing bitHuman agents in real-time applications with our cloud-hosted LiveKit plugin. The avatar runs on bitHuman’s servers — no model files, no GPU needed on your side.
New here? Read How It Works first to understand rooms, sessions, and avatars.

Quick Start

1

Install the plugin

pip install livekit-plugins-bithuman
This installs the bitHuman LiveKit plugin along with all required dependencies (bithuman, livekit-agents, etc.).
2

Get your API Secret

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

Find your Agent ID

Go to your Library and click any agent. The side panel shows your Agent ID (e.g., A18MDE7951).Agent Settings
4

Set environment variables

export BITHUMAN_API_SECRET="your_api_secret"
export BITHUMAN_AGENT_ID="A78WKV4515"
export OPENAI_API_KEY="sk-..."

# LiveKit (get from cloud.livekit.io)
export LIVEKIT_URL="wss://your-project.livekit.cloud"
export LIVEKIT_API_KEY="APIxxxxxxxx"
export LIVEKIT_API_SECRET="xxxxxxxx"

Complete Working Example

Here’s a full agent that uses a cloud-hosted avatar:
import asyncio
import os
from livekit.agents import (
    Agent,
    AgentSession,
    JobContext,
    RoomOutputOptions,
    WorkerOptions,
    cli,
    llm,
)
from livekit.plugins import openai, silero, bithuman

class MyAgent(Agent):
    def __init__(self):
        super().__init__(
            instructions="""You are a friendly assistant.
            Keep responses to 1-2 sentences.""",
        )

async def entrypoint(ctx: JobContext):
    # Connect to the LiveKit room
    await ctx.connect()

    # Wait for a human to join
    await ctx.wait_for_participant()

    # Create a cloud-hosted avatar
    avatar = bithuman.AvatarSession(
        avatar_id=os.getenv("BITHUMAN_AGENT_ID"),
        api_secret=os.getenv("BITHUMAN_API_SECRET"),
    )

    # Wire up the AI pipeline
    session = AgentSession(
        stt=openai.STT(),              # Listens to the user
        llm=openai.LLM(),              # Generates responses
        tts=openai.TTS(),              # Converts text to speech
        vad=silero.VAD.load(),         # Detects when user is speaking
    )

    # Start — avatar joins room and begins animating
    await avatar.start(session, room=ctx.room)

    await session.start(
        agent=MyAgent(),
        room=ctx.room,
        room_output_options=RoomOutputOptions(audio_enabled=False),
    )

if __name__ == "__main__":
    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))
Run it:
python agent.py dev
Open agents-playground.livekit.io and talk to your avatar.

What Happens When You Run This

  1. Your agent connects to a LiveKit room and waits for a user
  2. When a user joins, AvatarSession sends a request to bitHuman’s cloud
  3. A cloud avatar worker downloads the model (cached after first time) and joins the room
  4. The user speaks → STT transcribes → LLM responds → TTS generates audio → Avatar animates
  5. The avatar publishes video to the room — the user sees a talking face

Avatar Modes

Essence Model (CPU) — Default

Pre-built avatars with full body support, animal mode, and fast response times.
avatar = bithuman.AvatarSession(
    avatar_id="A78WKV4515",
    api_secret="your_api_secret",
)

Expression Model — Agent ID

Higher-fidelity face animation for platform-created agents.
avatar = bithuman.AvatarSession(
    avatar_id="A78WKV4515",
    api_secret="your_api_secret",
    model="expression",
)

Expression Model — Custom Image

Create an avatar from any face image on-the-fly.
from PIL import Image

avatar = bithuman.AvatarSession(
    avatar_image=Image.open("face.jpg"),
    api_secret="your_api_secret",
    model="expression",
)

Model Comparison

FeatureEssence (CPU)Expression
PersonalitiesPre-trainedDynamic
Response timeFaster (~2s)Standard (~4s)
Body supportFull body + animal modeFace and shoulders
Animal modeYesNo
Custom imagesNoYes
The Expression model runs on bitHuman Cloud (default), your own NVIDIA GPU (Self-Hosted GPU), or natively on Apple Silicon M3+ (Expression on macOS).

Adding Gestures (Dynamics)

Make the avatar wave, nod, or laugh in response to conversation keywords. Gestures are supported for Essence avatars only.

Dynamics API Reference

Complete guide to generating, listing, and triggering gesture animations

Configuration

ParameterTypeRequiredDescription
avatar_idstringYes*Agent ID from your Library
avatar_imagePIL.ImageYes*Face image for on-the-fly avatar (Expression only)
api_secretstringYesYour API secret
modelstringNo"essence" (default) or "expression"
*Either avatar_id or avatar_image is required.

Cloud Advantages

  • No Local Storage — No large model files to download or manage
  • Auto-Updates — Always uses the latest model versions
  • Scalability — Handles multiple concurrent sessions automatically
  • Cross-Platform — Works on any device with internet

Pricing

Visit Billing or click the credit balance in the top navigation for current pricing.
PlanPriceConcurrent SessionsGenerations/Day
FreeFree25
Creator$20/mo520
Pro$99/mo1050
EnterpriseCustomCustomCustom

Troubleshooting

ProblemSolution
Authentication errorsVerify API secret at Developer → API Keys
Avatar doesn’t appearCheck agent_id exists in your Library
Network timeoutsEnsure stable internet; the plugin retries automatically
Plugin installation failsRun pip install livekit-plugins-bithuman --upgrade
No lip movementEnsure avatar.start(session, room=ctx.room) is called before session.start()

Next Steps

Avatar Sessions Guide

All avatar modes explained with complete examples

Self-Hosted Plugin

Run on your own infrastructure

Dynamics API

Configure gestures and animations