pipecat-replicate 0.1.0__tar.gz

pipecat_replicate-0.1.0/.env.example

@@ -0,0 +1,5 @@
+# Replicate API token — https://replicate.com/account/api-tokens
+REPLICATE_API_TOKEN=
+
+# Required by the example (any OpenAI-compatible LLM key)
+OPENAI_API_KEY=

pipecat_replicate-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,17 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

pipecat_replicate-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,22 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv sync --group dev --python ${{ matrix.python-version }}
+      - run: uv run ruff check
+      - run: uv run ruff format --check
+      - run: uv run pytest tests/ -v

pipecat_replicate-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.env
+.venv/
+venv/
+.python-version
+uv.lock
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/

pipecat_replicate-0.1.0/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0 (2026-04-15)
+
+- Initial release
+- Support for official Replicate models (`owner/name`) and versioned models (`owner/name:version`)
+- Sync prediction requests with polling fallback
+- Returns `URLImageRawFrame` on success
+- Metrics support via `start_ttfb_metrics` / `stop_ttfb_metrics`
+- Tested with Pipecat v0.0.108

pipecat_replicate-0.1.0/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, Borislav Novikov
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pipecat_replicate-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: pipecat-replicate
+Version: 0.1.0
+Summary: Replicate image generation integration for Pipecat
+Project-URL: Repository, https://github.com/bnovik0v/pipecat-replicate
+Project-URL: Issues, https://github.com/bnovik0v/pipecat-replicate/issues
+Author-email: Borislav Novikov <borislav@polaro.com>
+License-Expression: BSD-2-Clause
+License-File: LICENSE
+Requires-Python: <3.14,>=3.10
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: loguru>=0.7
+Requires-Dist: pillow>=10.0
+Requires-Dist: pipecat-ai>=0.0.108
+Description-Content-Type: text/markdown
+
+# pipecat-replicate
+
+[Replicate](https://replicate.com/) image generation integration for [Pipecat](https://github.com/pipecat-ai/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
+
+```bash
+pip install pipecat-replicate
+```
+
+### Using uv
+
+```bash
+uv add pipecat-replicate
+```
+
+### From source
+
+```bash
+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:
+
+```bash
+export REPLICATE_API_TOKEN=r8_...
+```
+
+3. Use in a Pipecat pipeline:
+
+```python
+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`](examples/basic_image_gen.py) for a complete example that generates an image and displays it in a Tk window.
+
+```bash
+REPLICATE_API_TOKEN=r8_... python examples/basic_image_gen.py
+```
+
+## Running Tests
+
+```bash
+uv sync --group dev
+uv run pytest
+```
+
+## License
+
+BSD 2-Clause — see [LICENSE](LICENSE).

pipecat_replicate-0.1.0/README.md

@@ -0,0 +1,122 @@
+# pipecat-replicate
+
+[Replicate](https://replicate.com/) image generation integration for [Pipecat](https://github.com/pipecat-ai/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
+
+```bash
+pip install pipecat-replicate
+```
+
+### Using uv
+
+```bash
+uv add pipecat-replicate
+```
+
+### From source
+
+```bash
+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:
+
+```bash
+export REPLICATE_API_TOKEN=r8_...
+```
+
+3. Use in a Pipecat pipeline:
+
+```python
+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`](examples/basic_image_gen.py) for a complete example that generates an image and displays it in a Tk window.
+
+```bash
+REPLICATE_API_TOKEN=r8_... python examples/basic_image_gen.py
+```
+
+## Running Tests
+
+```bash
+uv sync --group dev
+uv run pytest
+```
+
+## License
+
+BSD 2-Clause — see [LICENSE](LICENSE).

pipecat_replicate-0.1.0/examples/basic_image_gen.py

@@ -0,0 +1,70 @@
+"""Basic Replicate image generation example with Pipecat.
+
+Generates an image using the Replicate API and displays it in a Tk window.
+
+Requirements:
+    pip install pipecat-replicate pipecat-ai[local]
+
+Environment variables:
+    REPLICATE_API_TOKEN  — your Replicate API token
+"""
+
+import asyncio
+import os
+import sys
+import tkinter as tk
+
+import aiohttp
+from dotenv import load_dotenv
+from loguru import logger
+
+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.transports.local.tk import TkLocalTransport, TkTransportParams
+from pipecat_replicate import ReplicateImageGenService
+
+load_dotenv(override=True)
+
+logger.remove(0)
+logger.add(sys.stderr, level="DEBUG")
+
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        tk_root = tk.Tk()
+        tk_root.title("Replicate Image Gen")
+
+        transport = TkLocalTransport(
+            tk_root,
+            TkTransportParams(video_out_enabled=True, video_out_width=1024, video_out_height=1024),
+        )
+
+        imagegen = ReplicateImageGenService(
+            settings=ReplicateImageGenService.Settings(
+                model="black-forest-labs/flux-schnell",
+                aspect_ratio="1:1",
+            ),
+            aiohttp_session=session,
+            api_token=os.getenv("REPLICATE_API_TOKEN"),
+        )
+
+        pipeline = Pipeline([imagegen, transport.output()])
+
+        task = PipelineTask(pipeline)
+        await task.queue_frames([TextFrame("a cat in the style of a screenprint poster")])
+
+        runner = PipelineRunner()
+
+        async def run_tk():
+            while not task.has_finished():
+                tk_root.update()
+                tk_root.update_idletasks()
+                await asyncio.sleep(0.1)
+
+        await asyncio.gather(runner.run(task), run_tk())
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

pipecat_replicate-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pipecat-replicate"
+version = "0.1.0"
+description = "Replicate image generation integration for Pipecat"
+readme = "README.md"
+license = "BSD-2-Clause"
+authors = [
+    { name = "Borislav Novikov", email = "borislav@polaro.com" },
+]
+requires-python = ">=3.10,<3.14"
+dependencies = [
+    "pipecat-ai>=0.0.108",
+    "aiohttp>=3.9",
+    "loguru>=0.7",
+    "Pillow>=10.0",
+]
+
+[project.urls]
+Repository = "https://github.com/bnovik0v/pipecat-replicate"
+Issues = "https://github.com/bnovik0v/pipecat-replicate/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "pytest-aiohttp>=1.0",
+    "ruff>=0.4",
+    "websockets>=13.0",
+]
+
+[tool.ruff]
+line-length = 100
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

pipecat_replicate-0.1.0/src/pipecat_replicate/__init__.py

@@ -0,0 +1,5 @@
+"""Replicate image generation integration for Pipecat."""
+
+from pipecat_replicate.image import ReplicateImageGenService, ReplicateImageGenSettings
+
+__all__ = ["ReplicateImageGenService", "ReplicateImageGenSettings"]

pipecat_replicate-0.1.0/src/pipecat_replicate/image.py

@@ -0,0 +1,356 @@
+"""Replicate image generation service implementation.
+
+This module provides integration with Replicate-hosted image generation models
+for creating images from text prompts.
+"""
+
+import asyncio
+import base64
+import io
+import os
+from dataclasses import dataclass, field
+from typing import Any, AsyncGenerator, Dict, Optional
+
+import aiohttp
+from loguru import logger
+from PIL import Image
+from pydantic import BaseModel, Field
+
+from pipecat.frames.frames import ErrorFrame, Frame, URLImageRawFrame
+from pipecat.services.image_service import ImageGenService
+from pipecat.services.settings import NOT_GIVEN, ImageGenSettings, _NotGiven
+
+
+@dataclass
+class ReplicateImageGenSettings(ImageGenSettings):
+    """Settings for the Replicate image generation service.
+
+    Parameters:
+        model: Replicate model identifier. Use ``owner/name`` for official
+            models or ``owner/name:version`` for versioned community models.
+        aspect_ratio: Aspect ratio for generated images.
+        num_outputs: Number of images to generate.
+        num_inference_steps: Number of denoising steps for the model.
+        seed: Random seed for reproducible generation. ``None`` uses a random seed.
+        output_format: Image format requested from the model.
+        output_quality: Output quality value supported by the model.
+        disable_safety_checker: Whether to disable the model safety checker.
+        go_fast: Whether to use the model's faster generation mode.
+        megapixels: Approximate megapixel count for generated images.
+    """
+
+    aspect_ratio: str | _NotGiven = field(default_factory=lambda: NOT_GIVEN)
+    num_outputs: int | _NotGiven = field(default_factory=lambda: NOT_GIVEN)
+    num_inference_steps: int | _NotGiven = field(default_factory=lambda: NOT_GIVEN)
+    seed: int | None | _NotGiven = field(default_factory=lambda: NOT_GIVEN)
+    output_format: str | _NotGiven = field(default_factory=lambda: NOT_GIVEN)
+    output_quality: int | _NotGiven = field(default_factory=lambda: NOT_GIVEN)
+    disable_safety_checker: bool | _NotGiven = field(default_factory=lambda: NOT_GIVEN)
+    go_fast: bool | _NotGiven = field(default_factory=lambda: NOT_GIVEN)
+    megapixels: str | _NotGiven = field(default_factory=lambda: NOT_GIVEN)
+
+    def to_api_input(self) -> Dict[str, Any]:
+        """Build the Replicate input payload from settings."""
+        payload: Dict[str, Any] = {
+            "aspect_ratio": self.aspect_ratio,
+            "num_outputs": self.num_outputs,
+            "num_inference_steps": self.num_inference_steps,
+            "output_format": self.output_format,
+            "output_quality": self.output_quality,
+            "disable_safety_checker": self.disable_safety_checker,
+            "go_fast": self.go_fast,
+            "megapixels": self.megapixels,
+        }
+        if self.seed is not None:
+            payload["seed"] = self.seed
+        payload.update(self.extra)
+        return payload
+
+
+class ReplicateImageGenService(ImageGenService):
+    """Replicate image generation service.
+
+    Provides text-to-image generation using Replicate-hosted models. Official
+    models use an ``owner/name`` identifier. Versioned community models can be
+    addressed with ``owner/name:version``.
+    """
+
+    Settings = ReplicateImageGenSettings
+    _settings: Settings
+
+    class InputParams(BaseModel):
+        """Input parameters for Replicate image generation.
+
+        .. deprecated:: 0.1.0
+            Use ``settings=ReplicateImageGenService.Settings(...)`` instead.
+
+        Parameters:
+            aspect_ratio: Aspect ratio for generated images. Defaults to ``"1:1"``.
+            num_outputs: Number of images to generate. Defaults to ``1``.
+            num_inference_steps: Number of denoising steps. Defaults to ``4``.
+            seed: Random seed for reproducible generation. Defaults to ``None``.
+            output_format: Output image format. Defaults to ``"webp"``.
+            output_quality: Output quality value. Defaults to ``80``.
+            disable_safety_checker: Whether to disable the safety checker. Defaults to ``False``.
+            go_fast: Whether to use the fast model path. Defaults to ``True``.
+            megapixels: Approximate megapixel count. Defaults to ``"1"``.
+        """
+
+        aspect_ratio: str = "1:1"
+        num_outputs: int = Field(default=1, ge=1, le=4)
+        num_inference_steps: int = Field(default=4, ge=1)
+        seed: Optional[int] = None
+        output_format: str = "webp"
+        output_quality: int = Field(default=80, ge=0, le=100)
+        disable_safety_checker: bool = False
+        go_fast: bool = True
+        megapixels: str = "1"
+
+    _TERMINAL_ERROR_STATUSES = {"failed", "canceled", "cancelled"}
+
+    def __init__(
+        self,
+        *,
+        params: Optional[InputParams] = None,
+        aiohttp_session: aiohttp.ClientSession,
+        api_token: Optional[str] = None,
+        model: Optional[str] = None,
+        settings: Optional[Settings] = None,
+        base_url: str = "https://api.replicate.com/v1",
+        wait_timeout_secs: int = 60,
+        poll_interval_secs: float = 0.5,
+        max_poll_attempts: int = 120,
+        **kwargs,
+    ):
+        """Initialize the ReplicateImageGenService.
+
+        Args:
+            params: Input parameters for image generation configuration.
+
+                .. deprecated:: 0.1.0
+                    Use ``settings=ReplicateImageGenService.Settings(...)`` instead.
+
+            aiohttp_session: HTTP client session for Replicate requests and image downloads.
+            api_token: Optional Replicate API token. If provided, sets the
+                ``REPLICATE_API_TOKEN`` environment variable.
+            model: Replicate model identifier. Defaults to
+                ``"black-forest-labs/flux-schnell"``.
+
+                .. deprecated:: 0.1.0
+                    Use ``settings=ReplicateImageGenService.Settings(model=...)`` instead.
+
+            settings: Runtime-configurable generation settings. When provided
+                alongside deprecated parameters, ``settings`` values take precedence.
+            base_url: Base URL for the Replicate HTTP API.
+            wait_timeout_secs: Sync wait duration passed in the ``Prefer`` header.
+            poll_interval_secs: Poll interval used when the initial sync request
+                returns before output is available.
+            max_poll_attempts: Maximum number of follow-up prediction polls.
+            **kwargs: Additional arguments passed to parent ImageGenService.
+        """
+        default_settings = self.Settings(
+            model="black-forest-labs/flux-schnell",
+            aspect_ratio="1:1",
+            num_outputs=1,
+            num_inference_steps=4,
+            seed=None,
+            output_format="webp",
+            output_quality=80,
+            disable_safety_checker=False,
+            go_fast=True,
+            megapixels="1",
+        )
+
+        if model is not None:
+            self._warn_init_param_moved_to_settings("model", "model")
+            default_settings.model = model
+
+        if params is not None:
+            self._warn_init_param_moved_to_settings("params")
+            if not settings:
+                default_settings.aspect_ratio = params.aspect_ratio
+                default_settings.num_outputs = params.num_outputs
+                default_settings.num_inference_steps = params.num_inference_steps
+                default_settings.seed = params.seed
+                default_settings.output_format = params.output_format
+                default_settings.output_quality = params.output_quality
+                default_settings.disable_safety_checker = params.disable_safety_checker
+                default_settings.go_fast = params.go_fast
+                default_settings.megapixels = params.megapixels
+
+        if settings is not None:
+            default_settings.apply_update(settings)
+
+        super().__init__(settings=default_settings, **kwargs)
+        self._aiohttp_session = aiohttp_session
+        self._api_token = api_token or os.getenv("REPLICATE_API_TOKEN", "")
+        self._base_url = base_url.rstrip("/")
+        self._wait_timeout_secs = wait_timeout_secs
+        self._poll_interval_secs = poll_interval_secs
+        self._max_poll_attempts = max_poll_attempts
+        if api_token:
+            os.environ["REPLICATE_API_TOKEN"] = api_token
+
+    def _prediction_request(self, prompt: str) -> tuple[str, dict[str, str], dict[str, Any]]:
+        """Build the Replicate prediction URL, headers, and request body."""
+        model = self._settings.model or ""
+        if "/" not in model:
+            raise ValueError("Replicate model must use 'owner/name' or 'owner/name:version' format")
+
+        input_payload = {"prompt": prompt, **self._settings.to_api_input()}
+        headers = {
+            "Authorization": f"Bearer {self._api_token}",
+            "Content-Type": "application/json",
+            "Prefer": f"wait={self._wait_timeout_secs}",
+        }
+
+        if ":" in model:
+            _, version = model.rsplit(":", maxsplit=1)
+            if not version:
+                raise ValueError("Versioned Replicate models must use 'owner/name:version' format")
+            return (
+                f"{self._base_url}/predictions",
+                headers,
+                {"version": version, "input": input_payload},
+            )
+
+        owner, name = model.split("/", maxsplit=1)
+        return (
+            f"{self._base_url}/models/{owner}/{name}/predictions",
+            headers,
+            {"input": input_payload},
+        )
+
+    def _extract_output_urls(self, prediction: Dict[str, Any]) -> list[str]:
+        """Extract output URLs from a Replicate prediction response."""
+        output = prediction.get("output")
+        if output is None:
+            return []
+        if isinstance(output, str):
+            return [output]
+        if isinstance(output, dict):
+            url = output.get("url")
+            return [url] if isinstance(url, str) else []
+
+        urls: list[str] = []
+        if isinstance(output, list):
+            for item in output:
+                if isinstance(item, str):
+                    urls.append(item)
+                elif isinstance(item, dict) and isinstance(item.get("url"), str):
+                    urls.append(item["url"])
+        return urls
+
+    async def _poll_prediction(
+        self,
+        prediction: Dict[str, Any],
+        headers: Dict[str, str],
+        *,
+        fallback_url: str | None,
+    ) -> Dict[str, Any]:
+        """Poll the prediction endpoint until output is available or it fails."""
+        output_urls = self._extract_output_urls(prediction)
+        if output_urls:
+            return prediction
+
+        prediction_url = prediction.get("urls", {}).get("get") or fallback_url
+
+        for _ in range(self._max_poll_attempts):
+            status = str(prediction.get("status", "")).lower()
+            if status in self._TERMINAL_ERROR_STATUSES:
+                error = prediction.get("error") or "prediction failed"
+                raise RuntimeError(f"Replicate prediction failed: {error}")
+
+            if not prediction_url:
+                return prediction
+
+            await asyncio.sleep(self._poll_interval_secs)
+            async with self._aiohttp_session.get(prediction_url, headers=headers) as response:
+                if response.status != 200:
+                    error_text = await response.text()
+                    raise RuntimeError(f"Replicate polling error ({response.status}): {error_text}")
+                prediction = await response.json()
+                output_urls = self._extract_output_urls(prediction)
+                if output_urls:
+                    return prediction
+
+        raise TimeoutError("Replicate image generation timed out while waiting for output")
+
+    @staticmethod
+    def _load_image_frame(image_url: str | None, encoded_image: bytes) -> URLImageRawFrame:
+        """Decode image bytes and build a Pipecat image frame."""
+        image = Image.open(io.BytesIO(encoded_image))
+        return URLImageRawFrame(
+            url=image_url,
+            image=image.tobytes(),
+            size=image.size,
+            format=image.format,
+        )
+
+    @staticmethod
+    def _decode_data_url(data_url: str) -> bytes:
+        """Decode a ``data:`` URL into raw bytes."""
+        _, _, data = data_url.partition(",")
+        if not data:
+            raise ValueError("Replicate returned an invalid data URL")
+        return base64.b64decode(data)
+
+    async def run_image_gen(self, prompt: str) -> AsyncGenerator[Frame, None]:
+        """Generate images from a text prompt using Replicate.
+
+        Args:
+            prompt: The text prompt to generate images from.
+
+        Yields:
+            URLImageRawFrame: Frame containing generated image data and metadata.
+            ErrorFrame: If image generation fails.
+        """
+        logger.debug(f"Generating image from prompt with Replicate: {prompt}")
+        await self.start_ttfb_metrics()
+
+        try:
+            url, headers, payload = self._prediction_request(prompt)
+            async with self._aiohttp_session.post(url, json=payload, headers=headers) as response:
+                if response.status not in {200, 201}:
+                    error_text = await response.text()
+                    await self.stop_ttfb_metrics()
+                    yield ErrorFrame(error=f"Replicate API error ({response.status}): {error_text}")
+                    return
+                prediction = await response.json()
+                fallback_url = response.headers.get("Location")
+
+            prediction = await self._poll_prediction(
+                prediction,
+                headers={"Authorization": headers["Authorization"]},
+                fallback_url=fallback_url,
+            )
+
+            output_urls = self._extract_output_urls(prediction)
+            if not output_urls:
+                await self.stop_ttfb_metrics()
+                yield ErrorFrame("Replicate image generation failed: no output returned")
+                return
+
+            await self.stop_ttfb_metrics()
+
+            for image_url in output_urls:
+                if image_url.startswith("data:"):
+                    encoded_image = self._decode_data_url(image_url)
+                else:
+                    async with self._aiohttp_session.get(image_url) as response:
+                        if response.status != 200:
+                            error_text = await response.text()
+                            yield ErrorFrame(
+                                error=(
+                                    f"Replicate image download error"
+                                    f" ({response.status}): {error_text}"
+                                )
+                            )
+                            continue
+                        encoded_image = await response.read()
+
+                frame = await asyncio.to_thread(self._load_image_frame, image_url, encoded_image)
+                yield frame
+
+        except Exception as e:
+            yield ErrorFrame(f"Replicate image generation error: {e}")

pipecat_replicate-0.1.0/tests/test_replicate_image.py

@@ -0,0 +1,202 @@
+"""Tests for ReplicateImageGenService."""
+
+import io
+
+import aiohttp
+import pytest
+from aiohttp import web
+from PIL import Image
+
+from pipecat.frames.frames import ErrorFrame, TextFrame, URLImageRawFrame
+from pipecat.tests.utils import run_test
+from pipecat_replicate import ReplicateImageGenService
+
+
+def _make_test_image_bytes(format: str = "PNG") -> bytes:
+    image = Image.new("RGB", (2, 2), color=(255, 0, 0))
+    buffer = io.BytesIO()
+    image.save(buffer, format=format)
+    return buffer.getvalue()
+
+
+@pytest.mark.asyncio
+async def test_run_replicate_image_success_official_model(aiohttp_client):
+    """Official Replicate models should return image frames from sync predictions."""
+
+    image_bytes = _make_test_image_bytes()
+
+    async def prediction_handler(request):
+        assert request.headers["Authorization"] == "Bearer test-token"
+        assert request.headers["Prefer"] == "wait=60"
+        payload = await request.json()
+        assert payload["input"]["prompt"] == "a red square"
+        assert payload["input"]["aspect_ratio"] == "1:1"
+        return web.json_response(
+            {
+                "status": "processing",
+                "output": [str(request.url.with_path("/image.png"))],
+                "urls": {"get": str(request.url.with_path("/prediction-status"))},
+            }
+        )
+
+    async def image_handler(_request):
+        return web.Response(body=image_bytes, content_type="image/png")
+
+    app = web.Application()
+    app.router.add_post("/v1/models/black-forest-labs/flux-schnell/predictions", prediction_handler)
+    app.router.add_get("/image.png", image_handler)
+    client = await aiohttp_client(app)
+    base_url = str(client.make_url("/v1")).rstrip("/")
+
+    async with aiohttp.ClientSession() as session:
+        image_gen = ReplicateImageGenService(
+            aiohttp_session=session,
+            api_token="test-token",
+            base_url=base_url,
+        )
+
+        down_frames, up_frames = await run_test(
+            image_gen, frames_to_send=[TextFrame("a red square")]
+        )
+
+        assert not up_frames
+        assert isinstance(down_frames[0], TextFrame)
+        assert isinstance(down_frames[1], URLImageRawFrame)
+        assert down_frames[1].size == (2, 2)
+        assert down_frames[1].format == "PNG"
+
+
+@pytest.mark.asyncio
+async def test_run_replicate_image_success_versioned_model(aiohttp_client):
+    """Versioned community models should use the generic predictions endpoint."""
+
+    image_bytes = _make_test_image_bytes()
+    version = "53d5d1586a229bd033e060941789bfb0c177cefd5ef638f34b3099658343a897"
+
+    async def prediction_handler(request):
+        payload = await request.json()
+        assert payload["version"] == version
+        assert payload["input"]["prompt"] == "a blue square"
+        return web.json_response(
+            {
+                "status": "successful",
+                "output": [str(request.url.with_path("/image-versioned.png"))],
+            }
+        )
+
+    async def image_handler(_request):
+        return web.Response(body=image_bytes, content_type="image/png")
+
+    app = web.Application()
+    app.router.add_post("/v1/predictions", prediction_handler)
+    app.router.add_get("/image-versioned.png", image_handler)
+    client = await aiohttp_client(app)
+    base_url = str(client.make_url("/v1")).rstrip("/")
+
+    async with aiohttp.ClientSession() as session:
+        image_gen = ReplicateImageGenService(
+            aiohttp_session=session,
+            api_token="test-token",
+            base_url=base_url,
+            settings=ReplicateImageGenService.Settings(
+                model=f"black-forest-labs/flux-schnell:{version}",
+                aspect_ratio="1:1",
+                num_outputs=1,
+                num_inference_steps=4,
+                seed=None,
+                output_format="webp",
+                output_quality=80,
+                disable_safety_checker=False,
+                go_fast=True,
+                megapixels="1",
+            ),
+        )
+
+        down_frames, up_frames = await run_test(
+            image_gen, frames_to_send=[TextFrame("a blue square")]
+        )
+
+        assert not up_frames
+        assert isinstance(down_frames[1], URLImageRawFrame)
+
+
+@pytest.mark.asyncio
+async def test_run_replicate_image_polls_when_sync_response_has_no_output(aiohttp_client):
+    """The service should poll the prediction URL if sync mode returns early."""
+
+    image_bytes = _make_test_image_bytes()
+    poll_count = 0
+
+    async def prediction_handler(request):
+        return web.json_response(
+            {
+                "status": "processing",
+                "output": None,
+                "urls": {"get": str(request.url.with_path("/v1/predictions/test-id"))},
+            }
+        )
+
+    async def prediction_status_handler(request):
+        nonlocal poll_count
+        poll_count += 1
+        return web.json_response(
+            {
+                "status": "processing",
+                "output": [str(request.url.with_path("/image-polled.png"))],
+            }
+        )
+
+    async def image_handler(_request):
+        return web.Response(body=image_bytes, content_type="image/png")
+
+    app = web.Application()
+    app.router.add_post("/v1/models/black-forest-labs/flux-schnell/predictions", prediction_handler)
+    app.router.add_get("/v1/predictions/test-id", prediction_status_handler)
+    app.router.add_get("/image-polled.png", image_handler)
+    client = await aiohttp_client(app)
+    base_url = str(client.make_url("/v1")).rstrip("/")
+
+    async with aiohttp.ClientSession() as session:
+        image_gen = ReplicateImageGenService(
+            aiohttp_session=session,
+            api_token="test-token",
+            base_url=base_url,
+            poll_interval_secs=0.001,
+            max_poll_attempts=2,
+        )
+
+        down_frames, up_frames = await run_test(image_gen, frames_to_send=[TextFrame("poll me")])
+
+        assert not up_frames
+        assert poll_count == 1
+        assert isinstance(down_frames[1], URLImageRawFrame)
+
+
+@pytest.mark.asyncio
+async def test_run_replicate_image_error(aiohttp_client):
+    """Non-success responses should propagate an ErrorFrame upstream."""
+
+    async def prediction_handler(_request):
+        return web.Response(status=401, text="unauthorized")
+
+    app = web.Application()
+    app.router.add_post("/v1/models/black-forest-labs/flux-schnell/predictions", prediction_handler)
+    client = await aiohttp_client(app)
+    base_url = str(client.make_url("/v1")).rstrip("/")
+
+    async with aiohttp.ClientSession() as session:
+        image_gen = ReplicateImageGenService(
+            aiohttp_session=session,
+            api_token="bad-token",
+            base_url=base_url,
+        )
+
+        down_frames, up_frames = await run_test(
+            image_gen,
+            frames_to_send=[TextFrame("this should fail")],
+        )
+
+        assert isinstance(down_frames[0], TextFrame)
+        assert len(up_frames) == 1
+        assert isinstance(up_frames[0], ErrorFrame)
+        assert "401" in up_frames[0].error