replicate-imagery

name	replicate-imagery
description	Route AI image generation and editing requests to Replicate (FLUX, Ideogram, Recraft, SDXL, imagen) via the bundled `replicate` MCP server. Use when a document, book, or report needs an illustration, hero image, character/concept art, photorealistic scene, or style-transferred image that neither Flint (data charts), Mermaid (technical diagrams), nor svg-banner (brand banners) can produce. Composes with Replicate's upstream agent skills (prompt-images, find-models, run-models, compare-models, prompt-videos) installable via `npx skills add replicate/skills`. Requires `REPLICATE_API_TOKEN`.
lastReviewed	2026-08-10T00:00:00.000Z

Replicate Imagery

Thin routing + brand-alignment skill for AI image generation and editing on Replicate. Delegates substantive prompting guidance to Replicate's upstream prompt-images skill and model discovery to the replicate MCP server. This skill is the plugin's entry point that says WHEN to reach for Replicate and HOW it composes with the plugin's other visual capabilities.

When to use this skill

You want to add a visual artifact to a doc / book / report and none of these fit:

Artifact	Not this skill — use instead
Data chart (bar, line, scatter, distribution, KPI)	flint-chart
Technical / architectural / flow diagram	markdown-mermaid (Alex_ACT_Steward baseline)
Brand banner (hero header for a doc)	svg-banner (Alex_ACT_Steward baseline)
Deterministic hand-authored figure (dataset-backed)	figure-generator
Print-quality book figure with typography grammar	print-svg-style-guide

Fires when the goal is one of:

• Illustrations — decorative or narrative images for chapters, sections, blog posts
• Hero images — top-of-page visuals for docs shared externally
• Character / concept art — figures for creative writing, book covers, brand mascots
• Photorealistic scenes — mockups, product-in-context imagery, scene composition
• Style-transferred images — restyling existing images to match a brand aesthetic
• Image editing — inpaint, background removal, upscaling, prompt-driven edits

Prerequisites

1. REPLICATE_API_TOKEN environment variable — get one at replicate.com/account/api-tokens. Set in your shell env so the MCP server picks it up:

   # PowerShell (per-session)
   $env:REPLICATE_API_TOKEN = 'r8_...'
   
   # PowerShell (persistent, user scope)
   [System.Environment]::SetEnvironmentVariable('REPLICATE_API_TOKEN', 'r8_...', 'User')
   

   # bash / zsh
   export REPLICATE_API_TOKEN=r8_...
   

   Do NOT commit the token to any config file. The plugin's shipped .vscode/mcp.json references it via ${env:REPLICATE_API_TOKEN} so it stays out of source control.

2. The replicate MCP server — run setup-illustrator-runtime once after installing or updating the plugin. It installs the reviewed replicate-mcp@0.9.0 pin through npm's configured registry; the bundled Node launcher starts it on the first Replicate tool invocation. Use setup's --check-updates mode to compare the pin with the stable dist-tag before a release.

3. Upstream Replicate skills (recommended, one-shot) — install once per project:

   npx skills add replicate/skills
   

   Pulls in five agent skills authored by Replicate covering the substantive prompting knowledge this thin skill delegates to:

   Upstream skill	What it covers
   find-models	Searching models, browsing collections, reading schemas, picking the right model
   compare-models	Evaluating by cost, speed, quality, capabilities
   run-models	Creating predictions, polling, webhooks, streaming, file handling, multi-model workflows
   prompt-images	Prompting techniques: photographic language, text rendering, style transfer, character consistency, inpainting
   prompt-videos	Prompting techniques for video: scene, camera motion, audio/dialogue, time-coded multi-shot, style control

   Update with npx skills update. Remove with .

Model selection

Replicate hosts thousands of models. Working set for illustration as of 2026-07:

Need	Recommended model	Notes
Fast, cheap illustrations	black-forest-labs/flux-schnell	Very fast, low cost; iterate freely
Higher quality, still fast	black-forest-labs/flux-dev	Balance of quality and speed
Premium quality, hero images	black-forest-labs/flux-1.1-pro or flux-1.1-pro-ultra	Premium; ultra variant supports very high resolution
Great text-in-image rendering	ideogram-ai/ideogram-v3	Best for images with readable typography (signage, quotes, labels)
Vector-style, brand-consistent	recraft-ai/recraft-v3	Cleaner, designed feel; respects color guidance well
Photorealistic scenes	google/imagen-4	Google's photorealism model
Image editing via prompt	black-forest-labs/flux-kontext-pro	Edit existing images with natural-language instructions
Inpainting (fill masked region)	black-forest-labs/flux-fill-pro	Mask + prompt → composited output
Upscaling	philz1337x/clarity-upscaler or lucataco/real-esrgan	Real-ESRGAN is the classic cheap option; Clarity has finer detail preservation
Background removal	851-labs/background-remover	Alpha channel output

Discover current models via the MCP tool: ask the agent "search Replicate for <capability> models" — the replicate MCP calls models.search under the hood and returns current results with cost, hardware, and capability metadata. Per-model page at replicate.com/<owner>/<model> shows pricing and interactive playground.

Model list evolves fast. If a recommendation here is stale, the upstream find-models skill has current model-discovery guidance and the MCP does live discovery.

Brand alignment

For illustrations that should feel on-brand with the Alex ACT constellation, weave color hex codes from the constellation's brand-palette.json into the prompt. Example:

"A minimalist illustration of a person coding at a desk, dominant color emerald #10b981 with deep slate #0f172a accents, cyan #06b6d4 highlight on the monitor, clean vector style, no text."

Per-project brands: use that project's own brand-palette.json (heirs override — see this plugin's README Brand palette section for the swatch and configuration key mapping).

Best model choices for brand-consistent output:

• recraft-ai/recraft-v3 — strongest color-guidance adherence, vector-friendly
• ideogram-ai/ideogram-v3 — respects color hints, best if the image includes readable text
• black-forest-labs/flux-* — interprets colors well but with less strict adherence

Output handling

• Default output location: assets/generated/<slug>-<timestamp>.png
• Consider adding assets/generated/ to .gitignore — ML-generated images are large and often iterative
• Keep curated finals in assets/ (not assets/generated/)
• For book / report embedding, downscale to target print DPI before committing to keep the git tree light

Cost awareness

Replicate charges per prediction. Approximate costs for image generation as of 2026-07 (verify current at replicate.com/<model>):

Model	Approx. cost per image
black-forest-labs/flux-schnell	~$0.003
black-forest-labs/flux-dev	~$0.025
black-forest-labs/flux-1.1-pro	~$0.04
ideogram-ai/ideogram-v3	~$0.09
recraft-ai/recraft-v3	~$0.04
Video models	~$0.10-$5.00 per second

Fabio's Karpathy_Loop testing (2026-07-27 user memory) spent ~$1.83 across an iteration session with multiple stock media generations. Individual illustrations are cheap; volume adds up.

Set a spending cap at replicate.com/account/billing if runaway costs are a concern.

Composition with plugin skills

• Big Idea gate first: run chart-big-idea Step 0.5 (earn-a-figure gate) before generating. Skips wasted API calls for figures that shouldn't exist.
• Verify after: run render-verify to check the generated image actually communicates what you asked for. AI-generated images fail Prose-coupling surprisingly often (prose says X, image shows Y).
• Iterate cheap, publish expensive: FLUX-schnell for iteration, FLUX-1.1-pro or Ideogram for the final.
• Style-lock for a series: for a book or multi-chapter report, lock model + seed + palette hints across figures so the visual family reads as one voice. Ideogram and Recraft handle this best.

Boundaries

• Does not itself run predictions — dispatches to the replicate MCP server which invokes the Replicate HTTP API. Requires setup-illustrator-runtime to have installed the reviewed runtime; verify with the plugin install verifier.
• Does not manage the API token — user brings their own via REPLICATE_API_TOKEN env var. If the var is unset, the MCP server fails on first invocation, not at config load.
• Does not cache or dedupe predictions — same prompt run twice = two paid predictions. Save outputs you want to keep.
• Does not select the model automatically — the agent chooses based on the prompt + this skill's recommendations. Model choice matters for both cost and quality.
• Does not do TTS, music, code generation, or LLM inference on Replicate — those are separate categories the plugin does not currently route to.

Falsifiability

Revisit by 2026-10-30 (90 days) or sooner if:

• The recommended model list is stale (≥3 models retired or superseded by newer versions)
• The upstream replicate/skills bundle changes structure such that the composition callouts here point at moved content
• Heirs consistently reach for this skill for artifact types the routing table above says NOT to use (indicates the boundary is unclear)
• Cost estimates in the table are off by >2x versus real Replicate pricing at 2026-10 recheck
• The replicate-mcp npm package moves, renames, or changes invocation shape
• Zero heir uses the skill in the observation window (parking-lot candidate — the plugin scope was wrong to activate)