Home / Guides / Build

Build pipeline models locally

Build a pipeline model locally using Cog.

Pipeline models are a new kind of Replicate model that can run other Replicate models.

If you’ve never published a pipeline model before, check out the quickstart guide which will walk you through creating your first pipeline model, right in the browser without any special tools or development environment.

This guide will walk you through building a pipeline model on your own machine using Cog, and publishing it to Replicate as a hosted model. You’ll be able to run this model from the web or with a cloud API.

The pipeline model you’ll build will combine multiple existing models to generate high-quality images from a text prompt:

  1. anthropic/claude-4-sonnet will take the user’s text prompt and enhance it.
  2. black-forest-labs/flux-schnell will generate an image from the enhanced prompt.
  3. topazlabs/image-upscale will upscale the generated image to a higher resolution.

Prerequisites

To follow this guide, you’ll need:

  • An account on Replicate.
  • Docker. You’ll be using the Cog command-line tool to build and push your model. Cog uses Docker to create a container for your model. You’ll need to install and start Docker before you can run Cog. You can confirm Docker is running by typing docker info in your terminal.

Step 1: Install Cog

To develop pipeline models locally, you’ll need the cog command line tool installed locally (version 0.16.1 or higher). You can install this with Homebrew:

brew install cog

Step 2: Create a model directory

Create a directory on your computer:

mkdir my-pipeline-model
cd my-pipeline-model

Then run this command to create the necessary files:

cog init --x-pipeline

This will create the following files:

  • main.py - The main entry point for your model, where you’ll write the code that runs your model.
  • cog.yaml - The configuration file for your model.
  • requirements.txt - The Python dependencies for your model.

What are we building?

In this guide, you’ll create a pipeline model that chains together multiple existing models to generate high-quality images from a text prompt.

Your pipeline model will combine the following models:

  1. anthropic/claude-4-sonnet will take the user’s text prompt and enhance it with more vivid details, lighting, and style.
  2. black-forest-labs/flux-schnell will generate an image from the enhanced prompt.
  3. topazlabs/image-upscale will upscale the generated image to a higher resolution.

This creates a pipeline that transforms a simple text prompt into a high-quality, detailed image.

Edit the main.py file to add code that creates this pipeline model:

import replicate
from cog import Input, Path

claude = replicate.use("anthropic/claude-4-sonnet")
flux_schnell = replicate.use("black-forest-labs/flux-schnell")
topaz_upscale = replicate.use("topazlabs/image-upscale")


def run(
    prompt: str = Input(
        description="Text prompt for image generation"
    )
) -> Path:
    # Step 1: Enhance the prompt
    enhanced_prompt = claude(
        prompt=f"Enhance this image prompt with more vivid details, lighting, and style:\n\n{prompt}"
    )
    
    print(f"Original prompt: {prompt}")
    print(f"Enhanced prompt: {enhanced_prompt}")
    
    # Step 2: Generate image
    generated_image_url = flux_schnell(
        prompt=enhanced_prompt,
        aspect_ratio="1:1",
        go_fast=True,
        num_outputs=1
    )[0]
    
    print(f"Generated image URL: {generated_image_url}")
    
    # Step 3: Upscale the generated image
    upscaled_image_url = topaz_upscale(
        image=generated_image_url,
        scale=2
    )
    
    print(f"Upscaled image URL: {upscaled_image_url}")
    
    return upscaled_image_url

Step 3: Set up your environment

Your pipeline model will call other Replicate models, so you’ll need to make REPLICATE_API_TOKEN available in your environment.

To create a Replicate API token, go to replicate.com/account/api-tokens and click Create new token, then copy the token to your clipboard.

Then, set the REPLICATE_API_TOKEN environment variable in your terminal:

export REPLICATE_API_TOKEN=<your-token>

Step 4: Run your model locally

To run your model locally, use the cog predict command with the --use-replicate-token and --x-pipeline flags, as well as any additional inputs.

Note that when you run your model locally, it will make actual API calls to other models hosted on Replicate. This means you’ll be charged for the cost of running those downstream models.

cog predict --x-pipeline --use-replicate-token -i prompt="photo of a cat wearing sunglasses"

The first time you run your model, it will take a bit to download the dependencies and set up the Docker environment.

You’ll see output showing the pipeline steps:

  • The original prompt being enhanced by Claude
  • The enhanced prompt being used to generate an image with Flux Schnell
  • The generated image being upscaled by Topaz

Among the output, you should see a line that says:

Written output to: output.jpg

Open the output.jpg file:

open output.jpg

You should see a high-quality upscaled image of a cute cat! đŸ±

Step 5: Create a model on Replicate

Before you can push your pipeline model, you need to create a model page on Replicate. Visit replicate.com/create to create your new model.

Choose a name

Pick a short and memorable name for your pipeline model, like enhanced-image-generator or fancy-image-pipeline. You can use lowercase characters and dashes.

Choose an owner

If you’re working with a team, you should create your model under an organization so you and your team can share access and billing. To create an organization, click “Join or create organization” from the account menu or go to replicate.com/organizations/create.

If you’re creating a model for your own individual use, you don’t need an organization. Create it under your user account.

Choose model visibility

Next, choose whether to make your model public or private:

  • Public - Anyone can run this model and see its source code.
  • Private - Only you and collaborators (such as organization members) can see this model.

Choose model type

Next you’ll need to choose a model type. Choose Pipeline models together (CPU).

Step 6: Publish your model

To publish your model to Replicate for your development machine, you’ll use the cog command line tool.

Authenticate to Replicate by running:

cog login

Use cog push and replace <username> and <modelname> with relevant values:

cog push --x-pipeline r8.im/<username>/<modelname>

You can then run your model using the models.predictions.create endpoint on the HTTP API or by going to the model’s page on the web (https://replicate.com/<username>/<modelname>)

curl -s -X POST -H 'Prefer: wait' \
  -d '{"input": {"prompt": "a majestic dragon flying over a mountain landscape"}}' \
  -H "Authorization: Bearer $REPLICATE_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Prefer: wait' \
  https://api.replicate.com/v1/models/<username>/<modelname>/predictions

Next steps

You’ve now built and published a pipeline model from your local machine!

Next steps: