How to Integrate Replicate with Your Headless CMS

What is Replicate?

Replicate is a hosted platform for running machine learning models through an API, including image generation, video generation, audio processing, embeddings, and language models. Developers use it to run open-source models without managing GPUs, model weights, or inference infrastructure. Its API, SDKs, and webhook support make it a practical fit for production AI workflows tied to content events.

Why integrate Replicate with a headless CMS?

AI content workflows usually break down at the handoff. An editor publishes a product page, then someone copies the title, description, and brand rules into a separate AI tool, waits for an output, downloads a file, uploads it somewhere else, and pastes the result back into the content entry. That might work for 10 pages. It doesn't work for 10,000 SKUs, 40 locales, or a media team publishing daily campaigns.

Connecting Replicate to a headless CMS lets content events call models automatically. A recipe page can generate a social image. A product description can trigger a background-removal model. A travel article can generate alt text, a hero image, or short-form video prompts. The important part is structure. If your content is typed JSON with fields like title, locale, category, prompt, imageStyle, and sourceAsset, Replicate gets clean inputs. No HTML scraping. No guessing which paragraph is the product summary.

With Sanity, content lives in the Content Lake as structured JSON, and webhooks can fire the moment a document is published, updated, or deleted. GROQ selects only the fields Replicate needs, including referenced fields like brand tone or image style. Functions can run the server-side call to Replicate without a separate queue worker or cron job. The trade-off is that you still need to design the workflow carefully. Long-running video models, rate limits, cost controls, retries, and human review states all need a place in your schema.

Architecture overview

A typical Sanity and Replicate integration starts when an editor publishes a document in Sanity Studio, for example a product, article, recipe, or campaign. A Sanity webhook listens for publish events, often filtered with GROQ so it only fires for documents that need AI generation, such as `*[_type == "article" && generateHeroImage == true]`. The webhook sends the document ID to a server-side handler or a Sanity Function. That handler uses `@sanity/client` to fetch the exact fields from the Content Lake with GROQ, such as title, summary, locale, image prompt, brand style, and referenced taxonomy data. It then calls Replicate with the official SDK, usually by running a model like `black-forest-labs/flux-schnell` for image generation, an upscaler, a background-removal model, or another model published on Replicate. Replicate returns output such as image URLs, prediction IDs, logs, or status updates. Your handler can write the result back to the original Sanity document, attach generated asset metadata, set a status like `aiImageStatus: "ready"`, or route the item into an editorial review state. From there, the same structured document can power the website, mobile app, preview experience, AI agent, or campaign feed.

Common use cases

Step-by-step integration

1. 1

   Create a Replicate account and API token

   Sign in to Replicate, create an API token from your account settings, and add it to your server environment as `REPLICATE_API_TOKEN`. For a TypeScript app or function, install the SDK with `npm install replicate`.

2. 2

   Model the workflow in Sanity Studio

   Add fields that make the AI workflow explicit, such as `aiPrompt`, `generateHeroImage`, `aiImageStatus`, `replicatePredictionId`, and `generatedImageUrls`. For review workflows, use statuses like `draft`, `generating`, `ready`, `approved`, and `rejected`.

3. 3

   Create a publish trigger

   Set up a Sanity webhook or Function that runs only when relevant content changes. Use a GROQ filter so a recipe image workflow doesn't fire for every author, category, or settings update.

4. 4

   Fetch structured inputs with GROQ

   In your handler, use `@sanity/client` to fetch the document and referenced fields Replicate needs. For example, pull the article title, excerpt, locale, prompt field, and image style reference in one query.

5. 5

   Call Replicate and save the result

   Run the selected Replicate model with the official SDK. Save the output URL, prediction ID, status, and any useful metadata back to Sanity so editors can approve or retry the result.

6. 6

   Test the frontend and review states

   Publish a test document, confirm the webhook fires once, check Replicate logs, and verify that your frontend handles `generating`, `ready`, and `failed` states without showing broken media.

Code example

import {createClient} from '@sanity/client'
import Replicate from 'replicate'

const sanity = createClient({
  projectId: process.env.SANITY_PROJECT_ID!,
  dataset: process.env.SANITY_DATASET!,
  apiVersion: '2025-02-19',
  token: process.env.SANITY_WRITE_TOKEN!,
  useCdn: false,
})

const replicate = new Replicate({auth: process.env.REPLICATE_API_TOKEN!})

export async function POST(req: Request) {
  const {_id} = await req.json()

  const doc = await sanity.fetch(`*[_id == $id][0]{
    _id,
    title,
    "prompt": aiPrompt,
    "style": imageStyle->label
  }`, {id: _id})

  if (!doc?.prompt) return Response.json({skipped: true})

  await sanity.patch(doc._id).set({aiImageStatus: 'generating'}).commit()

  const output = await replicate.run('black-forest-labs/flux-schnell', {
    input: {
      prompt: `${doc.prompt}. Style: ${doc.style ?? 'editorial photo'}`,
      num_outputs: 1,
    },
  })

  await sanity.patch(doc._id).set({
    aiImageStatus: 'ready',
    generatedImageUrls: output,
  }).commit()

  return Response.json({ok: true})
}

How Sanity + Replicate works

CMS approaches to Replicate

Keep building

Explore related integrations to complete your content stack.