Replicate Predictions

Setup

• Credential: a Replicate API token (r8_...) from Account > API tokens, stored as a VX Agents bearer credential. Runs are billed to the token's account.
• Call getAccount once to confirm which user or organization will be billed.
• If the user always uses the same model, pin model_owner and model_name (e.g. black-forest-labs / flux-schnell).

Run a model

1. Find a model: searchModels (query= keywords), or browse listCollections → getCollection (e.g. text-to-image).
2. getModel to read the description and latest_version. Inputs are listed in the version's openapi_schema (getModelVersion, or listModelVersions for older ones).
3. Show the user the model, inputs and that the run costs money; get confirmation.
4. Run it:
   • official models (marked official on replicate.com): runOfficialModel with {"input": {...}};
   • any other model: createPrediction with {"version": "<version id>", "input": {...}}. Send header Prefer: wait (or wait=10) to hold the request open up to 60 seconds.
5. If the response status is starting or processing, poll getPrediction every few seconds until succeeded, failed or canceled.
6. Read output (often file URLs) and error/logs on failure. cancelPrediction stops a run that hangs.

Good to know

• Output file URLs expire after one hour: download or store them right away.
• Rate limits: creating predictions 600 requests per minute, other endpoints 3000; accounts with only granted credit and no payment method are limited to 6 per minute.
• listPredictions returns your own predictions only (cursor pagination via next).
• Prefer runOfficialModel for official models; it does not need a version id.
• Do not put personal data or secrets in input unless the user agrees: inputs are sent to a third-party model.

Source: Replicate HTTP API reference (https://replicate.com/docs/reference/http), checked 2026-10-16.