Replicate

Image generation service implementation using Replicate-hosted models

Overview

ReplicateImageGenService generates images from text prompts using models hosted on Replicate, such as black-forest-labs/flux-schnell. Any text-to-image model available on Replicate can be used by setting the model parameter.

Source Repository

Source code, examples, and issues for the Replicate integration

PyPI Package

The pipecat-replicate package on PyPI

Replicate Models

Browse text-to-image models available on Replicate

API Tokens

Create and manage your Replicate API tokens

Installation

This is a community-maintained package distributed separately from pipecat-ai:

uv add pipecat-replicate

Prerequisites

Replicate Account Setup

Before using the Replicate image generation service, you need:

1. Replicate Account: Sign up at Replicate
2. API Token: Create a token from your account settings

Required Environment Variables

• REPLICATE_API_TOKEN: Your Replicate API token for authentication

Configuration

aiohttp_session · aiohttp.ClientSession · required

HTTP client session used for Replicate API requests and image downloads.

api_token · str · default: "None"

Replicate API token. Falls back to the REPLICATE_API_TOKEN environment variable if not provided.

settings · ReplicateImageGenService.Settings · default: "None"

Runtime-configurable generation settings. See Settings below.

base_url · str · default: "https://api.replicate.com/v1"

Base URL for the Replicate API.

wait_timeout_secs · int · default: "60"

Sync wait duration passed in the Replicate Prefer header.

poll_interval_secs · float · default: "0.5"

How often to poll Replicate for prediction status.

max_poll_attempts · int · default: "120"

Maximum number of polling attempts before giving up.

Settings

Runtime-configurable settings passed via the settings constructor argument using ReplicateImageGenService.Settings(...).

Parameter	Type	Default	Description
model	str	"black-forest-labs/flux-schnell"	Replicate model identifier. Use owner/name, or owner/name:version.
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. None uses a random seed.
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 checker.
go_fast	bool	True	Use the model’s faster generation mode.
megapixels	str	"1"	Approximate megapixel count for generated images.

Available parameters and defaults are defined by the integration and the selected Replicate model. See the source repository for the authoritative, up-to-date list.

Usage

import aiohttp
from pipecat_replicate import ReplicateImageGenService
from pipecat.frames.frames import TextFrame

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

    # ... add image_gen to your pipeline, then queue a prompt:
    await task.queue_frames(
        [TextFrame("a cat in the style of a screenprint poster")]
    )

Compatibility

Tested with Pipecat v0.0.108. Check the source repository for the latest tested version and changelog.