replicate

Replicate

Replicate lets you run open-source machine learning models via a simple HTTP API. Submit a prediction, poll until it completes, and retrieve the output URLs.

Official docs: https://replicate.com/docs/reference/http

---

When to Use

Use this skill when you need to:

• Generate images using SDXL, FLUX Schnell, or other diffusion models
• Run text generation with Llama or other open-source LLMs
• Execute any model hosted on replicate.com
• Poll the status of an async prediction job

---

Prerequisites

Connect the Replicate connector at app.vm0.ai/connectors.

Troubleshooting: If requests fail, run zero doctor check-connector --env-name REPLICATE_TOKEN or zero doctor check-connector --url https://api.replicate.com/v1/models --method GET

---

How to Use

All predictions are asynchronous: submit a job, then poll until status is succeeded or failed.

1. Run a Model by Version ID

Write to /tmp/replicate_prediction.json:

{
  "version": "<model-version-id>",
  "input": {
    "prompt": "A photorealistic cat sitting on a chair"
  }
}

curl -s -X POST "https://api.replicate.com/v1/predictions" --header "Authorization: Bearer $REPLICATE_TOKEN" --header "Content-Type: application/json" -d @/tmp/replicate_prediction.json | jq '{id, status, urls}'

The response includes a prediction id and a urls.get URL for polling.

2. Run the Latest Version of a Model

Replace <owner> and <model-name> with the model's owner and name (e.g. black-forest-labs / flux-schnell).

Write to /tmp/replicate_prediction.json:

{
  "input": {
    "prompt": "A photorealistic cat sitting on a chair"
  }
}

curl -s -X POST "https://api.replicate.com/v1/models/<owner>/<model-name>/predictions" --header "Authorization: Bearer $REPLICATE_TOKEN" --header "Content-Type: application/json" -d @/tmp/replicate_prediction.json | jq '{id, status, urls}'

3. Poll Prediction Status

Replace <prediction-id> with the id from the create response.

curl -s "https://api.replicate.com/v1/predictions/<prediction-id>" --header "Authorization: Bearer $REPLICATE_TOKEN" | jq '{id, status, output, error}'

Keep polling every 2–5 seconds until status is succeeded or failed.

status	Meaning
starting	Model is cold-starting
processing	Model is running
succeeded	Output is ready in the output field
failed	Check the error field for details
canceled	Prediction was canceled

4. Generate an Image with FLUX Schnell

Write to /tmp/replicate_flux.json:

{
  "input": {
    "prompt": "A serene mountain lake at sunrise, photorealistic",
    "num_outputs": 1
  }
}

curl -s -X POST "https://api.replicate.com/v1/models/black-forest-labs/flux-schnell/predictions" --header "Authorization: Bearer $REPLICATE_TOKEN" --header "Content-Type: application/json" -d @/tmp/replicate_flux.json | jq '{id, status, urls}'

5. Generate an Image with Stability AI SDXL

Write to /tmp/replicate_sdxl.json:

{
  "input": {
    "prompt": "A cyberpunk cityscape at night, neon lights, 4k",
    "negative_prompt": "blurry, low quality",
    "num_outputs": 1,
    "width": 1024,
    "height": 1024
  }
}

curl -s -X POST "https://api.replicate.com/v1/models/stability-ai/sdxl/predictions" --header "Authorization: Bearer $REPLICATE_TOKEN" --header "Content-Type: application/json" -d @/tmp/replicate_sdxl.json | jq '{id, status, urls}'

6. Run a Text Generation Model (Llama 3 70B)

Write to /tmp/replicate_llama.json:

{
  "input": {
    "prompt": "Explain quantum entanglement in simple terms.",
    "max_tokens": 512
  }
}

curl -s -X POST "https://api.replicate.com/v1/models/meta/llama-3-70b-instruct/predictions" --header "Authorization: Bearer $REPLICATE_TOKEN" --header "Content-Type: application/json" -d @/tmp/replicate_llama.json | jq '{id, status, urls}'

Text generation responses stream tokens as an array. Poll until succeeded, then read output (an array of strings — join them for the full response).

7. List Recent Predictions

curl -s "https://api.replicate.com/v1/predictions" --header "Authorization: Bearer $REPLICATE_TOKEN" | jq '.results[] | {id, status, created_at, urls}'

8. Search for Models

curl -s "https://api.replicate.com/v1/models" --header "Authorization: Bearer $REPLICATE_TOKEN" | jq '.results[] | {url, description}'

9. Get Model Details

Replace <owner>/<model-name> with the model identifier.

curl -s "https://api.replicate.com/v1/models/<owner>/<model-name>" --header "Authorization: Bearer $REPLICATE_TOKEN" | jq '{url, description, latest_version}'

10. Run via a Deployment

Replace <deployment-owner> and <deployment-name> with the deployment's owner and name.

Write to /tmp/replicate_deploy.json:

{
  "input": {
    "prompt": "A futuristic robot in a garden"
  }
}

curl -s -X POST "https://api.replicate.com/v1/deployments/<deployment-owner>/<deployment-name>/predictions" --header "Authorization: Bearer $REPLICATE_TOKEN" --header "Content-Type: application/json" -d @/tmp/replicate_deploy.json | jq '{id, status, urls}'

---

Guidelines

1. Always poll after submit: Predictions are async. Never assume instant completion — always poll GET /v1/predictions/<id> until status is succeeded or failed.
2. Poll interval: 2–5 seconds is reasonable. Cold-starting models may take 30–60 seconds on the first prediction.
3. Image output: output will be an array of URLs (e.g. ["https://replicate.delivery/..."]). Download with curl -L.
4. Text output: output is an array of token strings. Join them: | jq '.output | join("")'.
5. Popular models:
   • Image: black-forest-labs/flux-schnell, stability-ai/sdxl
   • Text: meta/llama-3-70b-instruct
6. Version vs. latest: Use /v1/models/<owner>/<name>/predictions to always run the latest version. Use /v1/predictions with a version ID to pin a specific version.