pipecat-replicate

Replicate image generation integration for Pipecat — a framework for building voice and multimodal conversational AI applications.

Pipecat Compatibility

Tested with Pipecat v0.0.108

Features

• Text-to-image generation using any Replicate-hosted model
• Official models (owner/name) and versioned community models (owner/name:version)
• Sync prediction requests with automatic polling fallback
• Returns URLImageRawFrame for direct use in Pipecat pipelines
• Configurable via the standard Pipecat Settings dataclass pattern

Installation

Using pip

pip install pipecat-replicate

Using uv

uv add pipecat-replicate

From source

git clone https://github.com/bnovik0v/pipecat-replicate.git
cd pipecat-replicate
pip install -e .

Quick Start

1. Get your Replicate API token at https://replicate.com/account/api-tokens

2. Set the environment variable:

export REPLICATE_API_TOKEN=r8_...

3. Use in a Pipecat pipeline:

import aiohttp
from pipecat.frames.frames import TextFrame
from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.runner import PipelineRunner
from pipecat.pipeline.task import PipelineTask
from pipecat_replicate import ReplicateImageGenService

async with aiohttp.ClientSession() as session:
    imagegen = ReplicateImageGenService(
        aiohttp_session=session,
        settings=ReplicateImageGenService.Settings(
            model="black-forest-labs/flux-schnell",
            aspect_ratio="1:1",
        ),
    )

    pipeline = Pipeline([imagegen, ...])
    task = PipelineTask(pipeline)
    await task.queue_frames([TextFrame("a cat in the style of a screenprint poster")])

    runner = PipelineRunner()
    await runner.run(task)

Configuration

Settings

Field	Type	Default	Description
model	str	"black-forest-labs/flux-schnell"	Replicate model identifier
aspect_ratio	str	"1:1"	Aspect ratio for generated images
num_outputs	int	1	Number of images to generate (1–4)
num_inference_steps	int	4	Number of denoising steps
seed	int	None	Random seed for reproducible generation
output_format	str	"webp"	Output image format
output_quality	int	80	Output quality (0–100)
disable_safety_checker	bool	False	Whether to disable the model safety check
go_fast	bool	True	Use the model's fast generation mode
megapixels	str	"1"	Approximate megapixel count

Constructor Parameters

Parameter	Type	Default	Description
aiohttp_session	aiohttp.ClientSession	(required)	HTTP session for API requests
api_token	str	$REPLICATE_API_TOKEN	Replicate API token
settings	Settings	(see defaults above)	Generation settings
base_url	str	"https://api.replicate.com/v1"	API base URL
wait_timeout_secs	int	60	Sync wait timeout (Prefer header)
poll_interval_secs	float	0.5	Poll interval for async predictions
max_poll_attempts	int	120	Maximum number of polling attempts

Examples

See examples/basic_image_gen.py for a complete example that generates an image and displays it in a Tk window.

REPLICATE_API_TOKEN=r8_... python examples/basic_image_gen.py

Running Tests

uv sync --group dev
uv run pytest

License

BSD 2-Clause — see LICENSE.