Replicate Local Workflow

Replicate local workflow

Use Replicate's official skills for model-specific work. This skill adds the local workflow around them: planning batches, preserving prediction records, downloading every output, naming files, embedding image metadata, reviewing candidates, and archiving results.

Before running

1. Confirm the requested output directory. If none was given, use outputs/<concise-task-slug>/ under the current project.
2. Confirm the model, prompt or inputs, output count, format, and any cost or quality constraint that is unclear.
3. Show the user the prompts and batch plan before creating predictions when the task is exploratory, expensive, or asks for multiple variants.
4. Check that REPLICATE_API_TOKEN exists without printing its value.
5. Load the relevant installed Replicate skills:
   • find-models to search and inspect schemas
   • compare-models to evaluate candidates
   • run-models to create and monitor predictions
   • prompt-images or prompt-videos for media prompting
6. If those skills are unavailable, install them globally with:

npx skills add replicate/skills --global --all --yes

Always fetch the current model schema before constructing inputs. Request JPG with the model's supported output_format, format, or equivalent input when available. Do not invent a format input that is absent from the schema.

Prefer MCP Code Mode

When the local Replicate MCP Code Mode tools are already available, prefer them for workflows involving several API calls. Use the MCP documentation-search tool first, then its TypeScript execution tool. Code Mode can create predictions concurrently, poll them, and return only compact prediction records and output URLs.

Do not block the task to configure Code Mode unless the user asks. Fall back to the Replicate skills and HTTP API when it is unavailable.

Current local server command:

npx -y replicate-mcp@alpha --tools=code

It requires Node.js, Deno, and REPLICATE_API_TOKEN. It is experimental, so search its current SDK documentation rather than relying on remembered method names.

Run predictions

• Create independent predictions concurrently. Never create one, wait for it, and then create the next.
• Use Promise.all or an equivalent bounded concurrent batch. Replicate can accept parallel predictions.
• For large or slow batches, cap local polling concurrency when needed, but do not serialize prediction creation.
• Log each prediction ID immediately after creation so work can be recovered if the process exits.
• Poll each prediction to a terminal state: succeeded, failed, or canceled.
• Download successful outputs as each prediction finishes. Replicate output URLs expire.
• Make long-running scripts resumable. Skip outputs whose prediction record and local file already exist.
• Retry only failed or missing slots. Record the replacement prediction separately.
• Save the one-off generation script when a batch is substantial or likely to be rerun.

For deterministic media operations such as conversion, resizing, concatenation, reversing, or contact sheets, prefer local tools such as FFmpeg or ImageMagick over another prediction.

Save prediction records and outputs

Use this structure unless the project already has a stronger convention:

outputs/<task-slug>/
├── predictions/        # complete prediction JSON, one file per prediction ID
├── files/              # downloaded outputs
├── scripts/            # one-off batch scripts when useful
├── manifest-001.json   # batch inputs, prediction IDs, statuses, and local paths
├── gallery.html        # optional visual review page
└── contact-sheet.jpg   # optional compact overview

Never overwrite an existing file. Use the next numeric manifest name and collision-safe output names.

Save each complete prediction response to predictions/<prediction-id>.json. Keep the exact inputs, outputs, model/version, timestamps, metrics, and errors. A batch manifest should map every requested slot to its prediction ID, status, remote output, and local path.

Download every file URL in a successful prediction output, including URLs nested in arrays or objects. Keep textual or structured outputs in the prediction JSON and manifest.

Use the bundled downloader after saving a prediction response:

node <skill-directory>/scripts/save-prediction.mjs \
  --prediction outputs/<task-slug>/predictions/<prediction-id>.json \
  --model owner/model \
  --dir outputs/<task-slug>/files

Optional --slug <description> overrides the slug inferred from input.prompt or other inputs.

Filename rules

Name downloaded files in this order:

<prediction-id>__<owner>-<model>__<input-or-prompt-slug>__<output-number>.<ext>

Example:

abc123__google-nano-banana-2__orange-cat-reading-on-train__01.jpg

Rules:

• Put the complete prediction ID first.
• Follow it with a concise owner-model slug.
• Follow that with a short, descriptive slug derived from the prompt or distinguishing inputs.
• Add a two-digit output number when a prediction has one or more file outputs.
• Keep names lowercase, ASCII, and reasonably short.
• Determine the extension from the response content type, then the URL. Do not label PNG or WebP bytes as JPG.
• If a path already exists, append __v002, __v003, and so on. Never replace it.

Favor JPG by requesting it from the model. Convert an existing PNG or WebP to JPG only when transparency and lossless fidelity are unimportant, and preserve the original unless the user says otherwise.

Embed image provenance

For every downloaded JPG, PNG, or WebP, use media-provenance to embed:

• provider: Replicate
• model owner/name
• exact prediction input
• original output value
• prediction ID, version, status, timestamps, metrics, and API URLs

The bundled downloader does this automatically with npx -y media-provenance. Verify at least one image from each batch:

npx -y media-provenance path/to/output.jpg | jq

Do not put tokens, authorization headers, local secrets, or environment contents in metadata or manifests.

Review and verify

After downloading:

1. Compare requested slots, succeeded predictions, downloaded URLs, and local files. Explain any mismatch.
2. Verify files are non-empty and inspect their actual media type.
3. Check image dimensions with magick identify and audio/video properties with ffprobe when relevant.
4. For visual batches, create a local HTML gallery or contact sheet and open it for review.
5. Preserve source and style reference files in the project when the run should be reproducible and the user has permission to retain them.
6. Invite the user to choose candidates. Generate broadly, review side by side, then cull aggressively rather than assuming the first result is final.

Git bookkeeping

Replicate outputs may be committed to Git when they are useful project artifacts.

Before committing, check for oversized files:

find outputs -type f -size +99M -print

Do not commit any individual file at or above 100 MB to ordinary Git. Use Git LFS or external object storage when required. Also inspect manifests and staged changes for secrets before committing.