Replicate Python Client

1.0.4 verified Tue May 12 auth: yes python install: verified quickstart: verified

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.

pip install replicate

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==2.0.0a16

Install compatibility verified last tested: 2026-05-12

python os / libc variant status wheel install import disk

3.10 alpine (musl) replicate - - 0.48s 32.6M

3.10 alpine (musl) replicate==2.0.0a16 - - - -

3.10 slim (glibc) replicate - - 0.35s 32M

3.10 slim (glibc) replicate==2.0.0a16 - - - -

3.11 alpine (musl) replicate - - 0.75s 35.7M

3.11 alpine (musl) replicate==2.0.0a16 - - - -

3.11 slim (glibc) replicate - - 0.59s 35M

3.11 slim (glibc) replicate==2.0.0a16 - - - -

3.12 alpine (musl) replicate - - 0.82s 27.2M

3.12 alpine (musl) replicate==2.0.0a16 - - - -

3.12 slim (glibc) replicate - - 0.80s 27M

3.12 slim (glibc) replicate==2.0.0a16 - - - -

3.13 alpine (musl) replicate - - 0.82s 26.8M

3.13 alpine (musl) replicate==2.0.0a16 - - - -

3.13 slim (glibc) replicate - - 0.78s 27M

3.13 slim (glibc) replicate==2.0.0a16 - - - -

3.9 alpine (musl) replicate - - 0.42s 31.9M

3.9 alpine (musl) replicate==2.0.0a16 - - - -

3.9 slim (glibc) replicate - - 0.40s 32M

3.9 slim (glibc) replicate==2.0.0a16 - - - -

Imports

replicate
wrong
```
from replicate import Client
client = Client(api_token=...)
```
correct
```
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
wrong
```
import replicate
await replicate.run(...)
```
correct
```
from replicate import AsyncReplicate
client = AsyncReplicate()
```
Top-level replicate module is synchronous only. For async, import AsyncReplicate explicitly.

Quickstart verified last tested: 2026-05-12

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())