Replicate Python Client

1.0.4 · active · verified Sun Mar 01

Python client for running ML models on Replicate's cloud API. v0.x stable client is at 1.x on PyPI. A v2.0 beta (replicate-python-beta) exists as a separate package with a redesigned API. replicate.stream() is deprecated in v2. Billing changed to prepaid credit for new accounts in July 2025.

Warnings

breaking replicate.run() output for image models is a list of FileOutput objects, not URLs or strings. Treating output[0] as a string raises AttributeError.
Fix: Use output[0].read() to get bytes, or output[0].url to get the URL string.
breaking v2.0 alpha (replicate-python-beta) has a completely redesigned API with replicate.use() replacing replicate.run(). The two packages are incompatible — do not mix v1 and v2 patterns.
Fix: Stick to stable v1.x unless explicitly opting into the v2 beta. Do not install replicate-python-beta alongside replicate.
deprecated replicate.stream() is deprecated in v2 SDK. Still available for v1 backwards compatibility but will be removed.
Fix: Use replicate.run() with stream=True parameter, or use predictions.create() with streaming for fine-grained control.
gotcha Model versions are pinned by hash in many tutorials (e.g. 'owner/model:abc123'). Pinned version hashes go stale as models are updated. Unpinned calls use the latest deployment which may have different inputs/outputs.
Fix: Use versioned model strings for production ('owner/model:hash'). Check replicate.com/owner/model/versions for current hashes.
gotcha replicate.run() is synchronous and blocks until the prediction completes. For long-running models this can block for minutes.
Fix: Use replicate.predictions.create() to get a prediction ID immediately, then poll with predictions.get() or use AsyncReplicate for non-blocking calls.
gotcha New Replicate accounts (post July 2025) use prepaid credit billing, not monthly billing. API calls will fail with 402 if credit balance is zero, unlike monthly billing which allows negative balances until invoice.
Fix: Add credit at replicate.com/account/billing before making API calls. Set up auto-reload to avoid unexpected failures.

Install

pip install replicate Python (stable v1.x)
pip install replicate==2.0.0a16 Python (v2.0 alpha — separate API, not stable)

Imports

replicate
```
import replicate
output = replicate.run("owner/model", input={...})
```
Client class exists but top-level replicate.run() is the standard pattern. REPLICATE_API_TOKEN is read from env automatically.
AsyncReplicate
```
from replicate import AsyncReplicate
client = AsyncReplicate()
```
Top-level replicate module is synchronous only. For async, import AsyncReplicate explicitly.

Quickstart

Run a model on Replicate. Requires REPLICATE_API_TOKEN environment variable.

import replicate

output = replicate.run(
    "black-forest-labs/flux-schnell",
    input={"prompt": "an iguana on the beach"}
)

# output is a list of FileOutput objects for image models
with open('output.png', 'wb') as f:
    f.write(output[0].read())

view raw JSON →