bitHuman Video Avatar

BitHumanVideoService renders a lip-synced bitHuman avatar in your own process from your Pipecat agent’s TTS audio.

Overview

BitHumanVideoService takes your bot’s TTS audio and turns it into a talking avatar. It pushes OutputImageRawFrame (RGB) and the matching TTSAudioRawFrame, so the mouth and the voice leave together. The avatar renders in your own process through the bithuman Python SDK. Expression 2 animates any character from one portrait; Essence 2 renders a photoreal person from one portrait.

Interruptions are handled: on InterruptionFrame the avatar drops the reply in flight and goes back to idle.

Installation

uv add pipecat-bithuman
# Expression 2 avatars:
uv add "pipecat-bithuman[expression-2]"

Prerequisites

bitHuman account setup

1. Create an account at www.bithuman.ai and create an API secret.
2. Download an avatar model (.imx). See docs.bithuman.ai.

Required environment variables

• BITHUMAN_API_SECRET: your bitHuman API secret.
• BITHUMAN_MODEL_PATH: path to the .imx model (or pass model_path).

Rendering bills active session time: 2 credits a minute on your own machine. From 2026-10-12, SDK use requires the Creator plan or higher. See docs.bithuman.ai/pricing.

Configuration

Constructor parameters for BitHumanVideoService:

model_path · str · default: "None"

Path to the avatar’s .imx model. Defaults to BITHUMAN_MODEL_PATH.

api_secret · str · default: "None"

bitHuman API secret. Defaults to BITHUMAN_API_SECRET. Never logged.

sync_video_to_audio · bool · default: "True"

Sets sync_with_audio on each image so the transport shows it after its audio.

audio_passthrough_on_error · bool · default: "True"

If the avatar fails, forward TTS audio unchanged so the bot keeps talking.

stop_frame_timeout_s · float · default: "2.0"

Release a held TTSStoppedFrame after this much quiet with no end-of-speech.

end_drain_timeout_s · float · default: "30.0"

On EndFrame, the longest wait for queued speech to finish.

The service has no runtime-updatable Settings yet.

Session time is metered while the avatar is open (talking or idle). It closes on EndFrame, CancelFrame or cleanup.

Usage

from pipecat_bithuman import BitHumanVideoService

avatar = BitHumanVideoService(model_path="avatar.imx")

pipeline = Pipeline(
    [transport.input(), stt, user_aggregator, llm, tts, avatar, transport.output(),
     assistant_aggregator]
)

Enable video_out_enabled=True on the transport. The service logs the frame size on the first frame; set video_out_width and video_out_height to match.

A complete example is in the repository.

Compatibility

Tested with Pipecat v1.12.0 (Python 3.11+). Check the source repository for the latest tested version and changelog.