pipecat-bithuman

Questions, demos and challenges: join the bitHuman Discord.

A bitHuman avatar for your Pipecat bot. Your TTS audio goes in. A lip-synced avatar video, plus the audio that goes with it, comes out.

The avatar renders in your own process, on your own machine, through the bithuman Python SDK. Both models run live on a standard Linux PC with no GPU. Expression 2 animates a character from one portrait. Essence 2 is for photoreal people.

Maintained by bitHuman, Inc. (community integration, not maintained by the Pipecat team).

Tested with Pipecat v1.12.0, bithuman 2.11.18, Python 3.11 to 3.14.

Demo (37 s, with a barge-in at 10 s): docs/demo.mp4, rendered through a Pipecat pipeline by examples/render_demo.py (--interrupt-at 10 --repeat 2) with the Expression 2 sample avatar Wise Pup.

Install

pip install pipecat-bithuman
# Expression 2 avatars (any character from one portrait):
pip install "pipecat-bithuman[expression-2]"
# Essence 2 avatars (photoreal people: essence-2 full body, essence-2f face):
pip install "pipecat-bithuman[essence-2]"

Essence 2 avatars stream through bithuman 2.12.1 or later; the essence-2 extra asks for it.

Get an avatar

python -m bithuman pull (from the bithuman package this installs) downloads an avatar and the engine files it needs, and prints the path to pass as model_path:

python -m bithuman list                         # showcase avatars and their model
export BITHUMAN_MODEL_PATH="$(python -m bithuman pull wise-pup)"         # Expression 2
export BITHUMAN_MODEL_PATH="$(python -m bithuman pull sofia-ramirez)"    # Essence 2
export BITHUMAN_MODEL_PATH="$(python -m bithuman pull A00AAA0000)"       # your agent's code

Showcase avatars need no API secret to pull. Your own agent's code does. An agent with both Essence 2 models picks one with --model essence-2 (full body) or --model essence-2f (face).

Environment variables

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

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.

Usage

Put BitHumanVideoService after the TTS service and before transport.output():

from pipecat_bithuman import BitHumanVideoService

avatar = BitHumanVideoService(model_path="avatar.imx")  # secret from BITHUMAN_API_SECRET

pipeline = Pipeline([
    transport.input(), stt, user_aggregator, llm, tts,
    avatar,                      # TTS audio -> avatar video + audio
    transport.output(),
    assistant_aggregator,
])

Turn on video out in the transport (video_out_enabled=True). The service logs the frame size on the first frame; set video_out_width / video_out_height to match.

What the service does with frames

If the avatar cannot start, or fails mid-session, the service pushes one ErrorFrame upstream. By default TTS audio then passes through unchanged, so the bot keeps talking without video (audio_passthrough_on_error=False turns this off). Error text is scrubbed of the API secret.

Options

How it maps to the bitHuman Python SDK

SDK docs: docs.bithuman.ai/platforms/python.

Run the checked source example

The PyPI wheel installs the plugin package, not this repository's examples/ folder. Get the example source first, then install it in a fresh virtual environment with the framework and SDK versions used for the existing checks:

git clone https://gitlab.com/bithuman/sdk/pipecat-bithuman.git
cd pipecat-bithuman
git checkout --detach f7e4d005c363a16204ec8ec4d624362a16914ec6
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -c examples/constraints.txt -e ".[expression-2]" "pipecat-ai[daily,deepgram,openai,cartesia,silero]"
export BITHUMAN_API_SECRET=... BITHUMAN_MODEL_PATH=avatar.imx
export DAILY_ROOM_URL=... DEEPGRAM_API_KEY=... OPENAI_API_KEY=... CARTESIA_API_KEY=... CARTESIA_VOICE_ID=...
python examples/bot.py

This is the reproducible source path; it does not imply that the source's 0.1.1 version has been released on PyPI. The constraints pin Pipecat 1.12.0 and bitHuman 2.11.18. The credential-free integration tests cover frame routing, interruption, cancellation, cleanup and error fallback. Importing the example checks its API imports; it does not prove a live Daily conversation. Running the bot still requires the account keys and avatar listed above, and bills the applicable services.

Tests

pip install -e ".[dev]"
pytest            # fakes only: no network, no API secret, no model file

One live test talks to the real SDK. It is skipped unless you set PIPECAT_BITHUMAN_LIVE=1, BITHUMAN_API_SECRET and BITHUMAN_MODEL_PATH. It opens the avatar for a few seconds, and that time is billed.

Links

• bitHuman: www.bithuman.ai
• Docs: docs.bithuman.ai/platforms/pipecat
• Source and issues: gitlab.com/bithuman/sdk/pipecat-bithuman
• Examples: gitlab.com/bithuman/sdk/bithuman-examples
• Contact: hello@bithuman.ai

Licence

BSD 2-Clause, the same as Pipecat. See LICENSE. Copyright (c) 2026, bitHuman, Inc.