Replicate Python Client

replicate is Replicate’s official Python client, letting you run any of the thousands of open-source machine learning models hosted on Replicate directly from Python or a Jupyter notebook with a single replicate.run() call. It handles authentication, prediction polling, streaming output, and file handling so callers don’t have to hand-build requests against Replicate’s REST API.

Beyond one-off model runs, the client covers the rest of the Replicate platform surface: creating and managing deployments, training custom models, working with webhooks for async predictions, and streaming partial output as a model runs — making it the reference way to integrate Replicate-hosted models into a Python application.

What You Get

• A one-line replicate.run() helper for running any hosted model, returning streaming-capable FileOutput objects for file outputs
• Lower-level Prediction, Model, Deployment, and Training resource objects for building custom integration flows
• Streaming support (stream.py) for consuming partial output from models as they run, not just the final result
• Webhook support for handling asynchronous prediction completion notifications instead of polling
• Pagination and collection helpers for browsing and listing models/predictions on the platform

Common Use Cases

• Calling a hosted image, audio, or LLM model from a Python backend with a single replicate.run() call
• Building a custom training pipeline that fine-tunes a model on Replicate and monitors training progress
• Streaming token-by-token or frame-by-frame output from a long-running model into a live UI
• Wiring Replicate webhooks into an application so prediction completion triggers a callback instead of client-side polling

Under The Hood

Architecture - client.py implements the core Client, handling auth via REPLICATE_API_TOKEN and all HTTP transport through httpx; run.py layers the simple replicate.run() helper on top of the lower-level prediction.py/model.py/deployment.py/training.py resource classes, each mapping to a corresponding Replicate REST resource. file.py implements the FileOutput abstraction introduced in the 1.0 release (an httpx.Response-like iterable for efficient file streaming), stream.py handles server-sent-event-style streaming of partial model output, and webhook.py/schema.py support async completion callbacks and model input/output schema introspection respectively.

Tech Stack - Python 3.8+ built on httpx for HTTP, pydantic (>1.10.7) for typed models, and packaging/typing_extensions for smaller platform needs; packaged with modern pyproject.toml and uv.lock for reproducible dependency resolution.

Code Quality - tests/ contains 18 test files covering the client, run helper, streaming, pagination, and webhook validation logic. The library ships a py.typed marker for full type-checker support, and exceptions.py centralizes API-error handling (e.g. distinguishing prediction failures from transport errors) rather than surfacing raw httpx exceptions to callers.

API Design - The top-level replicate.run() call is deliberately minimal — model identifier plus an input dict — while the 1.0 FileOutput change (README’s most prominent breaking-change note) improved default ergonomics for file-producing models at the cost of a documented migration step for existing callers (use_file_output=False reverts to the old URL-string behavior). Moving from the simple helper to lower-level resources (Prediction, Deployment, Training) for more control is a natural escalation path rather than a separate API to learn.