run-models

Docs

• Reference: https://replicate.com/docs/llms.txt
• OpenAPI schema: https://api.replicate.com/openapi.json
• MCP server: https://mcp.replicate.com
• Per-model docs:

  https://replicate.com/{owner}/{model}/llms.txt

• Set

  Accept: text/markdown

  when requesting docs pages for Markdown responses.

Workflow

1. Choose the right model - Search with the API or ask the user.
2. Get model metadata - Fetch input and output schema via API.
3. Create prediction - POST to /v1/predictions.
4. Poll for results - GET prediction until status is "succeeded".
5. Return output - Usually URLs to generated content.

Three ways to get output

1. Create a prediction, store its id from the response, and poll until completion.
2. Set a

   Prefer: wait

   header when creating a prediction for a blocking synchronous response. Only recommended for very fast models. Max 60 seconds.
3. Set an HTTPS webhook URL when creating a prediction, and Replicate will POST to that URL when the prediction completes.

Guidelines

• Use the

  POST /v1/predictions

  endpoint, as it supports both official and community models.
• Every model has its own OpenAPI schema. Always fetch and check model schemas to make sure you're setting valid inputs. Even popular models change their schemas.
• Validate input parameters against schema constraints (

  minimum

  ,

  maximum

  ,

  enum

  values). Don't generate values that violate them.
• When unsure about a parameter value, use the model's default example or omit the optional parameter.
• Don't set optional inputs unless you have a reason to. Stick to the required inputs and let the model's defaults do the work.
• Use HTTPS URLs for file inputs whenever possible. You can also send base64-encoded files, but they should be avoided.
• Fire off multiple predictions concurrently. Don't wait for one to finish before starting the next.
• Output file URLs expire after 1 hour, so back them up if you need to keep them, using a service like Cloudflare R2.
• Webhooks are a good mechanism for receiving and storing prediction output.

Predictions

• A prediction goes through these states:

  starting

  ->

  processing

  ->

  succeeded

  /

  failed

  /

  canceled

  .
• Official models use

  owner/name

  format. Community models require

  owner/name:version_id

  .
• The

  POST /v1/predictions

  endpoint handles both.

Webhooks

• Set

  webhook

  to an HTTPS URL when creating a prediction. Replicate POSTs the full prediction object when it completes.
• Filter events with

  webhook_events_filter

  :

  start

  ,

  output

  ,

  logs

  ,

  completed

  .
• Validate webhook signatures using the

  Webhook-ID

  ,

  Webhook-Timestamp

  , and

  Webhook-Signature

  headers. Get the signing secret from

  GET /v1/webhooks/default/secret

  .

Prediction lifetime

• Set

  lifetime

  to auto-cancel predictions that run too long (e.g.

  30s

  ,

  5m

  ,

  1h

  ). Measured from creation time.

Streaming

• Language models that support streaming include a

  stream

  URL in the response. Use SSE to receive incremental output.

File handling

• Prefer HTTPS URLs for file inputs. Output URLs from one prediction can be passed directly as file inputs to the next model.
• Output file URLs expire after 1 hour. Download and store them immediately if you need to keep them.

Multi-model workflows

• Chain models by passing output URLs as file inputs to the next model.
• Start all independent predictions in parallel, then collect results.
• Output URLs are valid for 1 hour, which is enough for pipeline steps.