> ## Documentation Index
> Fetch the complete documentation index at: https://docs.protoface.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pipecat

> Add a live avatar to a Pipecat pipeline.

If your voice agent runs on Pipecat, `pipecat-protoface` adds a Protoface
avatar as a video service. It starts a hosted session, takes assistant
speech from the pipeline, and emits synchronized audio and video frames
to your output transport.

Protoface maintains the official Pipecat community plugin, and Pipecat
documents the service at
[docs.pipecat.ai](https://docs.pipecat.ai/api-reference/server/services/video/protoface).

If you are not on Pipecat, Protoface works with many more platforms and
SDKs. See [Other integrations](/guides/more-integrations).

## Install

```bash theme={null}
uv add pipecat-protoface
```

Install Pipecat extras for your transport, STT, LLM, TTS, or realtime
model separately.

## Basic usage

Create the service with an API key and avatar ID:

```python theme={null}
import os

from pipecat_protoface import ProtofaceVideoService

protoface = ProtofaceVideoService(
    api_key=os.environ["PROTOFACE_API_KEY"],
    avatar_id=os.environ["PROTOFACE_AVATAR_ID"],
)
```

Then place it after TTS and before `transport.output()`:

```python theme={null}
pipeline = Pipeline([
    transport.input(),
    stt,
    context_aggregator.user(),
    llm,
    tts,
    protoface,
    transport.output(),
    context_aggregator.assistant(),
])
```

`protoface` then emits synchronized avatar audio and video frames
downstream.

## Realtime speech-to-speech

Place `protoface` after the realtime model and before the output
transport:

```python theme={null}
pipeline = Pipeline([
    transport.input(),
    context_aggregator.user(),
    gemini_live,
    context_aggregator.assistant(),
    protoface,
    transport.output(),
])
```

## Configuration

Set both variables in the Pipecat worker environment.

* `PROTOFACE_API_KEY`: Authenticates calls to Protoface.
* `PROTOFACE_AVATAR_ID`: Avatar to render. Start with `av_stock_001` or
  use an ID from `/v1/avatars`.

## ProtofaceVideoService options

| Option | Purpose |
| - | - |
| `api_key` | Protoface API key. |
| `avatar_id` | Avatar to render. Use an ID from the dashboard or `/v1/avatars`. |
| `api_url` | Protoface API base URL. Defaults to `https://api.protoface.com`. |
| `max_duration_seconds` | Optional upper bound for the Protoface session. |
| `metadata` | Customer-owned JSON attached to the Protoface session. |
| `settings` | Advanced buffering and client-readiness settings. |

## Lifecycle

`ProtofaceVideoService` opens a session as the pipeline starts. The
session moves through `queued`, `starting`, and `running`. Speech
produced before the avatar is live is buffered, then streamed. Stopping
the pipeline ends the session. Billing rounds up to the minute, and
[Credits and limits](/reference/quotas) covers the caps.

## Compatibility

Tested with Pipecat v1.4.0+ and Python 3.11+. The
[plugin source](https://github.com/protoface-ai/protoface-plugin-pipecat)
carries current examples and compatibility notes.


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