Pipecat

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. If you are not on Pipecat, Protoface works with many more platforms and SDKs. See Other integrations.

Install

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:

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():

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:

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 covers the caps.

Compatibility

Tested with Pipecat v1.4.0+ and Python 3.11+. The plugin source carries current examples and compatibility notes.

Inference

Realtime

Account

Reference

Install

Basic usage

Realtime speech-to-speech

Configuration

ProtofaceVideoService options

Lifecycle

Compatibility

​Install

​Basic usage

​Realtime speech-to-speech

​Configuration

​ProtofaceVideoService options

​Lifecycle

​Compatibility

Install

Basic usage

Realtime speech-to-speech

Configuration

ProtofaceVideoService options

Lifecycle

Compatibility