run-models

---
name: run-models
description: Run AI models on Replicate via predictions, webhooks, and streaming.
---

## 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.