Replicate Images

Replicate image generation & prompt craft

This skill is the image layer on top of Replicate: how to call an image model from code and how to write a prompt that the specific model family actually obeys. Two competencies braided together — mechanics (run path, output handling, levers, image inputs) and prompt shape per family (Gemini/Nano-Banana wants prose, Flux wants dense description, gpt-image wants instructions). If the question is platform plumbing — auth, billing, deployments, webhooks, running an LLM or audio model — that is replicate, not this skill.

Pinned facts (verified 2026-06-02). Slugs and parameter names are the load-bearing details that make code run, and they drift — the full per-model schema lives in references/models.md so this file stays evergreen. Confirm any exact slug/param on the model page before quoting it as fact.

First move

export REPLICATE_API_TOKEN=r8_...     # both clients read this automatically
npm install replicate                  # Node; pip install replicate for Python

import Replicate from "replicate";
const replicate = new Replicate();     // reads REPLICATE_API_TOKEN from env

const output = await replicate.run("google/nano-banana-2", {
  input: { prompt: "a red ceramic mug on a sunlit wooden table, soft morning light" },
});
console.log(output[0].url());          // hosted URL of the first image

Rule: do not hand-build the token into the client — let new Replicate() read the env var. Why: a hardcoded token leaks into git and logs. Python is the same shape: replicate.run("google/nano-banana-2", input={"prompt": ...}).

Pick the model

Pick by the dominant requirement, not by hype. Full input schemas and rough cost tiers per model are in references/models.md.

Rule: for anything involving editing an existing image or merging references, start at google/nano-banana-2. Why: it is purpose-built for semantic edits and accepts many reference images, which the Flux text-to-image models do not.

The three run paths

// 1. run() — synchronous, the default. Use for interactive/script calls.
const out = await replicate.run("google/nano-banana-2", { input: { prompt } });

// 2. predictions.create + wait — when you need the full object (status, metrics, retry/cancel).
const prediction = await replicate.predictions.create({
  model: "black-forest-labs/flux-1.1-pro",
  input: { prompt },
});
const done = await replicate.wait(prediction);   // done.output, done.status, done.metrics

// 3. stream — progressive output for streaming-capable models.
for await (const event of replicate.stream("black-forest-labs/flux-dev", { input: { prompt } })) {
  process.stdout.write(event.data);              // { event, data }
}

Rule: default to run(); reach for predictions.create + wait only when you actually read status/metrics or need to cancel(). Why: run() is the low-latency path optimized for file models — the extra object is overhead you do not need for a one-shot generation.

Handling output

Since the file-output era, replicate.run returns FileOutput objects, not URL strings. Treating one as a string is the most common bug.

const output = await replicate.run("google/nano-banana-2", { input: { prompt } });

// Bad — output[0] is a FileOutput; this stringifies the object, not the image
fs.writeFileSync("out.jpg", output[0]);

// Good — read bytes via .blob(), or take the hosted link via .url()
import { writeFile } from "node:fs/promises";
const blob = await output[0].blob();
await writeFile("out.jpg", Buffer.from(await blob.arrayBuffer()));
console.log(output[0].url());                    // hosted URL if you'd rather link

output is an array even for a single image — index it. Pass useFileOutput: false to new Replicate({ useFileOutput: false }) if you want plain URL strings back instead of FileOutput.

Rule: index the array and call .blob() for bytes or .url() for the link. Why: silently coercing a FileOutput to a string writes a [object]-style repr and the corruption surfaces far from the cause.

Universal levers

const out = await replicate.run("google/nano-banana-2", {
  input: { prompt, aspect_ratio: "4:5", output_resolution: "1K", output_format: "png", seed: 42 },
});

Rule: only pass parameters that exist on the model you call. Why: Replicate rejects unknown inputs — do not copy a Flux width/height onto a call that wants aspect_ratio, and do not invent a parameter. Allowed values per model are in references/models.md.

Image-to-image & editing

Local files auto-upload, public URLs and data: URIs pass as strings. The single classic mistake is passing a bare path string for a local file — that uploads the literal text, not the bytes.

import { readFile } from "node:fs/promises";

// Bad — sends the string "./photo.jpg" as the image, not the file
await replicate.run("google/nano-banana-2", { input: { prompt, image_input: ["./photo.jpg"] } });

// Good — read the bytes (or pass a real https:// URL / data: URI string)
const photo = await readFile("./photo.jpg");
await replicate.run("google/nano-banana-2", {
  input: {
    prompt: "Remove the person on the left. Keep everything else identical.",
    image_input: [photo],            // nano-banana takes up to 14 reference images
    aspect_ratio: "match_input_image",
  },
});

For edits, write what to change and what to preserve in plain language — "keep everything else identical" is the idiom that stops the model from re-rendering the whole scene. Multi-image composition passes several references in image_input and describes how they combine. Copy-paste recipes (object removal, background swap, style transfer, 2-image composition, product shot with rendered text, character consistency) are in references/editing-recipes.md.

Rule: never pass a bare local path as an image input. Why: clients only auto-upload file/Buffer values — a string is treated as a URL or literal, and the model silently generates from nothing.

Prompt structure per family

Each family rewards a different prompt shape. Match the shape or the model "ignores" you.

Gemini / Nano-Banana — prose, not keywords

Google's formula: [Subject] + [Action] + [Location/context] + [Composition] + [Style], written as sentences. Editing is conversational and semantic. For text, put the literal string in quotes and name the font.

Bad:  cat, hat, studio, 85mm, cinematic, 8k, highly detailed, trending
Good: A ginger cat wearing a tiny red wool hat, sitting on a velvet stool in a
      softly lit studio, shot from slightly above with a shallow depth of field,
      warm cinematic color grade.

For a rendered label: Add a banner reading "SUMMER SALE" in bold condensed sans-serif across the top — quotes fix the literal text, the font name fixes the rendering. It can also translate text on request.

Flux — one dense descriptive paragraph

Flux rewards a single rich paragraph weighting subject, lighting, and lens; thin prompts get filled in by the model. Use a fixed seed to A/B prompt edits.

Bad:  a city at night, neon, rain
Good: A rain-slicked Tokyo backstreet at night, neon signage reflected in the
      puddles, a lone figure under a translucent umbrella, shot on a 35mm lens
      with shallow focus and cool teal-magenta lighting.

gpt-image — explicit instructions + constraints

Write it like a brief with hard constraints; it follows complex instructions and renders readable text well. Generate a 3-icon row on a white background; each icon flat-style, 2px stroke, evenly spaced; label them "Plan", "Build", "Ship" in a clean sans-serif.

SeeDream — multi-reference and batch phrasing

State the references and the relationship, and ask for the batch explicitly when you want a set: Using image 1 as the character and image 2 as the outfit, generate 4 sequential poses, same lighting.

Rule: do not paste a keyword soup into a Gemini/Nano-Banana call. Why: these models parse natural language; a comma-list of tags reads as noise and the model drops half of it.

Cost & latency discipline

• Resolution is the cost lever. For nano-banana, cost climbs sharply with output_resolution (roughly: 0.5K cheapest → 1K default → 2K → 4K). Iterate at 1K, render the chosen frame at 4K.
• Do not 4K every draft. A 20-iteration prompt loop at 4K can cost an order of magnitude more than the same loop at 1K for output you are about to throw away.
• Pro tier ≈ 2x Flash at the same size — reach for nano-banana-pro only when NB2 genuinely can't do the job, not by default.
• Verify live pricing on the model page before quoting a number to anyone — the figures here are order-of-magnitude and Replicate may differ from upstream Google rates.

Anti-patterns

References

• references/models.md — per-model slug, full input schema with allowed values, prompt shape, pick-when, and rough cost tier for nano-banana-2, nano-banana-pro, flux-1.1-pro / flux-dev / flux-schnell, openai/gpt-image-1, seedream-4. Header note: slugs and params drift — confirm on the model page.
• references/editing-recipes.md — copy-paste recipes (object removal, background swap, style transfer, 2-image composition, product shot with rendered text, character consistency), each as goal + model + input shape + prompt template.

scripts/verify.sh statically lints the Replicate image-calling code in your project — point it at a directory of emitted .js/.mjs/.ts/.py files (no network, no token). It checks that image slugs come from the allowlist, aspect_ratio literals are in the nano-banana set, output_resolution values are valid, and local image inputs use readFile/Buffer rather than a bare quoted path. It does not parse this skill's own Markdown fences — it scans source files, so run it where the code lands.