> ## Documentation Index
> Fetch the complete documentation index at: https://daily-main.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# bitHuman Video Avatar

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

export const CommunityMaintained = ({maintainer, maintainerUrl, repo}) => <Note>
    <strong>Community-maintained integration.</strong> This service is built and
    maintained by{" "}
    <a href={maintainerUrl} target="_blank" rel="noreferrer">
      {maintainer}
    </a>
    . Pipecat does not test or officially support it. Please report issues and
    request changes on the{" "}
    <a href={repo} target="_blank" rel="noreferrer">
      source repository
    </a>
    . Learn more about{" "}
    <a href="/api-reference/server/services/community-integrations">
      community integrations
    </a>
    .
  </Note>;

<CommunityMaintained maintainer="bithuman-product" maintainerUrl="https://github.com/bithuman-product" repo="https://github.com/bithuman-product/pipecat-bithuman" />

## 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

```bash theme={null}
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](https://www.bithuman.ai) and create an API secret.
2. Download an avatar model (`.imx`). See [docs.bithuman.ai](https://docs.bithuman.ai/platforms/python).

### 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`:

<ParamField path="model_path" type="str" default="None">
  Path to the avatar's `.imx` model. Defaults to `BITHUMAN_MODEL_PATH`.
</ParamField>

<ParamField path="api_secret" type="str" default="None">
  bitHuman API secret. Defaults to `BITHUMAN_API_SECRET`. Never logged.
</ParamField>

<ParamField path="sync_video_to_audio" type="bool" default="True">
  Sets `sync_with_audio` on each image so the transport shows it after its audio.
</ParamField>

<ParamField path="audio_passthrough_on_error" type="bool" default="True">
  If the avatar fails, forward TTS audio unchanged so the bot keeps talking.
</ParamField>

<ParamField path="stop_frame_timeout_s" type="float" default="2.0">
  Release a held `TTSStoppedFrame` after this much quiet with no end-of-speech.
</ParamField>

<ParamField path="end_drain_timeout_s" type="float" default="30.0">
  On `EndFrame`, the longest wait for queued speech to finish.
</ParamField>

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

```python theme={null}
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](https://github.com/bithuman-product/pipecat-bithuman/blob/main/examples/bot.py).

## Compatibility

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.