From 7ffabdf32e2152285c78bc5a1125aebf5e3708f4 Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: 2025年9月30日 22:12:13 -0700 Subject: [PATCH 01/17] docs: add migration guide for upgrading from v1 to v2 This PR adds UPGRADING.md, a comprehensive migration guide for users upgrading from the v1 Replicate Python SDK to v2. The guide covers: - Client initialization changes (Replicate vs Client, bearer_token vs api_token) - Prediction lifecycle changes (resource methods vs instance methods) - Async support differences (AsyncReplicate client vs async_ methods) - Error handling improvements (granular exception types) - Pagination enhancements (auto-pagination) - Models and versions API changes (keyword arguments) - File handling differences - New features in v2 (models listing, better types, HTTP customization) - Removed features (instance methods, positional arguments) - Migration strategy recommendations Addresses DP-684 --- UPGRADING.md | 677 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 677 insertions(+) create mode 100644 UPGRADING.md diff --git a/UPGRADING.md b/UPGRADING.md new file mode 100644 index 0000000..b490240 --- /dev/null +++ b/UPGRADING.md @@ -0,0 +1,677 @@ +# Upgrading from v1 to v2 + +This guide helps you migrate from the v1 Replicate Python SDK to v2. The v2 SDK is a complete rewrite generated from Replicate's OpenAPI specification, providing better type safety, more consistent error handling, and improved async support. + +## Installation + +```sh +pip install --pre replicate +``` + +The v2 SDK requires Python 3.8 or higher, same as v1. + +## Pinning to 1.x + +You are not required to upgrade to the new 2.x version. If you're already using the 1.x version and want to continue using it, pin the version number in your dependency file. + +Here's an example `requirements.txt`: + +``` +replicate>=1.0.0,<2.0.0 +``` + +Here's an example `pyproject.toml`: + +```toml +[project] +dependencies = [ + "replicate>=1.0.0,<2.0.0", +] +``` + +## Quick migration checklist + +- Update client initialization to use `Replicate()` instead of `Client()` and `bearer_token` instead of `api_token` +- Replace prediction instance methods (`wait()`, `cancel()`, `reload()`) with resource methods +- Update async code to use `AsyncReplicate` client or context-aware module-level functions +- Add keyword arguments to all API calls +- Update exception handling to use new exception types + +## Client initialization and authentication + +The client class name and parameter names have changed. + +### Before (v1) + +```python +import replicate +from replicate import Client + +# Using environment variable +client = Client() + +# Explicit token +client = Client(api_token="r8_...") + +# Module-level usage +output = replicate.run(...) +``` + +### After (v2) + +```python +import replicate +from replicate import Replicate + +# Using environment variable (REPLICATE_API_TOKEN) +client = Replicate() + +# Explicit token (note: bearer_token, not api_token) +client = Replicate(bearer_token="r8_...") + +# Module-level usage (still works) +output = replicate.run(...) +``` + +The `api_token` parameter is still accepted for backward compatibility, but `bearer_token` is preferred. + +## Running models + +The basic `run()` method works similarly, but the `wait` parameter handling has changed. + +### Before (v1) + +```python +# Wait up to 60 seconds (default) +output = replicate.run( + "black-forest-labs/flux-schnell", + input={"prompt": "astronaut riding a rocket"} +) + +# Custom timeout +output = replicate.run(..., wait=30) + +# Don't wait +output = replicate.run(..., wait=False) +``` + +### After (v2) + +```python +# Wait up to 60 seconds (default) +output = replicate.run( + "black-forest-labs/flux-schnell", + input={"prompt": "astronaut riding a rocket"} +) + +# Custom timeout +output = replicate.run(..., wait=30) + +# Don't wait +output = replicate.run(..., wait=False) +``` + +The interface is the same, but v2 uses HTTP `Prefer` headers internally for better standards compliance. + +## Streaming output + +Streaming works similarly, but prediction objects no longer have a `stream()` method. + +### Before (v1) + +```python +# Top-level streaming +for event in replicate.stream( + "meta/meta-llama-3-70b-instruct", + input={"prompt": "Write a haiku"} +): + print(str(event), end="") + +# Streaming from prediction object +prediction = replicate.predictions.create(..., stream=True) +for event in prediction.stream(): + print(str(event), end="") +``` + +### After (v2) + +```python +# Top-level streaming (same) +for event in replicate.stream( + "meta/meta-llama-3-70b-instruct", + input={"prompt": "Write a haiku"} +): + print(str(event), end="") + +# Streaming from prediction requires using stream() function +prediction = replicate.predictions.create(...) +# prediction.stream() is not available in v2 +# Use replicate.stream() instead +``` + +To stream a specific prediction in v2, use the top-level `stream()` function. + +## Predictions + +Prediction objects have changed significantly. Instance methods like `wait()`, `cancel()`, and `reload()` are removed in favor of resource methods. + +### Creating predictions + +#### Before (v1) + +```python +prediction = replicate.predictions.create( + version="abc123...", + input={"prompt": "..."}, + webhook="https://example.com/webhook" +) + +# Create via model +prediction = replicate.predictions.create( + model="owner/model", + input={"prompt": "..."} +) +``` + +#### After (v2) + +```python +# Version is required +prediction = replicate.predictions.create( + version="abc123...", + input={"prompt": "..."}, + webhook="https://example.com/webhook" +) + +# Create via models resource (different structure) +prediction = replicate.models.predictions.create( + model_owner="owner", + model_name="model", + input={"prompt": "..."} +) +``` + +### Getting predictions + +#### Before (v1) + +```python +prediction = replicate.predictions.get("prediction_id") +``` + +#### After (v2) + +```python +# Note: keyword argument required +prediction = replicate.predictions.get(prediction_id="prediction_id") +``` + +### Waiting for predictions + +#### Before (v1) + +```python +prediction = replicate.predictions.create(...) +prediction.wait() +``` + +#### After (v2) + +```python +prediction = replicate.predictions.create(...) +# prediction.wait() is not available + +# Use resource method instead +prediction = replicate.predictions.wait(prediction.id) +``` + +### Canceling predictions + +#### Before (v1) + +```python +prediction = replicate.predictions.get("prediction_id") +prediction.cancel() +``` + +#### After (v2) + +```python +prediction = replicate.predictions.get(prediction_id="prediction_id") +# prediction.cancel() is not available + +# Use resource method instead +prediction = replicate.predictions.cancel(prediction.id) +``` + +### Reloading predictions + +#### Before (v1) + +```python +prediction = replicate.predictions.get("prediction_id") +prediction.reload() +print(prediction.status) +``` + +#### After (v2) + +```python +prediction = replicate.predictions.get(prediction_id="prediction_id") +# prediction.reload() is not available + +# Fetch fresh data instead +prediction = replicate.predictions.get(prediction_id=prediction.id) +print(prediction.status) +``` + +## Async support + +Async functionality has been redesigned. Instead of separate `async_*` methods, v2 uses a dedicated `AsyncReplicate` client. + +### Before (v1) + +```python +import replicate + +# Async methods with async_ prefix +output = await replicate.async_run(...) + +for event in replicate.async_stream(...): + print(event) + +prediction = await replicate.predictions.async_create(...) +prediction = await replicate.predictions.async_get("id") +await prediction.async_wait() +``` + +### After (v2) + +```python +from replicate import AsyncReplicate + +# Use AsyncReplicate client +client = AsyncReplicate() + +# Same method names, no async_ prefix +output = await client.run(...) + +async for event in client.stream(...): + print(event) + +prediction = await client.predictions.create(...) +prediction = await client.predictions.get(prediction_id="id") +prediction = await client.predictions.wait(prediction.id) + +# Or use module-level functions (context-aware) +output = await replicate.run(...) +async for event in replicate.stream(...): + print(event) +``` + +## Error handling + +Error handling is more granular in v2, with specific exception types for each HTTP status code. + +### Before (v1) + +```python +from replicate.exceptions import ReplicateError, ModelError + +try: + output = replicate.run(...) +except ModelError as e: + print(f"Model failed: {e.prediction.error}") +except ReplicateError as e: + print(f"API error: {e}") +``` + +### After (v2) + +```python +from replicate.exceptions import ( + ModelError, + NotFoundError, + AuthenticationError, + RateLimitError, + APIStatusError +) + +try: + output = replicate.run(...) +except ModelError as e: + print(f"Model failed: {e.prediction.error}") +except NotFoundError as e: + print(f"Not found: {e.message}") +except RateLimitError as e: + print(f"Rate limited: {e.message}") +except APIStatusError as e: + print(f"API error {e.status_code}: {e.message}") +``` + +Available exception types in v2: + +- `APIError` - Base exception for all API errors +- `APIConnectionError` - Network connection errors +- `APITimeoutError` - Request timeout errors +- `APIStatusError` - Base for HTTP status errors +- `BadRequestError` - 400 errors +- `AuthenticationError` - 401 errors +- `PermissionDeniedError` - 403 errors +- `NotFoundError` - 404 errors +- `ConflictError` - 409 errors +- `UnprocessableEntityError` - 422 errors +- `RateLimitError` - 429 errors +- `InternalServerError` - 500+ errors +- `ModelError` - Model execution failures + +## Pagination + +Pagination is more streamlined in v2 with auto-pagination support. + +### Before (v1) + +```python +# Manual pagination +page = replicate.predictions.list() +for prediction in page.results: + print(prediction.id) + +if page.next: + next_page = replicate.predictions.list(cursor=page.next) + +# Auto-pagination +for page in replicate.paginate(replicate.predictions.list): + for prediction in page.results: + print(prediction.id) +``` + +### After (v2) + +```python +# Auto-pagination built-in +page = replicate.predictions.list() + +# Iterate directly over page +for prediction in page: + print(prediction.id) + +# Manual pagination +if page.has_next_page(): + next_page = page.get_next_page() + +# Access results list still available +for prediction in page.results: + print(prediction.id) +``` + +## Models and versions + +Model and version access uses keyword arguments throughout. + +### Before (v1) + +```python +# Get model +model = replicate.models.get("owner/name") + +# Get version from model +version = model.versions.get("version_id") + +# List versions +versions = model.versions.list() +``` + +### After (v2) + +```python +# Get model (keyword arguments required) +model = replicate.models.get( + model_owner="owner", + model_name="name" +) + +# Get version (no shorthand via model object) +version = replicate.models.versions.get( + model_owner="owner", + model_name="name", + version_id="version_id" +) + +# List versions +versions = replicate.models.versions.list( + model_owner="owner", + model_name="name" +) + +# NEW: List all models +all_models = replicate.models.list() +``` + +The `model.versions` shorthand is not available in v2. The v2 SDK adds a new `models.list()` method to list all models. + +## Trainings + +Training objects also lose their instance methods in v2. + +### Before (v1) + +```python +training = replicate.trainings.create( + version="version_id", + input={"train_data": "https://..."}, + destination="owner/model" +) + +# Wait and cancel +training.wait() +training.cancel() +``` + +### After (v2) + +```python +training = replicate.trainings.create( + model_owner="owner", + model_name="model", + version_id="version_id", + input={"train_data": "https://..."}, + destination="owner/new-model" +) + +# No instance methods available +# Use resource methods +training = replicate.trainings.cancel(training_id=training.id) +``` + +## File uploads + +File upload handling has changed slightly. + +### Before (v1) + +```python +# Upload file +file = replicate.files.create( + file=open("image.jpg", "rb"), + filename="image.jpg" +) + +# Access URL +url = file.urls["get"] +``` + +### After (v2) + +```python +# Upload file (takes bytes, not file handle) +with open("image.jpg", "rb") as f: + file = replicate.files.create( + content=f.read(), + filename="image.jpg" + ) + +# Access URL (property instead of dict) +url = file.urls.get +``` + +File inputs to predictions work the same way in both versions. + +## Collections + +Collections API uses keyword arguments in v2. + +### Before (v1) + +```python +collection = replicate.collections.get("collection_slug") +models = collection.models +``` + +### After (v2) + +```python +collection = replicate.collections.get(collection_slug="collection_slug") + +# Models accessed via nested resource +models = replicate.collections.models.list(collection_slug="collection_slug") +``` + +## Webhooks + +Webhook validation is compatible between v1 and v2. + +### Before (v1) + +```python +from replicate.webhook import Webhooks + +secret = replicate.webhooks.default.secret() +Webhooks.validate(request, secret) +``` + +### After (v2) + +```python +from replicate.resources.webhooks import Webhooks + +secret = replicate.webhooks.default.secret() +Webhooks.validate(request, secret) +``` + +The validation logic is identical; only import paths may differ. + +## Experimental use() interface + +The experimental `use()` interface is available in both versions with similar functionality. V2 adds async support. + +### Before (v1) + +```python +flux = replicate.use("black-forest-labs/flux-schnell") +outputs = flux(prompt="astronaut on a horse") +``` + +### After (v2) + +```python +# Same interface +flux = replicate.use("black-forest-labs/flux-schnell") +outputs = flux(prompt="astronaut on a horse") + +# NEW: Async support +async_flux = replicate.use("black-forest-labs/flux-schnell", use_async=True) +outputs = await async_flux(prompt="astronaut on a horse") +``` + +## New features in v2 + +### Models listing + +```python +# List all models (not available in v1) +for model in replicate.models.list(): + print(model.name) +``` + +### Better type safety + +V2 includes comprehensive type hints generated from the OpenAPI spec, providing better IDE autocomplete and type checking. + +```python +from replicate import Replicate +from replicate.types import Prediction + +client: Replicate = Replicate() +prediction: Prediction = client.predictions.get(prediction_id="...") +``` + +### HTTP client customization + +```python +from replicate import Replicate, DefaultHttpxClient +import httpx + +client = Replicate( + http_client=DefaultHttpxClient( + proxy="http://proxy.example.com", + transport=httpx.HTTPTransport(local_address="0.0.0.0") + ), + timeout=30.0, + max_retries=3 +) +``` + +### Raw response access + +```python +# Access raw HTTP responses +response = client.with_raw_response.predictions.get(prediction_id="...") +print(response.headers) +print(response.http_response.status_code) + +prediction = response.parse() +``` + +### Streaming response wrapper + +```python +# Stream response body +with client.with_streaming_response.predictions.get( + prediction_id="..." +) as response: + for chunk in response.iter_bytes(): + process(chunk) +``` + +## Removed features + +The following features are not available in v2: + +- Prediction instance methods: `wait()`, `cancel()`, `reload()`, `stream()`, `output_iterator()` +- Training instance methods: `cancel()`, `reload()` +- Model instance methods: `predict()` +- `model.versions` shorthand (use `replicate.models.versions` instead) +- Separate `async_*` methods (use `AsyncReplicate` client) +- Positional arguments (all methods require keyword arguments) + +## Migration strategy + +For a gradual migration: + +1. Start by updating client initialization and imports +2. Replace prediction instance methods with resource methods +3. Update async code to use `AsyncReplicate` +4. Add keyword arguments to all API calls +5. Update error handling to use specific exception types +6. Test thoroughly, especially prediction lifecycle code + +For codebases with extensive v1 usage, consider creating adapter functions to bridge the differences while you migrate incrementally. + +## Getting help + +If you encounter issues during migration: + +- Check the [API documentation](https://replicate.com/docs/reference/http) +- Review the [full API reference](api.md) +- Open an issue on [GitHub](https://github.com/replicate/replicate-python-stainless/issues) From 675922a8fdc840d4886e7bd33e1e881d5aad23b0 Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: 2025年9月30日 22:15:42 -0700 Subject: [PATCH 02/17] docs: remove unnecessary implementation detail about Prefer headers --- UPGRADING.md | 38 -------------------------------------- 1 file changed, 38 deletions(-) diff --git a/UPGRADING.md b/UPGRADING.md index b490240..91cbda2 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -75,44 +75,6 @@ output = replicate.run(...) The `api_token` parameter is still accepted for backward compatibility, but `bearer_token` is preferred. -## Running models - -The basic `run()` method works similarly, but the `wait` parameter handling has changed. - -### Before (v1) - -```python -# Wait up to 60 seconds (default) -output = replicate.run( - "black-forest-labs/flux-schnell", - input={"prompt": "astronaut riding a rocket"} -) - -# Custom timeout -output = replicate.run(..., wait=30) - -# Don't wait -output = replicate.run(..., wait=False) -``` - -### After (v2) - -```python -# Wait up to 60 seconds (default) -output = replicate.run( - "black-forest-labs/flux-schnell", - input={"prompt": "astronaut riding a rocket"} -) - -# Custom timeout -output = replicate.run(..., wait=30) - -# Don't wait -output = replicate.run(..., wait=False) -``` - -The interface is the same, but v2 uses HTTP `Prefer` headers internally for better standards compliance. - ## Streaming output Streaming works similarly, but prediction objects no longer have a `stream()` method. From c0d4a383d4f24a64a7fa54798ed9a2d49161c53a Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Wed, 1 Oct 2025 09:38:32 -0700 Subject: [PATCH 03/17] docs: clarify "resource methods" terminology in migration guide --- UPGRADING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/UPGRADING.md b/UPGRADING.md index 91cbda2..a09f554 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -32,7 +32,7 @@ dependencies = [ ## Quick migration checklist - Update client initialization to use `Replicate()` instead of `Client()` and `bearer_token` instead of `api_token` -- Replace prediction instance methods (`wait()`, `cancel()`, `reload()`) with resource methods +- Replace prediction instance methods with client methods (e.g., `replicate.predictions.wait(id)` instead of `prediction.wait()`) - Update async code to use `AsyncReplicate` client or context-aware module-level functions - Add keyword arguments to all API calls - Update exception handling to use new exception types @@ -115,7 +115,7 @@ To stream a specific prediction in v2, use the top-level `stream()` function. ## Predictions -Prediction objects have changed significantly. Instance methods like `wait()`, `cancel()`, and `reload()` are removed in favor of resource methods. +Prediction objects have changed significantly. Instance methods like `wait()`, `cancel()`, and `reload()` are removed in favor of client methods (e.g., use `replicate.predictions.wait(prediction.id)` instead of `prediction.wait()`). ### Creating predictions From e979d1b0d205e48f1a8eab30abc2908fb070898e Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Wed, 1 Oct 2025 09:38:52 -0700 Subject: [PATCH 04/17] docs: add section links to migration checklist --- UPGRADING.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/UPGRADING.md b/UPGRADING.md index a09f554..8ebd0dc 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -31,11 +31,11 @@ dependencies = [ ## Quick migration checklist -- Update client initialization to use `Replicate()` instead of `Client()` and `bearer_token` instead of `api_token` -- Replace prediction instance methods with client methods (e.g., `replicate.predictions.wait(id)` instead of `prediction.wait()`) -- Update async code to use `AsyncReplicate` client or context-aware module-level functions -- Add keyword arguments to all API calls -- Update exception handling to use new exception types +- Update client initialization to use `Replicate()` instead of `Client()` and `bearer_token` instead of `api_token` - [details](#client-initialization-and-authentication) +- Replace prediction instance methods with client methods (e.g., `replicate.predictions.wait(id)` instead of `prediction.wait()`) - [details](#predictions) +- Update async code to use `AsyncReplicate` client or context-aware module-level functions - [details](#async-support) +- Add keyword arguments to all API calls - [details](#models-and-versions) +- Update exception handling to use new exception types - [details](#error-handling) ## Client initialization and authentication From 734ec416791b64f95519740aa8e99f29217cd071 Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Wed, 1 Oct 2025 09:39:13 -0700 Subject: [PATCH 05/17] docs: clarify auto-pagination behavior in v2 --- UPGRADING.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/UPGRADING.md b/UPGRADING.md index 8ebd0dc..bdc8ab2 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -351,18 +351,18 @@ for page in replicate.paginate(replicate.predictions.list): ### After (v2) ```python -# Auto-pagination built-in -page = replicate.predictions.list() - -# Iterate directly over page -for prediction in page: +# Auto-pagination: iterate through all pages automatically +for prediction in replicate.predictions.list(): print(prediction.id) + # Automatically fetches more pages as needed -# Manual pagination +# Manual pagination (if needed) +page = replicate.predictions.list() if page.has_next_page(): next_page = page.get_next_page() -# Access results list still available +# Access results from a single page +page = replicate.predictions.list() for prediction in page.results: print(prediction.id) ``` From c6f1222129384b748c8e40e7eeb91fbe2d029498 Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Wed, 1 Oct 2025 09:43:27 -0700 Subject: [PATCH 06/17] docs: add wait example for trainings to mirror v1 --- UPGRADING.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/UPGRADING.md b/UPGRADING.md index bdc8ab2..944859c 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -442,7 +442,17 @@ training = replicate.trainings.create( ) # No instance methods available -# Use resource methods +# Use client methods instead + +# Wait for training (no trainings.wait() available) +# Poll with get() instead +while True: + training = replicate.trainings.get(training_id=training.id) + if training.status in ["succeeded", "failed", "canceled"]: + break + time.sleep(1) + +# Cancel training training = replicate.trainings.cancel(training_id=training.id) ``` From 822e831fd0da7c243d51849df2cf5574af385bec Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Wed, 1 Oct 2025 09:44:30 -0700 Subject: [PATCH 07/17] docs: clarify file upload supports file handles without reading into memory --- UPGRADING.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/UPGRADING.md b/UPGRADING.md index 944859c..3524d09 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -476,7 +476,14 @@ url = file.urls["get"] ### After (v2) ```python -# Upload file (takes bytes, not file handle) +# Upload file (supports file handle, bytes, or PathLike) +with open("image.jpg", "rb") as f: + file = replicate.files.create( + content=f, # Can pass file handle directly + filename="image.jpg" + ) + +# Or read into memory if needed with open("image.jpg", "rb") as f: file = replicate.files.create( content=f.read(), From 5f53bd6ef999318c3065dbbb8ac162b1538e9784 Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Wed, 1 Oct 2025 09:49:33 -0700 Subject: [PATCH 08/17] docs: correct async support in use() interface - v1 also had it --- UPGRADING.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/UPGRADING.md b/UPGRADING.md index 3524d09..14b2d3b 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -542,13 +542,17 @@ The validation logic is identical; only import paths may differ. ## Experimental use() interface -The experimental `use()` interface is available in both versions with similar functionality. V2 adds async support. +The experimental `use()` interface is available in both versions with similar functionality. ### Before (v1) ```python flux = replicate.use("black-forest-labs/flux-schnell") outputs = flux(prompt="astronaut on a horse") + +# Async support +async_flux = replicate.use("black-forest-labs/flux-schnell") +outputs = await async_flux(prompt="astronaut on a horse") ``` ### After (v2) @@ -558,7 +562,7 @@ outputs = flux(prompt="astronaut on a horse") flux = replicate.use("black-forest-labs/flux-schnell") outputs = flux(prompt="astronaut on a horse") -# NEW: Async support +# Async support (uses use_async parameter) async_flux = replicate.use("black-forest-labs/flux-schnell", use_async=True) outputs = await async_flux(prompt="astronaut on a horse") ``` From 76f31f2fa959f30c9c98021e83f00fc174d0d69c Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Wed, 1 Oct 2025 09:52:44 -0700 Subject: [PATCH 09/17] docs: add documentation reference for APIResponse object --- UPGRADING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/UPGRADING.md b/UPGRADING.md index 14b2d3b..246e6e5 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -616,6 +616,8 @@ print(response.http_response.status_code) prediction = response.parse() ``` +The response object is an [`APIResponse`](https://github.com/replicate/replicate-python-stainless/tree/main/src/replicate/_response.py) instance. See the [README](https://github.com/replicate/replicate-python-stainless#accessing-raw-response-data-eg-headers) for full documentation. + ### Streaming response wrapper ```python From 1e10544c8afbc1357b8553062fb077c1a3c0f120 Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Wed, 1 Oct 2025 10:26:39 -0700 Subject: [PATCH 10/17] fix upgrading note about creating predictions --- UPGRADING.md | 17 ++--------------- 1 file changed, 2 insertions(+), 15 deletions(-) diff --git a/UPGRADING.md b/UPGRADING.md index 246e6e5..e9effcc 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -122,13 +122,7 @@ Prediction objects have changed significantly. Instance methods like `wait()`, ` #### Before (v1) ```python -prediction = replicate.predictions.create( - version="abc123...", - input={"prompt": "..."}, - webhook="https://example.com/webhook" -) - -# Create via model +# Create via model shorthand prediction = replicate.predictions.create( model="owner/model", input={"prompt": "..."} @@ -138,14 +132,7 @@ prediction = replicate.predictions.create( #### After (v2) ```python -# Version is required -prediction = replicate.predictions.create( - version="abc123...", - input={"prompt": "..."}, - webhook="https://example.com/webhook" -) - -# Create via models resource (different structure) +# Create with keyword arguments model_owner and model_name prediction = replicate.models.predictions.create( model_owner="owner", model_name="model", From f1dc6b0beafd392a0c80b47b2a81449ea06e78fd Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Wed, 1 Oct 2025 10:33:55 -0700 Subject: [PATCH 11/17] remove unrelated comment about models.list() --- UPGRADING.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/UPGRADING.md b/UPGRADING.md index e9effcc..adabd88 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -392,12 +392,9 @@ versions = replicate.models.versions.list( model_owner="owner", model_name="name" ) - -# NEW: List all models -all_models = replicate.models.list() ``` -The `model.versions` shorthand is not available in v2. The v2 SDK adds a new `models.list()` method to list all models. +The `model.versions` shorthand is not available in v2. ## Trainings From fbe8fce2251507dadafeb6a87e442b6db0012bec Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: 2025年10月10日 11:40:22 -0700 Subject: [PATCH 12/17] docs: update streaming section to show replicate.use() with streaming=True Update migration guide to reflect that replicate.use() with streaming=True is the preferred approach for streaming in v2. Mention that replicate.stream() still works but is deprecated, without showing a code example. --- UPGRADING.md | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/UPGRADING.md b/UPGRADING.md index adabd88..97a340a 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -77,7 +77,7 @@ The `api_token` parameter is still accepted for backward compatibility, but `bea ## Streaming output -Streaming works similarly, but prediction objects no longer have a `stream()` method. +Streaming works differently in v2. Prediction objects no longer have a `stream()` method. Use `replicate.use()` with `streaming=True` for streaming output. ### Before (v1) @@ -98,20 +98,17 @@ for event in prediction.stream(): ### After (v2) ```python -# Top-level streaming (same) -for event in replicate.stream( - "meta/meta-llama-3-70b-instruct", - input={"prompt": "Write a haiku"} -): +# Use replicate.use() with streaming=True +model = replicate.use("meta/meta-llama-3-70b-instruct", streaming=True) +for event in model(prompt="Write a haiku"): print(str(event), end="") -# Streaming from prediction requires using stream() function +# Streaming from prediction object is not available prediction = replicate.predictions.create(...) # prediction.stream() is not available in v2 -# Use replicate.stream() instead ``` -To stream a specific prediction in v2, use the top-level `stream()` function. +Note: `replicate.stream()` still works in v2 but is deprecated and will be removed in a future version. ## Predictions From f6f6029c8120f3f39ddd5d2ef2be75e37ba6cb13 Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: 2025年10月10日 12:04:41 -0700 Subject: [PATCH 13/17] update client section of upgrade guide --- UPGRADING.md | 38 ++++++++++++++++++++------------------ 1 file changed, 20 insertions(+), 18 deletions(-) diff --git a/UPGRADING.md b/UPGRADING.md index 97a340a..b77c990 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -2,8 +2,14 @@ This guide helps you migrate from the v1 Replicate Python SDK to v2. The v2 SDK is a complete rewrite generated from Replicate's OpenAPI specification, providing better type safety, more consistent error handling, and improved async support. +This doc is intended for both humans and agents. + +If you're using an AI tool to assist with the upgrade process, you can provide it with this entire document as context. + ## Installation +Use pip to install the latest pre-release version of the SDK: + ```sh pip install --pre replicate ``` @@ -12,7 +18,7 @@ The v2 SDK requires Python 3.8 or higher, same as v1. ## Pinning to 1.x -You are not required to upgrade to the new 2.x version. If you're already using the 1.x version and want to continue using it, pin the version number in your dependency file. +You are not required to upgrade to the new 2.x version. If you're already using the 1.x version and want to continue using it, pin the version number in your dependency files. Here's an example `requirements.txt`: @@ -39,38 +45,34 @@ dependencies = [ ## Client initialization and authentication -The client class name and parameter names have changed. +In both the v1 and v2 SDKs, the simplest usage pattern is to import the `replicate` module and use the module-level functions like `replicate.run()`, which automatically uses the `REPLICATE_API_TOKEN` environment variable, without explicitly instantiating a client: + +```python +import replicate + +output = replicate.run(...) +``` + +For cases where you need to instantiate a client (e.g., for custom configuration or async support), the client class name and parameter names have changed in v2: ### Before (v1) ```python +import os import replicate from replicate import Client -# Using environment variable -client = Client() - -# Explicit token -client = Client(api_token="r8_...") - -# Module-level usage -output = replicate.run(...) +client = Client(api_token=os.environ["REPLICATE_API_TOKEN"]) ``` ### After (v2) ```python +import os import replicate from replicate import Replicate -# Using environment variable (REPLICATE_API_TOKEN) -client = Replicate() - -# Explicit token (note: bearer_token, not api_token) -client = Replicate(bearer_token="r8_...") - -# Module-level usage (still works) -output = replicate.run(...) +client = Replicate(bearer_token=os.environ["REPLICATE_API_TOKEN"]) ``` The `api_token` parameter is still accepted for backward compatibility, but `bearer_token` is preferred. From e82741d95d82edd1a059acf61bd8890752ff1917 Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: 2025年10月10日 12:08:10 -0700 Subject: [PATCH 14/17] docs: use anthropic/claude-4.5-sonnet in streaming examples --- UPGRADING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/UPGRADING.md b/UPGRADING.md index b77c990..c6a3388 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -6,9 +6,9 @@ This doc is intended for both humans and agents. If you're using an AI tool to assist with the upgrade process, you can provide it with this entire document as context. -## Installation +## Installing the v2 SDK -Use pip to install the latest pre-release version of the SDK: +Use pip to install the latest pre-release version of the v2 SDK: ```sh pip install --pre replicate @@ -86,7 +86,7 @@ Streaming works differently in v2. Prediction objects no longer have a `stream() ```python # Top-level streaming for event in replicate.stream( - "meta/meta-llama-3-70b-instruct", + "anthropic/claude-4.5-sonnet", input={"prompt": "Write a haiku"} ): print(str(event), end="") @@ -101,7 +101,7 @@ for event in prediction.stream(): ```python # Use replicate.use() with streaming=True -model = replicate.use("meta/meta-llama-3-70b-instruct", streaming=True) +model = replicate.use("anthropic/claude-4.5-sonnet", streaming=True) for event in model(prompt="Write a haiku"): print(str(event), end="") From 31298dc90b3e64364098ac0d16732eadf39519f2 Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: 2025年10月10日 12:52:08 -0700 Subject: [PATCH 15/17] Update UPGRADING.md --- UPGRADING.md | 48 ++++++++++++++++++++---------------------------- 1 file changed, 20 insertions(+), 28 deletions(-) diff --git a/UPGRADING.md b/UPGRADING.md index c6a3388..317d10c 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -1,10 +1,10 @@ # Upgrading from v1 to v2 -This guide helps you migrate from the v1 Replicate Python SDK to v2. The v2 SDK is a complete rewrite generated from Replicate's OpenAPI specification, providing better type safety, more consistent error handling, and improved async support. +This guide will help you migrate an existing codebase from the v1 Replicate Python SDK to v2. The v2 SDK is a complete rewrite generated in partnership with [Stainless](https://www.stainless.com/customers/replicate), the folks who help build and maintain SDKs for companies like OpenAI, Anthropic, and Cloudflare. The v2 SDK is largely autogenerated from Replicate's OpenAPI specification, providing better type safety, more consistent error handling, and improved async support. Check out the [v2 release notes](#TODO) for more details. -This doc is intended for both humans and agents. +✋ If you are working on a new project, you don't need to read this document. -If you're using an AI tool to assist with the upgrade process, you can provide it with this entire document as context. +This doc is intended for both humans and agents. 🧑🏽‍🦰 🤝 🤖 ## Installing the v2 SDK @@ -14,9 +14,7 @@ Use pip to install the latest pre-release version of the v2 SDK: pip install --pre replicate ``` -The v2 SDK requires Python 3.8 or higher, same as v1. - -## Pinning to 1.x +## Pinning to the legacy v1 SDK You are not required to upgrade to the new 2.x version. If you're already using the 1.x version and want to continue using it, pin the version number in your dependency files. @@ -45,7 +43,7 @@ dependencies = [ ## Client initialization and authentication -In both the v1 and v2 SDKs, the simplest usage pattern is to import the `replicate` module and use the module-level functions like `replicate.run()`, which automatically uses the `REPLICATE_API_TOKEN` environment variable, without explicitly instantiating a client: +In both the v1 and v2 SDKs, the simplest way to import and use the library is to import the `replicate` module and use the module-level functions like `replicate.run()`, without explicitly instantiating a client: ```python import replicate @@ -53,6 +51,10 @@ import replicate output = replicate.run(...) ``` +☝️ This approach expects a `REPLICATE_API_TOKEN` variable to be present in the environment. + +--- + For cases where you need to instantiate a client (e.g., for custom configuration or async support), the client class name and parameter names have changed in v2: ### Before (v1) @@ -79,7 +81,9 @@ The `api_token` parameter is still accepted for backward compatibility, but `bea ## Streaming output -Streaming works differently in v2. Prediction objects no longer have a `stream()` method. Use `replicate.use()` with `streaming=True` for streaming output. +Streaming works differently in v2. Prediction objects no longer have a `stream()` method and the `replicate.stream()` method is deprecated. + +You should use `replicate.use()` with `streaming=True` for streaming output in the v2 SDK. ### Before (v1) @@ -114,7 +118,7 @@ Note: `replicate.stream()` still works in v2 but is deprecated and will be remov ## Predictions -Prediction objects have changed significantly. Instance methods like `wait()`, `cancel()`, and `reload()` are removed in favor of client methods (e.g., use `replicate.predictions.wait(prediction.id)` instead of `prediction.wait()`). +Prediction objects in the v2 client no longer have instance methods like `wait()`, `cancel()`, and `reload()`. These have been removed in favor of client methods (e.g., use `replicate.predictions.wait(prediction.id)` instead of `prediction.wait()`). ### Creating predictions @@ -355,7 +359,9 @@ for prediction in page.results: ## Models and versions -Model and version access uses keyword arguments throughout. +Model and version access uses keyword arguments throughout, instead of shorthand positional arguments. + +The new keyword argument syntax in v2 is more verbose but clearer and more consistent with Replicate's HTTP API, and consistent across all SDKs in different programming languages. ### Before (v1) @@ -397,7 +403,7 @@ The `model.versions` shorthand is not available in v2. ## Trainings -Training objects also lose their instance methods in v2. +Training objects do not have the `.wait()` and `.cancel()` instance methods in v2. ### Before (v1) @@ -521,7 +527,7 @@ secret = replicate.webhooks.default.secret() Webhooks.validate(request, secret) ``` -The validation logic is identical; only import paths may differ. +The validation logic is identical; only the import paths differ. ## Experimental use() interface @@ -621,25 +627,11 @@ The following features are not available in v2: - Model instance methods: `predict()` - `model.versions` shorthand (use `replicate.models.versions` instead) - Separate `async_*` methods (use `AsyncReplicate` client) -- Positional arguments (all methods require keyword arguments) - -## Migration strategy - -For a gradual migration: - -1. Start by updating client initialization and imports -2. Replace prediction instance methods with resource methods -3. Update async code to use `AsyncReplicate` -4. Add keyword arguments to all API calls -5. Update error handling to use specific exception types -6. Test thoroughly, especially prediction lifecycle code - -For codebases with extensive v1 usage, consider creating adapter functions to bridge the differences while you migrate incrementally. +- Positional arguments (all API operation methods like `models.get` and `collections.let` require keyword arguments) ## Getting help -If you encounter issues during migration: +If you encounter issues during the migration process: - Check the [API documentation](https://replicate.com/docs/reference/http) -- Review the [full API reference](api.md) - Open an issue on [GitHub](https://github.com/replicate/replicate-python-stainless/issues) From 0bb7fdf3a38f250c698a6a1081615b224e5d8e70 Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: 2025年10月10日 12:54:23 -0700 Subject: [PATCH 16/17] Update UPGRADING.md --- UPGRADING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/UPGRADING.md b/UPGRADING.md index 317d10c..0fbe9e9 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -1,6 +1,6 @@ # Upgrading from v1 to v2 -This guide will help you migrate an existing codebase from the v1 Replicate Python SDK to v2. The v2 SDK is a complete rewrite generated in partnership with [Stainless](https://www.stainless.com/customers/replicate), the folks who help build and maintain SDKs for companies like OpenAI, Anthropic, and Cloudflare. The v2 SDK is largely autogenerated from Replicate's OpenAPI specification, providing better type safety, more consistent error handling, and improved async support. Check out the [v2 release notes](#TODO) for more details. +This guide will help you migrate an existing codebase from the v1 Replicate Python SDK to v2. The v2 SDK is a complete rewrite generated in partnership with [Stainless](https://www.stainless.com/customers/replicate), the folks who help build and maintain SDKs for companies like OpenAI, Anthropic, and Cloudflare. The v2 SDK is largely autogenerated from Replicate's OpenAPI specification, providing better type safety, more consistent error handling, and improved async support. Check out the [v2 release notes](https://github.com/replicate/replicate-python-stainless/releases) for more details. ✋ If you are working on a new project, you don't need to read this document. @@ -627,11 +627,11 @@ The following features are not available in v2: - Model instance methods: `predict()` - `model.versions` shorthand (use `replicate.models.versions` instead) - Separate `async_*` methods (use `AsyncReplicate` client) -- Positional arguments (all API operation methods like `models.get` and `collections.let` require keyword arguments) +- Positional arguments (all methods that map to HTTP API operations like `models.get` and `collections.get` now require keyword arguments) ## Getting help If you encounter issues during the migration process: - Check the [API documentation](https://replicate.com/docs/reference/http) -- Open an issue on [GitHub](https://github.com/replicate/replicate-python-stainless/issues) +- Open an issue on [GitHub](https://github.com/replicate/replicate-python-stainless/issues) \ No newline at end of file From 9917ddb4d655b3a145fe11f8a2cd5d2fe682acbe Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: 2025年10月10日 13:08:35 -0700 Subject: [PATCH 17/17] Update UPGRADING.md --- UPGRADING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/UPGRADING.md b/UPGRADING.md index 0fbe9e9..8a3f48d 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -1,6 +1,6 @@ # Upgrading from v1 to v2 -This guide will help you migrate an existing codebase from the v1 Replicate Python SDK to v2. The v2 SDK is a complete rewrite generated in partnership with [Stainless](https://www.stainless.com/customers/replicate), the folks who help build and maintain SDKs for companies like OpenAI, Anthropic, and Cloudflare. The v2 SDK is largely autogenerated from Replicate's OpenAPI specification, providing better type safety, more consistent error handling, and improved async support. Check out the [v2 release notes](https://github.com/replicate/replicate-python-stainless/releases) for more details. +This guide will help you migrate an existing codebase from the v1 Replicate Python SDK to v2. The v2 SDK is a complete rewrite built in partnership with [Stainless](https://www.stainless.com/customers/replicate), the company that helps design and maintain SDKs for companies like OpenAI, Anthropic, and Cloudflare. The v2 SDK is largely autogenerated from Replicate's OpenAPI specification, providing better type safety, more consistent error handling, and improved async support. Check out the [v2 release notes](https://github.com/replicate/replicate-python-stainless/releases) for more details. ✋ If you are working on a new project, you don't need to read this document.

AltStyle によって変換されたページ (->オリジナル) /