From f849891b5aaef8fa074244e5ac8fc8e5f6a29e04 Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Wed, 24 Sep 2025 12:57:13 -0700 Subject: [PATCH 1/2] WIP --- api-template.md | 106 ++++ api.md | 948 +++++++++++++++++++++++++++---- pyproject.toml | 1 + scripts/update-api-docs | 8 + scripts/utils/update-api-docs.py | 306 ++++++++++ 5 files changed, 1271 insertions(+), 98 deletions(-) create mode 100644 api-template.md create mode 100755 scripts/update-api-docs create mode 100644 scripts/utils/update-api-docs.py diff --git a/api-template.md b/api-template.md new file mode 100644 index 0000000..e22c05c --- /dev/null +++ b/api-template.md @@ -0,0 +1,106 @@ +# Replicate Python SDK API reference + +## Installation + +```bash +pip install replicate +``` + +## Initialize a client + +Start by setting a `REPLICATE_API_TOKEN` environment variable in your environment. You can create a token at [replicate.com/account/api-tokens](https://replicate.com/account/api-tokens). + +Then use this code to initialize a client: + +```py +import replicate +``` + +That's it! You can now use the client to make API calls. + + +If you want to explicitly pass the token when creating a client, you can do so like this: + + +```python +import os +import replicate + +client = replicate.Replicate( + bearer_token=os.environ["REPLICATE_API_TOKEN"] +) +``` + +## High-level operations + +### `replicate.use()` + +Create a reference to a model that can be used to make predictions. + +```python +import replicate + +claude = replicate.use("anthropic/claude-sonnet-4") + +output = claude(prompt="Hello, world!") +print(output) + +banana = replicate.use("google/nano-banana") +output = banana(prompt="Make me a sandwich") +print(output) +``` + +Note: The `replicate.use()` method only returns output. If you need access to more metadata like prediction ID, status, metrics, or input values, use `replicate.predictions.create()` instead. + +### `replicate.run()` + +Run a model and wait for the output. This is a convenience method that creates a prediction and waits for it to complete. + +```python +import replicate + +# Run a model and get the output directly +output = replicate.run( + "anthropic/claude-sonnet-4", + input={"prompt": "Hello, world!"} +) +print(output) +``` + +Note: The `replicate.run()` method only returns output. If you need access to more metadata like prediction ID, status, metrics, or input values, use `replicate.predictions.create()` instead. + + +## API operations + + + +## Low-level API + +For cases where you need to make direct API calls not covered by the SDK methods, you can use the low-level request interface: + +### Making custom requests + +```python +import replicate + +client = replicate.Replicate() + +# Make a custom GET request +response = client.get("/custom/endpoint") + +# Make a custom POST request with data +response = client.post( + "/custom/endpoint", + json={"key": "value"} +) + +# Make a custom request with all options +response = client.request( + method="PATCH", + url="/custom/endpoint", + json={"key": "value"}, + headers={"X-Custom-Header": "value"} +) +``` + +See the [README](https://github.com/replicate/replicate-python-stainless/blob/main/README.md) for more details about response handing, error handling, pagination, async support, and more. diff --git a/api.md b/api.md index d037762..94f32ab 100644 --- a/api.md +++ b/api.md @@ -1,193 +1,945 @@ -# Replicate +# Replicate Python SDK API reference + +## Installation + +```bash +pip install replicate +``` + +## Initialize a client + +Start by setting a `REPLICATE_API_TOKEN` environment variable in your environment. You can create a token at [replicate.com/account/api-tokens](https://replicate.com/account/api-tokens). + +Then use this code to initialize a client: + +```py +import replicate +``` + +That's it! You can now use the client to make API calls. + + +If you want to explicitly pass the token when creating a client, you can do so like this: -Types: ```python -from replicate.types import SearchResponse +import os +import replicate + +client = replicate.Replicate( + bearer_token=os.environ["REPLICATE_API_TOKEN"] +) ``` -Methods: +## High-level operations + +### `replicate.use()` + +Create a reference to a model that can be used to make predictions. + +```python +import replicate + +claude = replicate.use("anthropic/claude-sonnet-4") + +output = claude(prompt="Hello, world!") +print(output) + +banana = replicate.use("google/nano-banana") +output = banana(prompt="Make me a sandwich") +print(output) +``` -- replicate.search(\*\*params) -> SearchResponse +Note: The `replicate.use()` method only returns output. If you need access to more metadata like prediction ID, status, metrics, or input values, use `replicate.predictions.create()` instead. -# Collections +### `replicate.run()` -Types: +Run a model and wait for the output. This is a convenience method that creates a prediction and waits for it to complete. ```python -from replicate.types import CollectionListResponse, CollectionGetResponse +import replicate + +# Run a model and get the output directly +output = replicate.run( + "anthropic/claude-sonnet-4", + input={"prompt": "Hello, world!"} +) +print(output) ``` -Methods: +Note: The `replicate.run()` method only returns output. If you need access to more metadata like prediction ID, status, metrics, or input values, use `replicate.predictions.create()` instead. + -- replicate.collections.list() -> SyncCursorURLPage[CollectionListResponse] -- replicate.collections.get(\*, collection_slug) -> CollectionGetResponse +## API operations + +### `search` + +Search models, collections, and docs (beta) + +Search for public models, collections, and docs using a text query. + +For models, the response includes all model data, plus a new `metadata` object with the following fields: + +- `generated_description`: A longer and more detailed AI-generated description of the model +- `tags`: An array of tags for the model +- `score`: A score for the model's relevance to the search query + +Example cURL request: + +```console +curl -s \ + -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ + "https://api.replicate.com/v1/search?query=nano+banana" +``` -# Deployments +Note: This search API is currently in beta and may change in future versions. -Types: ```python -from replicate.types import ( - DeploymentCreateResponse, - DeploymentUpdateResponse, - DeploymentListResponse, - DeploymentGetResponse, +response = replicate.search( + query="nano banana", ) +print(response.collections) ``` -Methods: +Docs: https://replicate.com/docs/reference/http#search -- replicate.deployments.create(\*\*params) -> DeploymentCreateResponse -- replicate.deployments.update(\*, deployment_owner, deployment_name, \*\*params) -> DeploymentUpdateResponse -- replicate.deployments.list() -> SyncCursorURLPage[DeploymentListResponse] -- replicate.deployments.delete(\*, deployment_owner, deployment_name) -> None -- replicate.deployments.get(\*, deployment_owner, deployment_name) -> DeploymentGetResponse +### `predictions.cancel` -## Predictions +Cancel a prediction -Methods: +Cancel a prediction that is currently running. -- replicate.deployments.predictions.create(\*, deployment_owner, deployment_name, \*\*params) -> Prediction +Example cURL request that creates a prediction and then cancels it: -# Hardware +```console +# First, create a prediction +PREDICTION_ID=$(curl -s -X POST \ + -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "input": { + "prompt": "a video that may take a while to generate" + } + }' \ + https://api.replicate.com/v1/models/minimax/video-01/predictions | jq -r '.id') + +# Echo the prediction ID +echo "Created prediction with ID: $PREDICTION_ID" + +# Cancel the prediction +curl -s -X POST \ + -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ + https://api.replicate.com/v1/predictions/$PREDICTION_ID/cancel +``` -Types: ```python -from replicate.types import HardwareListResponse +prediction = replicate.predictions.cancel( + prediction_id="prediction_id", +) +print(prediction.id) +``` + +Docs: https://replicate.com/docs/reference/http#predictions.cancel + +### `predictions.get` + +Get a prediction + +Get the current state of a prediction. + +Example cURL request: + +```console +curl -s \ + -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ + https://api.replicate.com/v1/predictions/gm3qorzdhgbfurvjtvhg6dckhu +``` + +The response will be the prediction object: + +```json +{ + "id": "gm3qorzdhgbfurvjtvhg6dckhu", + "model": "replicate/hello-world", + "version": "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa", + "input": { + "text": "Alice" + }, + "logs": "", + "output": "hello Alice", + "error": null, + "status": "succeeded", + "created_at": "2023-09-08T16:19:34.765994Z", + "data_removed": false, + "started_at": "2023-09-08T16:19:34.779176Z", + "completed_at": "2023-09-08T16:19:34.791859Z", + "metrics": { + "predict_time": 0.012683 + }, + "urls": { + "web": "https://replicate.com/p/gm3qorzdhgbfurvjtvhg6dckhu", + "get": "https://api.replicate.com/v1/predictions/gm3qorzdhgbfurvjtvhg6dckhu", + "cancel": "https://api.replicate.com/v1/predictions/gm3qorzdhgbfurvjtvhg6dckhu/cancel" + } +} +``` + +`status` will be one of: + +- `starting`: the prediction is starting up. If this status lasts longer than a few seconds, then it's typically because a new worker is being started to run the prediction. +- `processing`: the `predict()` method of the model is currently running. +- `succeeded`: the prediction completed successfully. +- `failed`: the prediction encountered an error during processing. +- `canceled`: the prediction was canceled by its creator. + +In the case of success, `output` will be an object containing the output of the model. Any files will be represented as HTTPS URLs. You'll need to pass the `Authorization` header to request them. + +In the case of failure, `error` will contain the error encountered during the prediction. + +Terminated predictions (with a status of `succeeded`, `failed`, or `canceled`) will include a `metrics` object with a `predict_time` property showing the amount of CPU or GPU time, in seconds, that the prediction used while running. It won't include time waiting for the prediction to start. + +All input parameters, output values, and logs are automatically removed after an hour, by default, for predictions created through the API. + +You must save a copy of any data or files in the output if you'd like to continue using them. The `output` key will still be present, but it's value will be `null` after the output has been removed. + +Output files are served by `replicate.delivery` and its subdomains. If you use an allow list of external domains for your assets, add `replicate.delivery` and `*.replicate.delivery` to it. + + +```python +prediction = replicate.predictions.get( + prediction_id="prediction_id", +) +print(prediction.id) +``` + +Docs: https://replicate.com/docs/reference/http#predictions.get + +### `trainings.create` + +Create a training + +Start a new training of the model version you specify. + +Example request body: + +```json +{ + "destination": "{new_owner}/{new_name}", + "input": { + "train_data": "https://example.com/my-input-images.zip", + }, + "webhook": "https://example.com/my-webhook", +} +``` + +Example cURL request: + +```console +curl -s -X POST \ + -d '{"destination": "{new_owner}/{new_name}", "input": {"input_images": "https://example.com/my-input-images.zip"}}' \ + -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ + -H 'Content-Type: application/json' \ + https://api.replicate.com/v1/models/stability-ai/sdxl/versions/da77bc59ee60423279fd632efb4795ab731d9e3ca9705ef3341091fb989b7eaf/trainings +``` + +The response will be the training object: + +```json +{ + "id": "zz4ibbonubfz7carwiefibzgga", + "model": "stability-ai/sdxl", + "version": "da77bc59ee60423279fd632efb4795ab731d9e3ca9705ef3341091fb989b7eaf", + "input": { + "input_images": "https://example.com/my-input-images.zip" + }, + "logs": "", + "error": null, + "status": "starting", + "created_at": "2023-09-08T16:32:56.990893084Z", + "urls": { + "web": "https://replicate.com/p/zz4ibbonubfz7carwiefibzgga", + "get": "https://api.replicate.com/v1/predictions/zz4ibbonubfz7carwiefibzgga", + "cancel": "https://api.replicate.com/v1/predictions/zz4ibbonubfz7carwiefibzgga/cancel" + } +} ``` -Methods: +As models can take several minutes or more to train, the result will not be available immediately. To get the final result of the training you should either provide a `webhook` HTTPS URL for us to call when the results are ready, or poll the [get a training](#trainings.get) endpoint until it has finished. -- replicate.hardware.list() -> HardwareListResponse +When a training completes, it creates a new [version](https://replicate.com/docs/how-does-replicate-work#terminology) of the model at the specified destination. -# Account +To find some models to train on, check out the [trainable language models collection](https://replicate.com/collections/trainable-language-models). -Types: ```python -from replicate.types import AccountGetResponse +training = replicate.trainings.create( + model_owner="model_owner", + model_name="model_name", + version_id="version_id", + destination="destination", + input={}, +) +print(training.id) +``` + +Docs: https://replicate.com/docs/reference/http#trainings.create + +### `models.versions.get` + +Get a model version + +Example cURL request: + +```console +curl -s \ + -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ + https://api.replicate.com/v1/models/replicate/hello-world/versions/5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa +``` + +The response will be the version object: + +```json +{ + "id": "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa", + "created_at": "2022-04-26T19:29:04.418669Z", + "cog_version": "0.3.0", + "openapi_schema": {...} +} +``` + +Every model describes its inputs and outputs with [OpenAPI Schema Objects](https://spec.openapis.org/oas/latest.html#schemaObject) in the `openapi_schema` property. + +The `openapi_schema.components.schemas.Input` property for the [replicate/hello-world](https://replicate.com/replicate/hello-world) model looks like this: + +```json +{ + "type": "object", + "title": "Input", + "required": [ + "text" + ], + "properties": { + "text": { + "x-order": 0, + "type": "string", + "title": "Text", + "description": "Text to prefix with 'hello '" + } + } +} ``` -Methods: +The `openapi_schema.components.schemas.Output` property for the [replicate/hello-world](https://replicate.com/replicate/hello-world) model looks like this: -- replicate.account.get() -> AccountGetResponse +```json +{ + "type": "string", + "title": "Output" +} +``` -# Models +For more details, see the docs on [Cog's supported input and output types](https://github.com/replicate/cog/blob/75b7802219e7cd4cee845e34c4c22139558615d4/docs/python.md#input-and-output-types) -Types: ```python -from replicate.types import ( - ModelCreateResponse, - ModelListResponse, - ModelGetResponse, - ModelSearchResponse, +version = replicate.models.versions.get( + model_owner="model_owner", + model_name="model_name", + version_id="version_id", ) +print(version.id) ``` -Methods: +Docs: https://replicate.com/docs/reference/http#models.versions.get -- replicate.models.create(\*\*params) -> ModelCreateResponse -- replicate.models.list() -> SyncCursorURLPage[ModelListResponse] -- replicate.models.delete(\*, model_owner, model_name) -> None -- replicate.models.get(\*, model_owner, model_name) -> ModelGetResponse -- replicate.models.search(\*\*params) -> SyncCursorURLPage[ModelSearchResponse] +### `models.versions.delete` -## Examples +Delete a model version -Methods: +Delete a model version and all associated predictions, including all output files. -- replicate.models.examples.list(\*, model_owner, model_name) -> SyncCursorURLPage[Prediction] +Model version deletion has some restrictions: -## Predictions +- You can only delete versions from models you own. +- You can only delete versions from private models. +- You cannot delete a version if someone other than you has run predictions with it. +- You cannot delete a version if it is being used as the base model for a fine tune/training. +- You cannot delete a version if it has an associated deployment. +- You cannot delete a version if another model version is overridden to use it. -Methods: +Example cURL request: -- replicate.models.predictions.create(\*, model_owner, model_name, \*\*params) -> Prediction +```command +curl -s -X DELETE \ + -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ + https://api.replicate.com/v1/models/replicate/hello-world/versions/5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa +``` -## Readme +The response will be an empty 202, indicating the deletion request has been accepted. It might take a few minutes to be processed. -Types: ```python -from replicate.types.models import ReadmeGetResponse +replicate.models.versions.delete( + model_owner="model_owner", + model_name="model_name", + version_id="version_id", +) ``` -Methods: +Docs: https://replicate.com/docs/reference/http#models.versions.delete + +### `collections.get` + +Get a collection of models -- replicate.models.readme.get(\*, model_owner, model_name) -> str +Example cURL request: -## Versions +```console +curl -s \ + -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ + https://api.replicate.com/v1/collections/super-resolution +``` + +The response will be a collection object with a nested list of the models in that collection: + +```json +{ + "name": "Super resolution", + "slug": "super-resolution", + "description": "Upscaling models that create high-quality images from low-quality images.", + "models": [...] +} +``` -Types: ```python -from replicate.types.models import VersionListResponse, VersionGetResponse +collection = replicate.collections.get( + collection_slug="collection_slug", +) +print(collection.description) ``` -Methods: +Docs: https://replicate.com/docs/reference/http#collections.get + +### `deployments.create` -- replicate.models.versions.list(\*, model_owner, model_name) -> SyncCursorURLPage[VersionListResponse] -- replicate.models.versions.delete(\*, model_owner, model_name, version_id) -> None -- replicate.models.versions.get(\*, model_owner, model_name, version_id) -> VersionGetResponse +Create a deployment -# Predictions +Create a new deployment: + +Example cURL request: + +```console +curl -s \ + -X POST \ + -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "my-app-image-generator", + "model": "stability-ai/sdxl", + "version": "da77bc59ee60423279fd632efb4795ab731d9e3ca9705ef3341091fb989b7eaf", + "hardware": "gpu-t4", + "min_instances": 0, + "max_instances": 3 + }' \ + https://api.replicate.com/v1/deployments +``` + +The response will be a JSON object describing the deployment: + +```json +{ + "owner": "acme", + "name": "my-app-image-generator", + "current_release": { + "number": 1, + "model": "stability-ai/sdxl", + "version": "da77bc59ee60423279fd632efb4795ab731d9e3ca9705ef3341091fb989b7eaf", + "created_at": "2024-02-15T16:32:57.018467Z", + "created_by": { + "type": "organization", + "username": "acme", + "name": "Acme Corp, Inc.", + "avatar_url": "https://cdn.replicate.com/avatars/acme.png", + "github_url": "https://github.com/acme" + }, + "configuration": { + "hardware": "gpu-t4", + "min_instances": 1, + "max_instances": 5 + } + } +} +``` -Types: ```python -from replicate.types import Prediction, PredictionOutput, PredictionRequest +deployment = replicate.deployments.create( + hardware="hardware", + max_instances=0, + min_instances=0, + model="model", + name="name", + version="version", +) +print(deployment.current_release) ``` -Methods: +Docs: https://replicate.com/docs/reference/http#deployments.create + +### `deployments.get` + +Get a deployment + +Get information about a deployment by name including the current release. + +Example cURL request: -- replicate.predictions.create(\*\*params) -> Prediction -- replicate.predictions.list(\*\*params) -> SyncCursorURLPageWithCreatedFilters[Prediction] -- replicate.predictions.cancel(\*, prediction_id) -> Prediction -- replicate.predictions.get(\*, prediction_id) -> Prediction +```console +curl -s \ + -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ + https://api.replicate.com/v1/deployments/replicate/my-app-image-generator +``` -# Trainings +The response will be a JSON object describing the deployment: + +```json +{ + "owner": "acme", + "name": "my-app-image-generator", + "current_release": { + "number": 1, + "model": "stability-ai/sdxl", + "version": "da77bc59ee60423279fd632efb4795ab731d9e3ca9705ef3341091fb989b7eaf", + "created_at": "2024-02-15T16:32:57.018467Z", + "created_by": { + "type": "organization", + "username": "acme", + "name": "Acme Corp, Inc.", + "avatar_url": "https://cdn.replicate.com/avatars/acme.png", + "github_url": "https://github.com/acme" + }, + "configuration": { + "hardware": "gpu-t4", + "min_instances": 1, + "max_instances": 5 + } + } +} +``` -Types: ```python -from replicate.types import ( - TrainingCreateResponse, - TrainingListResponse, - TrainingCancelResponse, - TrainingGetResponse, +deployment = replicate.deployments.get( + deployment_owner="deployment_owner", + deployment_name="deployment_name", ) +print(deployment.current_release) ``` -Methods: +Docs: https://replicate.com/docs/reference/http#deployments.get + +### `deployments.update` + +Update a deployment -- replicate.trainings.create(\*, model_owner, model_name, version_id, \*\*params) -> TrainingCreateResponse -- replicate.trainings.list() -> SyncCursorURLPage[TrainingListResponse] -- replicate.trainings.cancel(\*, training_id) -> TrainingCancelResponse -- replicate.trainings.get(\*, training_id) -> TrainingGetResponse +Update properties of an existing deployment, including hardware, min/max instances, and the deployment's underlying model [version](https://replicate.com/docs/how-does-replicate-work#versions). -# Webhooks +Example cURL request: -## Default +```console +curl -s \ + -X PATCH \ + -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"min_instances": 3, "max_instances": 10}' \ + https://api.replicate.com/v1/deployments/acme/my-app-image-generator +``` + +The response will be a JSON object describing the deployment: + +```json +{ + "owner": "acme", + "name": "my-app-image-generator", + "current_release": { + "number": 2, + "model": "stability-ai/sdxl", + "version": "da77bc59ee60423279fd632efb4795ab731d9e3ca9705ef3341091fb989b7eaf", + "created_at": "2024-02-15T16:32:57.018467Z", + "created_by": { + "type": "organization", + "username": "acme", + "name": "Acme Corp, Inc.", + "avatar_url": "https://cdn.replicate.com/avatars/acme.png", + "github_url": "https://github.com/acme" + }, + "configuration": { + "hardware": "gpu-t4", + "min_instances": 3, + "max_instances": 10 + } + } +} +``` -### Secret +Updating any deployment properties will increment the `number` field of the `current_release`. -Types: ```python -from replicate.types.webhooks.default import SecretGetResponse +deployment = replicate.deployments.update( + deployment_owner="deployment_owner", + deployment_name="deployment_name", +) +print(deployment.current_release) ``` -Methods: +Docs: https://replicate.com/docs/reference/http#deployments.update -- replicate.webhooks.default.secret.get() -> SecretGetResponse +### `deployments.delete` -# Files +Delete a deployment + +Delete a deployment + +Deployment deletion has some restrictions: + +- You can only delete deployments that have been offline and unused for at least 15 minutes. + +Example cURL request: + +```command +curl -s -X DELETE \ + -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ + https://api.replicate.com/v1/deployments/acme/my-app-image-generator +``` + +The response will be an empty 204, indicating the deployment has been deleted. -Types: ```python -from replicate.types import FileCreateResponse, FileListResponse, FileGetResponse +replicate.deployments.delete( + deployment_owner="deployment_owner", + deployment_name="deployment_name", +) +``` + +Docs: https://replicate.com/docs/reference/http#deployments.delete + +### `files.list` + +List files + +Get a paginated list of all files created by the user or organization associated with the provided API token. + +Example cURL request: + +```console +curl -s \ + -H "Authorization: Token $REPLICATE_API_TOKEN" \ + https://api.replicate.com/v1/files ``` + +The response will be a paginated JSON array of file objects, sorted with the most recent file first. + + +```python +page = replicate.files.list() +page = page.results[0] +print(page.id) +``` + +Docs: https://replicate.com/docs/reference/http#files.list + +### `files.create` + +Create a file + +Create a file by uploading its content and optional metadata. + +Example cURL request: + +```console +curl -X POST https://api.replicate.com/v1/files \ + -H "Authorization: Token $REPLICATE_API_TOKEN" \ + -H 'Content-Type: multipart/form-data' \ + -F 'content=@/path/to/archive.zip;type=application/zip;filename=example.zip' \ + -F 'metadata={"customer_reference_id": 123};type=application/json' +``` + +The request must include: +- `content`: The file content (required) +- `type`: The content / MIME type for the file (defaults to `application/octet-stream`) +- `filename`: The filename (required, ≤ 255 bytes, valid UTF-8) +- `metadata`: User-provided metadata associated with the file (defaults to `{}`, must be valid JSON) + + +```python +file = replicate.files.create( + content=b"raw file contents", +) +print(file.id) +``` + +Docs: https://replicate.com/docs/reference/http#files.create + +### `files.delete` + +Delete a file + +Delete a file. Once a file has been deleted, subsequent requests to the file resource return 404 Not found. + +Example cURL request: + +```console +curl -X DELETE \ + -H "Authorization: Token $REPLICATE_API_TOKEN" \ + https://api.replicate.com/v1/files/cneqzikepnug6xezperrr4z55o +``` + + +```python +replicate.files.delete( + file_id="file_id", +) +``` + +Docs: https://replicate.com/docs/reference/http#files.delete + +### `files.download` + +Download a file + +Download a file by providing the file owner, access expiry, and a valid signature. + +Example cURL request: + +```console +curl -X GET "https://api.replicate.com/v1/files/cneqzikepnug6xezperrr4z55o/download?expiry=1708515345&owner=mattt&signature=zuoghqlrcnw8YHywkpaXQlHsVhWen%2FDZ4aal76dLiOo%3D" +``` + + +```python +response = replicate.files.download( + file_id="file_id", + expiry=0, + owner="owner", + signature="signature", +) +print(response) +content = response.read() +print(content) +``` + +Docs: https://replicate.com/docs/reference/http#files.download + +### `trainings.cancel` + +Cancel a training + + +```python +response = replicate.trainings.cancel( + training_id="training_id", +) +print(response.id) +``` + +Docs: https://replicate.com/docs/reference/http#trainings.cancel + +### `trainings.get` + +Get a training + +Get the current state of a training. + +Example cURL request: + +```console +curl -s \ + -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ + https://api.replicate.com/v1/trainings/zz4ibbonubfz7carwiefibzgga +``` + +The response will be the training object: + +```json +{ + "completed_at": "2023-09-08T16:41:19.826523Z", + "created_at": "2023-09-08T16:32:57.018467Z", + "error": null, + "id": "zz4ibbonubfz7carwiefibzgga", + "input": { + "input_images": "https://example.com/my-input-images.zip" + }, + "logs": "...", + "metrics": { + "predict_time": 502.713876 + }, + "output": { + "version": "...", + "weights": "..." + }, + "started_at": "2023-09-08T16:32:57.112647Z", + "status": "succeeded", + "urls": { + "web": "https://replicate.com/p/zz4ibbonubfz7carwiefibzgga", + "get": "https://api.replicate.com/v1/trainings/zz4ibbonubfz7carwiefibzgga", + "cancel": "https://api.replicate.com/v1/trainings/zz4ibbonubfz7carwiefibzgga/cancel" + }, + "model": "stability-ai/sdxl", + "version": "da77bc59ee60423279fd632efb4795ab731d9e3ca9705ef3341091fb989b7eaf", +} +``` + +`status` will be one of: + +- `starting`: the training is starting up. If this status lasts longer than a few seconds, then it's typically because a new worker is being started to run the training. +- `processing`: the `train()` method of the model is currently running. +- `succeeded`: the training completed successfully. +- `failed`: the training encountered an error during processing. +- `canceled`: the training was canceled by its creator. + +In the case of success, `output` will be an object containing the output of the model. Any files will be represented as HTTPS URLs. You'll need to pass the `Authorization` header to request them. + +In the case of failure, `error` will contain the error encountered during the training. + +Terminated trainings (with a status of `succeeded`, `failed`, or `canceled`) will include a `metrics` object with a `predict_time` property showing the amount of CPU or GPU time, in seconds, that the training used while running. It won't include time waiting for the training to start. + + +```python +training = replicate.trainings.get( + training_id="training_id", +) +print(training.id) +``` + +Docs: https://replicate.com/docs/reference/http#trainings.get + +### `hardware.list` + +List available hardware for models + +Example cURL request: + +```console +curl -s \ + -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ + https://api.replicate.com/v1/hardware +``` + +The response will be a JSON array of hardware objects: + +```json +[ + {"name": "CPU", "sku": "cpu"}, + {"name": "Nvidia T4 GPU", "sku": "gpu-t4"}, + {"name": "Nvidia A40 GPU", "sku": "gpu-a40-small"}, + {"name": "Nvidia A40 (Large) GPU", "sku": "gpu-a40-large"}, +] +``` + + +```python +hardware = replicate.hardware.list() +print(hardware) +``` + +Docs: https://replicate.com/docs/reference/http#hardware.list + +### `account.get` + +Get the authenticated account + +Returns information about the user or organization associated with the provided API token. + +Example cURL request: + +```console +curl -s \ + -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ + https://api.replicate.com/v1/account +``` + +The response will be a JSON object describing the account: + +```json +{ + "type": "organization", + "username": "acme", + "name": "Acme Corp, Inc.", + "github_url": "https://github.com/acme", +} +``` + + +```python +account = replicate.account.get() +print(account.type) +``` + +Docs: https://replicate.com/docs/reference/http#account.get + +### `webhooks.default.secret.get` + +Get the signing secret for the default webhook + +Get the signing secret for the default webhook endpoint. This is used to verify that webhook requests are coming from Replicate. + +Example cURL request: + +```console +curl -s \ + -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ + https://api.replicate.com/v1/webhooks/default/secret +``` + +The response will be a JSON object with a `key` property: + +```json +{ + "key": "..." +} +``` + + +```python +secret = replicate.webhooks.default.secret.get() +print(secret.key) +``` + +Docs: https://replicate.com/docs/reference/http#webhooks.default.secret.get + + +## Low-level API + +For cases where you need to make direct API calls not covered by the SDK methods, you can use the low-level request interface: + +### Making custom requests + +```python +import replicate + +client = replicate.Replicate() + +# Make a custom GET request +response = client.get("/custom/endpoint") + +# Make a custom POST request with data +response = client.post( + "/custom/endpoint", + json={"key": "value"} +) + +# Make a custom request with all options +response = client.request( + method="PATCH", + url="/custom/endpoint", + json={"key": "value"}, + headers={"X-Custom-Header": "value"} +) +``` + +See the [README](https://github.com/replicate/replicate-python-stainless/blob/main/README.md) for more details about response handing, error handling, pagination, async support, and more. diff --git a/pyproject.toml b/pyproject.toml index 044be7f..c790881 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -70,6 +70,7 @@ format = { chain = [ ]} "format:docs" = "python scripts/utils/ruffen-docs.py README.md api.md" "format:ruff" = "ruff format" +"update-api-docs" = "python scripts/utils/update-api-docs.py" "lint" = { chain = [ "check:ruff", diff --git a/scripts/update-api-docs b/scripts/update-api-docs new file mode 100755 index 0000000..d84cd61 --- /dev/null +++ b/scripts/update-api-docs @@ -0,0 +1,8 @@ +#!/usr/bin/env bash + +set -e + +cd "$(dirname "$0")/.." + +echo "==> Updating API documentation" +python3 scripts/utils/update-api-docs.py \ No newline at end of file diff --git a/scripts/utils/update-api-docs.py b/scripts/utils/update-api-docs.py new file mode 100644 index 0000000..bfdc7ec --- /dev/null +++ b/scripts/utils/update-api-docs.py @@ -0,0 +1,306 @@ +#!/usr/bin/env python3 +""" +Script to generate API.md documentation from OpenAPI spec with code samples. +""" + +from __future__ import annotations + +import re +import sys +import json +import tempfile +import subprocess +from typing import Any +from pathlib import Path + + +def download_openapi_spec() -> dict[str, Any]: + """Download and parse the OpenAPI spec from Stainless.""" + import urllib.request + + spec_url = "https://app.stainless.com/api/spec/documented/replicate-client/openapi.documented.yml" + + print(f"Downloading OpenAPI spec from {spec_url}...") + + with urllib.request.urlopen(spec_url) as response: + yaml_content = response.read().decode("utf-8") + + # Save to temp file to dereference it + with tempfile.NamedTemporaryFile(mode="w", suffix=".yml", delete=False) as f: + f.write(yaml_content) + temp_path = f.name + + try: + # Try to use swagger-cli if available to dereference + result = subprocess.run( + ["npx", "@apidevtools/swagger-cli", "bundle", temp_path, "--dereference", "--type", "json"], + capture_output=True, + text=True, + ) + if result.returncode == 0: + spec = json.loads(result.stdout) + print("Successfully dereferenced OpenAPI spec using swagger-cli") + else: + # Fallback to PyYAML + import yaml + + with open(temp_path, "r") as f: + spec = yaml.safe_load(f) + print("Loaded OpenAPI spec using PyYAML (not dereferenced)") + finally: + Path(temp_path).unlink(missing_ok=True) + + return spec + + +def extract_operation_id(path: str, method: str, operation: dict[str, Any]) -> str: + """Extract operation ID from operation object.""" + if "operationId" in operation: + return operation["operationId"] + + # Fallback: generate from path and method + # Convert path like /models/{model_owner}/{model_name} to models_get + clean_path = path.strip("/").replace("{", "").replace("}", "").replace("/", "_") + return f"{clean_path}_{method}" + + +def remove_client_instantiation(code: str) -> str: + """Remove client instantiation code from examples.""" + # Pattern to match Replicate client instantiation + patterns = [ + # Multi-line instantiation + r"replicate\s*=\s*Replicate\s*\([^)]*\)\s*\n", + # Single-line instantiation + r"replicate\s*=\s*Replicate\s*\([^)]*\)", + # Import and instantiation in one + r"from replicate import Replicate\s*\n", + r"import replicate\s*\n\s*replicate\s*=\s*Replicate\s*\([^)]*\)\s*\n?", + # Client with bearer_token + r'client\s*=\s*replicate\.Replicate\s*\(\s*bearer_token\s*=\s*"[^"]*"\s*\)\s*\n?', + r'replicate\s*=\s*replicate\.Replicate\s*\(\s*bearer_token\s*=\s*"[^"]*"\s*\)\s*\n?', + ] + + cleaned = code + for pattern in patterns: + cleaned = re.sub(pattern, "", cleaned, flags=re.MULTILINE) + + # Clean up extra blank lines at the start + lines = cleaned.split("\n") + while lines and not lines[0].strip(): + lines.pop(0) + + return "\n".join(lines) + + +def format_operation(operation_id: str, operation: dict[str, Any]) -> str: + """Format a single operation as markdown.""" + summary = operation.get("summary", "").strip() + description = operation.get("description", "").strip() + + # Extract code sample + code_sample = "" + if "x-readme" in operation and "code-samples" in operation["x-readme"]: + samples = operation["x-readme"]["code-samples"] + # Look for Python sample + for sample in samples: + if sample.get("language") == "python" or sample.get("lang") == "python": + code = sample.get("code", "") + code = remove_client_instantiation(code) + if code: + code_sample = f"\n```python\n{code}\n```" + break + + # Generate docs link + docs_link = f"https://replicate.com/docs/reference/http#{operation_id}" + + # Build the markdown section + lines = [f"### `{operation_id}`", ""] + + if summary: + lines.append(summary) + lines.append("") + + if description and description != summary: + lines.append(description) + lines.append("") + + if code_sample: + lines.append(code_sample) + lines.append("") + + lines.append(f"Docs: {docs_link}") + lines.append("") + + return "\n".join(lines) + + +def get_ordered_operations(spec: dict[str, Any]) -> list[tuple[str, str, str, dict[str, Any]]]: + """Get operations in the specified order.""" + # Specified order from the Linear issue + operation_order = [ + "search", + "predictions.create", + "predictions.get", + "predictions.list", + "predictions.cancel", + "models.create", + "models.get", + "models.list", + "models.search", + "models.delete", + "models.examples.list", + "models.predictions.create", + "models.readme.get", + "models.versions.get", + "models.versions.list", + "models.versions.delete", + "collections.get", + "collections.list", + "deployments.create", + "deployments.get", + "deployments.list", + "deployments.update", + "deployments.delete", + "deployments.predictions.create", + "files.list", + "files.create", + "files.delete", + "files.get", + "files.download", + "trainings.create", + "trainings.get", + "trainings.list", + "trainings.cancel", + "hardware.list", + "account.get", + "webhooks.default.secret.get", + ] + + operations: dict[str, tuple[str, str, str, dict[str, Any]]] = {} + + # Extract all operations from paths + for path, path_obj in spec.get("paths", {}).items(): + for method in ["get", "post", "put", "patch", "delete"]: + if method in path_obj: + operation = path_obj[method] + op_id = extract_operation_id(path, method, operation) + + # Try to match with our ordered list + matched_name = None + for ordered_name in operation_order: + # Convert ordered name to possible operation IDs + # e.g., "predictions.create" might be "predictionsCreate" or "predictions_create" + variants = [ + ordered_name, + ordered_name.replace(".", "_"), + ordered_name.replace(".", ""), + "".join(word.capitalize() if i > 0 else word for i, word in enumerate(ordered_name.split("."))), + ] + + if op_id in variants or any(v.lower() == op_id.lower() for v in variants): + matched_name = ordered_name + break + + # Also check if the operation path matches + path_parts = path.strip("/").split("/") + ordered_parts = ordered_name.split(".") + + # Match by path structure + if len(ordered_parts) >= 2: + resource = ordered_parts[0] + action = ordered_parts[-1] + + # Check if path contains the resource name + if resource in path and action.lower() == method: + matched_name = ordered_name + break + elif resource in path and action in ["create"] and method == "post": + matched_name = ordered_name + break + elif resource in path and action in ["list", "get"] and method == "get": + # Differentiate between list and get + if "{" in path and action == "get": + matched_name = ordered_name + break + elif "{" not in path and action == "list": + matched_name = ordered_name + break + elif resource in path and action in ["update"] and method in ["put", "patch"]: + matched_name = ordered_name + break + elif resource in path and action in ["delete"] and method == "delete": + matched_name = ordered_name + break + + key = matched_name or op_id + operations[key] = (op_id, path, method, operation) + + # Order operations according to the specified list + ordered = [] + added_keys = set() + + for name in operation_order: + if name in operations: + ordered.append(operations[name]) + added_keys.add(name) + + # Add any remaining operations not in the ordered list + for key, value in operations.items(): + if key not in added_keys: + ordered.append(value) + + return ordered + + +def generate_api_docs(spec: dict[str, Any]) -> str: + """Generate the API operations documentation.""" + lines = [] + operations = get_ordered_operations(spec) + + for op_id, _path, _method, operation in operations: + lines.append(format_operation(op_id, operation)) + + return "\n".join(lines) + + +def update_api_md(): + """Main function to update api.md file.""" + # Paths + project_root = Path(__file__).parent.parent.parent + template_path = project_root / "api-template.md" + output_path = project_root / "api.md" + + # Download and parse OpenAPI spec + try: + spec = download_openapi_spec() + except Exception as e: + print(f"Error downloading OpenAPI spec: {e}", file=sys.stderr) + sys.exit(1) + + # Read template + if not template_path.exists(): + print(f"Template file not found: {template_path}", file=sys.stderr) + sys.exit(1) + + with open(template_path, "r") as f: + template_content = f.read() + + # Generate API operations documentation + api_docs = generate_api_docs(spec) + + # Replace placeholder in template + if "" not in template_content: + print("Warning: placeholder not found in template", file=sys.stderr) + final_content = template_content + "\n\n" + api_docs + else: + final_content = template_content.replace("", api_docs) + + # Write output + with open(output_path, "w") as f: + f.write(final_content) + + print(f"Successfully updated {output_path}") + + +if __name__ == "__main__": + update_api_md() From 56d4b589f77a45e1277af230a11244111f811899 Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Wed, 24 Sep 2025 13:28:40 -0700 Subject: [PATCH 2/2] list operations --- api.md | 812 ++++++++++++------------------- scripts/utils/update-api-docs.py | 97 ++-- 2 files changed, 352 insertions(+), 557 deletions(-) diff --git a/api.md b/api.md index 94f32ab..c6c966f 100644 --- a/api.md +++ b/api.md @@ -72,28 +72,48 @@ Note: The `replicate.run()` method only returns output. If you need access to mo ## API operations +Available operations: + +- [`search`](#search) +- [`predictions.create`](#predictionscreate) +- [`predictions.get`](#predictionsget) +- [`predictions.list`](#predictionslist) +- [`predictions.cancel`](#predictionscancel) +- [`models.create`](#modelscreate) +- [`models.get`](#modelsget) +- [`models.list`](#modelslist) +- [`models.delete`](#modelsdelete) +- [`models.examples.list`](#modelsexampleslist) +- [`models.predictions.create`](#modelspredictionscreate) +- [`models.readme.get`](#modelsreadmeget) +- [`models.versions.get`](#modelsversionsget) +- [`models.versions.list`](#modelsversionslist) +- [`models.versions.delete`](#modelsversionsdelete) +- [`collections.get`](#collectionsget) +- [`collections.list`](#collectionslist) +- [`deployments.create`](#deploymentscreate) +- [`deployments.get`](#deploymentsget) +- [`deployments.list`](#deploymentslist) +- [`deployments.update`](#deploymentsupdate) +- [`deployments.delete`](#deploymentsdelete) +- [`deployments.predictions.create`](#deploymentspredictionscreate) +- [`files.list`](#fileslist) +- [`files.create`](#filescreate) +- [`files.delete`](#filesdelete) +- [`files.get`](#filesget) +- [`files.download`](#filesdownload) +- [`trainings.create`](#trainingscreate) +- [`trainings.get`](#trainingsget) +- [`trainings.list`](#trainingslist) +- [`trainings.cancel`](#trainingscancel) +- [`hardware.list`](#hardwarelist) +- [`account.get`](#accountget) +- [`webhooks.default.secret.get`](#webhooksdefaultsecretget) + ### `search` Search models, collections, and docs (beta) -Search for public models, collections, and docs using a text query. - -For models, the response includes all model data, plus a new `metadata` object with the following fields: - -- `generated_description`: A longer and more detailed AI-generated description of the model -- `tags`: An array of tags for the model -- `score`: A score for the model's relevance to the search query - -Example cURL request: - -```console -curl -s \ - -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ - "https://api.replicate.com/v1/search?query=nano+banana" -``` - -Note: This search API is currently in beta and may change in future versions. - ```python response = replicate.search( @@ -104,243 +124,200 @@ print(response.collections) Docs: https://replicate.com/docs/reference/http#search -### `predictions.cancel` +--- -Cancel a prediction +### `predictions.create` -Cancel a prediction that is currently running. +Create a prediction -Example cURL request that creates a prediction and then cancels it: -```console -# First, create a prediction -PREDICTION_ID=$(curl -s -X POST \ - -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "input": { - "prompt": "a video that may take a while to generate" - } - }' \ - https://api.replicate.com/v1/models/minimax/video-01/predictions | jq -r '.id') +```python +prediction = replicate.predictions.create( + input={ + "text": "Alice" + }, + version="replicate/hello-world:9dcd6d78e7c6560c340d916fe32e9f24aabfa331e5cce95fe31f77fb03121426", +) +print(prediction.id) +``` -# Echo the prediction ID -echo "Created prediction with ID: $PREDICTION_ID" +Docs: https://replicate.com/docs/reference/http#predictions.create -# Cancel the prediction -curl -s -X POST \ - -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ - https://api.replicate.com/v1/predictions/$PREDICTION_ID/cancel -``` +--- + +### `predictions.get` + +Get a prediction ```python -prediction = replicate.predictions.cancel( +prediction = replicate.predictions.get( prediction_id="prediction_id", ) print(prediction.id) ``` -Docs: https://replicate.com/docs/reference/http#predictions.cancel +Docs: https://replicate.com/docs/reference/http#predictions.get -### `predictions.get` +--- -Get a prediction +### `predictions.list` -Get the current state of a prediction. +List predictions -Example cURL request: -```console -curl -s \ - -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ - https://api.replicate.com/v1/predictions/gm3qorzdhgbfurvjtvhg6dckhu +```python +page = replicate.predictions.list() +page = page.results[0] +print(page.id) ``` -The response will be the prediction object: +Docs: https://replicate.com/docs/reference/http#predictions.list -```json -{ - "id": "gm3qorzdhgbfurvjtvhg6dckhu", - "model": "replicate/hello-world", - "version": "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa", - "input": { - "text": "Alice" - }, - "logs": "", - "output": "hello Alice", - "error": null, - "status": "succeeded", - "created_at": "2023-09-08T16:19:34.765994Z", - "data_removed": false, - "started_at": "2023-09-08T16:19:34.779176Z", - "completed_at": "2023-09-08T16:19:34.791859Z", - "metrics": { - "predict_time": 0.012683 - }, - "urls": { - "web": "https://replicate.com/p/gm3qorzdhgbfurvjtvhg6dckhu", - "get": "https://api.replicate.com/v1/predictions/gm3qorzdhgbfurvjtvhg6dckhu", - "cancel": "https://api.replicate.com/v1/predictions/gm3qorzdhgbfurvjtvhg6dckhu/cancel" - } -} -``` +--- -`status` will be one of: +### `predictions.cancel` -- `starting`: the prediction is starting up. If this status lasts longer than a few seconds, then it's typically because a new worker is being started to run the prediction. -- `processing`: the `predict()` method of the model is currently running. -- `succeeded`: the prediction completed successfully. -- `failed`: the prediction encountered an error during processing. -- `canceled`: the prediction was canceled by its creator. +Cancel a prediction -In the case of success, `output` will be an object containing the output of the model. Any files will be represented as HTTPS URLs. You'll need to pass the `Authorization` header to request them. -In the case of failure, `error` will contain the error encountered during the prediction. +```python +prediction = replicate.predictions.cancel( + prediction_id="prediction_id", +) +print(prediction.id) +``` -Terminated predictions (with a status of `succeeded`, `failed`, or `canceled`) will include a `metrics` object with a `predict_time` property showing the amount of CPU or GPU time, in seconds, that the prediction used while running. It won't include time waiting for the prediction to start. +Docs: https://replicate.com/docs/reference/http#predictions.cancel -All input parameters, output values, and logs are automatically removed after an hour, by default, for predictions created through the API. +--- -You must save a copy of any data or files in the output if you'd like to continue using them. The `output` key will still be present, but it's value will be `null` after the output has been removed. +### `models.create` -Output files are served by `replicate.delivery` and its subdomains. If you use an allow list of external domains for your assets, add `replicate.delivery` and `*.replicate.delivery` to it. +Create a model ```python -prediction = replicate.predictions.get( - prediction_id="prediction_id", +model = replicate.models.create( + hardware="cpu", + name="hot-dog-detector", + owner="alice", + visibility="public", ) -print(prediction.id) +print(model.cover_image_url) ``` -Docs: https://replicate.com/docs/reference/http#predictions.get +Docs: https://replicate.com/docs/reference/http#models.create -### `trainings.create` +--- -Create a training +### `models.get` -Start a new training of the model version you specify. +Get a model -Example request body: -```json -{ - "destination": "{new_owner}/{new_name}", - "input": { - "train_data": "https://example.com/my-input-images.zip", - }, - "webhook": "https://example.com/my-webhook", -} +```python +model = replicate.models.get( + model_owner="model_owner", + model_name="model_name", +) +print(model.cover_image_url) ``` -Example cURL request: +Docs: https://replicate.com/docs/reference/http#models.get -```console -curl -s -X POST \ - -d '{"destination": "{new_owner}/{new_name}", "input": {"input_images": "https://example.com/my-input-images.zip"}}' \ - -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ - -H 'Content-Type: application/json' \ - https://api.replicate.com/v1/models/stability-ai/sdxl/versions/da77bc59ee60423279fd632efb4795ab731d9e3ca9705ef3341091fb989b7eaf/trainings -``` +--- + +### `models.list` -The response will be the training object: +List public models -```json -{ - "id": "zz4ibbonubfz7carwiefibzgga", - "model": "stability-ai/sdxl", - "version": "da77bc59ee60423279fd632efb4795ab731d9e3ca9705ef3341091fb989b7eaf", - "input": { - "input_images": "https://example.com/my-input-images.zip" - }, - "logs": "", - "error": null, - "status": "starting", - "created_at": "2023-09-08T16:32:56.990893084Z", - "urls": { - "web": "https://replicate.com/p/zz4ibbonubfz7carwiefibzgga", - "get": "https://api.replicate.com/v1/predictions/zz4ibbonubfz7carwiefibzgga", - "cancel": "https://api.replicate.com/v1/predictions/zz4ibbonubfz7carwiefibzgga/cancel" - } -} + +```python +page = replicate.models.list() +page = page.results[0] +print(page.cover_image_url) ``` -As models can take several minutes or more to train, the result will not be available immediately. To get the final result of the training you should either provide a `webhook` HTTPS URL for us to call when the results are ready, or poll the [get a training](#trainings.get) endpoint until it has finished. +Docs: https://replicate.com/docs/reference/http#models.list + +--- -When a training completes, it creates a new [version](https://replicate.com/docs/how-does-replicate-work#terminology) of the model at the specified destination. +### `models.delete` -To find some models to train on, check out the [trainable language models collection](https://replicate.com/collections/trainable-language-models). +Delete a model ```python -training = replicate.trainings.create( +replicate.models.delete( model_owner="model_owner", model_name="model_name", - version_id="version_id", - destination="destination", - input={}, ) -print(training.id) ``` -Docs: https://replicate.com/docs/reference/http#trainings.create +Docs: https://replicate.com/docs/reference/http#models.delete -### `models.versions.get` +--- -Get a model version +### `models.examples.list` + +List examples for a model -Example cURL request: -```console -curl -s \ - -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ - https://api.replicate.com/v1/models/replicate/hello-world/versions/5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa +```python +page = replicate.models.examples.list( + model_owner="model_owner", + model_name="model_name", +) +page = page.results[0] +print(page.id) ``` -The response will be the version object: +Docs: https://replicate.com/docs/reference/http#models.examples.list -```json -{ - "id": "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa", - "created_at": "2022-04-26T19:29:04.418669Z", - "cog_version": "0.3.0", - "openapi_schema": {...} -} -``` +--- + +### `models.predictions.create` -Every model describes its inputs and outputs with [OpenAPI Schema Objects](https://spec.openapis.org/oas/latest.html#schemaObject) in the `openapi_schema` property. +Create a prediction using an official model -The `openapi_schema.components.schemas.Input` property for the [replicate/hello-world](https://replicate.com/replicate/hello-world) model looks like this: -```json -{ - "type": "object", - "title": "Input", - "required": [ - "text" - ], - "properties": { - "text": { - "x-order": 0, - "type": "string", - "title": "Text", - "description": "Text to prefix with 'hello '" - } - } -} +```python +prediction = replicate.models.predictions.create( + model_owner="model_owner", + model_name="model_name", + input={ + "prompt": "Tell me a joke", + "system_prompt": "You are a helpful assistant", + }, +) +print(prediction.id) ``` -The `openapi_schema.components.schemas.Output` property for the [replicate/hello-world](https://replicate.com/replicate/hello-world) model looks like this: +Docs: https://replicate.com/docs/reference/http#models.predictions.create -```json -{ - "type": "string", - "title": "Output" -} +--- + +### `models.readme.get` + +Get a model's README + + +```python +readme = replicate.models.readme.get( + model_owner="model_owner", + model_name="model_name", +) +print(readme) ``` -For more details, see the docs on [Cog's supported input and output types](https://github.com/replicate/cog/blob/75b7802219e7cd4cee845e34c4c22139558615d4/docs/python.md#input-and-output-types) +Docs: https://replicate.com/docs/reference/http#models.readme.get + +--- + +### `models.versions.get` + +Get a model version ```python @@ -354,30 +331,29 @@ print(version.id) Docs: https://replicate.com/docs/reference/http#models.versions.get -### `models.versions.delete` +--- -Delete a model version +### `models.versions.list` -Delete a model version and all associated predictions, including all output files. +List model versions -Model version deletion has some restrictions: -- You can only delete versions from models you own. -- You can only delete versions from private models. -- You cannot delete a version if someone other than you has run predictions with it. -- You cannot delete a version if it is being used as the base model for a fine tune/training. -- You cannot delete a version if it has an associated deployment. -- You cannot delete a version if another model version is overridden to use it. +```python +page = replicate.models.versions.list( + model_owner="model_owner", + model_name="model_name", +) +page = page.results[0] +print(page.id) +``` -Example cURL request: +Docs: https://replicate.com/docs/reference/http#models.versions.list -```command -curl -s -X DELETE \ - -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ - https://api.replicate.com/v1/models/replicate/hello-world/versions/5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa -``` +--- -The response will be an empty 202, indicating the deletion request has been accepted. It might take a few minutes to be processed. +### `models.versions.delete` + +Delete a model version ```python @@ -390,29 +366,12 @@ replicate.models.versions.delete( Docs: https://replicate.com/docs/reference/http#models.versions.delete +--- + ### `collections.get` Get a collection of models -Example cURL request: - -```console -curl -s \ - -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ - https://api.replicate.com/v1/collections/super-resolution -``` - -The response will be a collection object with a nested list of the models in that collection: - -```json -{ - "name": "Super resolution", - "slug": "super-resolution", - "description": "Upscaling models that create high-quality images from low-quality images.", - "models": [...] -} -``` - ```python collection = replicate.collections.get( @@ -423,57 +382,27 @@ print(collection.description) Docs: https://replicate.com/docs/reference/http#collections.get -### `deployments.create` +--- -Create a deployment +### `collections.list` -Create a new deployment: - -Example cURL request: - -```console -curl -s \ - -X POST \ - -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "my-app-image-generator", - "model": "stability-ai/sdxl", - "version": "da77bc59ee60423279fd632efb4795ab731d9e3ca9705ef3341091fb989b7eaf", - "hardware": "gpu-t4", - "min_instances": 0, - "max_instances": 3 - }' \ - https://api.replicate.com/v1/deployments -``` - -The response will be a JSON object describing the deployment: - -```json -{ - "owner": "acme", - "name": "my-app-image-generator", - "current_release": { - "number": 1, - "model": "stability-ai/sdxl", - "version": "da77bc59ee60423279fd632efb4795ab731d9e3ca9705ef3341091fb989b7eaf", - "created_at": "2024-02-15T16:32:57.018467Z", - "created_by": { - "type": "organization", - "username": "acme", - "name": "Acme Corp, Inc.", - "avatar_url": "https://cdn.replicate.com/avatars/acme.png", - "github_url": "https://github.com/acme" - }, - "configuration": { - "hardware": "gpu-t4", - "min_instances": 1, - "max_instances": 5 - } - } -} +List collections of models + + +```python +page = replicate.collections.list() +page = page.results[0] +print(page.description) ``` +Docs: https://replicate.com/docs/reference/http#collections.list + +--- + +### `deployments.create` + +Create a deployment + ```python deployment = replicate.deployments.create( @@ -489,47 +418,12 @@ print(deployment.current_release) Docs: https://replicate.com/docs/reference/http#deployments.create +--- + ### `deployments.get` Get a deployment -Get information about a deployment by name including the current release. - -Example cURL request: - -```console -curl -s \ - -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ - https://api.replicate.com/v1/deployments/replicate/my-app-image-generator -``` - -The response will be a JSON object describing the deployment: - -```json -{ - "owner": "acme", - "name": "my-app-image-generator", - "current_release": { - "number": 1, - "model": "stability-ai/sdxl", - "version": "da77bc59ee60423279fd632efb4795ab731d9e3ca9705ef3341091fb989b7eaf", - "created_at": "2024-02-15T16:32:57.018467Z", - "created_by": { - "type": "organization", - "username": "acme", - "name": "Acme Corp, Inc.", - "avatar_url": "https://cdn.replicate.com/avatars/acme.png", - "github_url": "https://github.com/acme" - }, - "configuration": { - "hardware": "gpu-t4", - "min_instances": 1, - "max_instances": 5 - } - } -} -``` - ```python deployment = replicate.deployments.get( @@ -541,51 +435,26 @@ print(deployment.current_release) Docs: https://replicate.com/docs/reference/http#deployments.get -### `deployments.update` +--- -Update a deployment +### `deployments.list` -Update properties of an existing deployment, including hardware, min/max instances, and the deployment's underlying model [version](https://replicate.com/docs/how-does-replicate-work#versions). - -Example cURL request: - -```console -curl -s \ - -X PATCH \ - -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"min_instances": 3, "max_instances": 10}' \ - https://api.replicate.com/v1/deployments/acme/my-app-image-generator -``` - -The response will be a JSON object describing the deployment: - -```json -{ - "owner": "acme", - "name": "my-app-image-generator", - "current_release": { - "number": 2, - "model": "stability-ai/sdxl", - "version": "da77bc59ee60423279fd632efb4795ab731d9e3ca9705ef3341091fb989b7eaf", - "created_at": "2024-02-15T16:32:57.018467Z", - "created_by": { - "type": "organization", - "username": "acme", - "name": "Acme Corp, Inc.", - "avatar_url": "https://cdn.replicate.com/avatars/acme.png", - "github_url": "https://github.com/acme" - }, - "configuration": { - "hardware": "gpu-t4", - "min_instances": 3, - "max_instances": 10 - } - } -} +List deployments + + +```python +page = replicate.deployments.list() +page = page.results[0] +print(page.current_release) ``` -Updating any deployment properties will increment the `number` field of the `current_release`. +Docs: https://replicate.com/docs/reference/http#deployments.list + +--- + +### `deployments.update` + +Update a deployment ```python @@ -598,52 +467,49 @@ print(deployment.current_release) Docs: https://replicate.com/docs/reference/http#deployments.update +--- + ### `deployments.delete` Delete a deployment -Delete a deployment -Deployment deletion has some restrictions: +```python +replicate.deployments.delete( + deployment_owner="deployment_owner", + deployment_name="deployment_name", +) +``` -- You can only delete deployments that have been offline and unused for at least 15 minutes. +Docs: https://replicate.com/docs/reference/http#deployments.delete -Example cURL request: +--- -```command -curl -s -X DELETE \ - -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ - https://api.replicate.com/v1/deployments/acme/my-app-image-generator -``` +### `deployments.predictions.create` -The response will be an empty 204, indicating the deployment has been deleted. +Create a prediction using a deployment ```python -replicate.deployments.delete( +prediction = replicate.deployments.predictions.create( deployment_owner="deployment_owner", deployment_name="deployment_name", + input={ + "prompt": "Tell me a joke", + "system_prompt": "You are a helpful assistant", + }, ) +print(prediction.id) ``` -Docs: https://replicate.com/docs/reference/http#deployments.delete +Docs: https://replicate.com/docs/reference/http#deployments.predictions.create + +--- ### `files.list` List files -Get a paginated list of all files created by the user or organization associated with the provided API token. - -Example cURL request: - -```console -curl -s \ - -H "Authorization: Token $REPLICATE_API_TOKEN" \ - https://api.replicate.com/v1/files -``` - -The response will be a paginated JSON array of file objects, sorted with the most recent file first. - ```python page = replicate.files.list() @@ -653,28 +519,12 @@ print(page.id) Docs: https://replicate.com/docs/reference/http#files.list +--- + ### `files.create` Create a file -Create a file by uploading its content and optional metadata. - -Example cURL request: - -```console -curl -X POST https://api.replicate.com/v1/files \ - -H "Authorization: Token $REPLICATE_API_TOKEN" \ - -H 'Content-Type: multipart/form-data' \ - -F 'content=@/path/to/archive.zip;type=application/zip;filename=example.zip' \ - -F 'metadata={"customer_reference_id": 123};type=application/json' -``` - -The request must include: -- `content`: The file content (required) -- `type`: The content / MIME type for the file (defaults to `application/octet-stream`) -- `filename`: The filename (required, ≤ 255 bytes, valid UTF-8) -- `metadata`: User-provided metadata associated with the file (defaults to `{}`, must be valid JSON) - ```python file = replicate.files.create( @@ -685,20 +535,12 @@ print(file.id) Docs: https://replicate.com/docs/reference/http#files.create +--- + ### `files.delete` Delete a file -Delete a file. Once a file has been deleted, subsequent requests to the file resource return 404 Not found. - -Example cURL request: - -```console -curl -X DELETE \ - -H "Authorization: Token $REPLICATE_API_TOKEN" \ - https://api.replicate.com/v1/files/cneqzikepnug6xezperrr4z55o -``` - ```python replicate.files.delete( @@ -708,18 +550,28 @@ replicate.files.delete( Docs: https://replicate.com/docs/reference/http#files.delete -### `files.download` +--- -Download a file +### `files.get` -Download a file by providing the file owner, access expiry, and a valid signature. +Get a file -Example cURL request: -```console -curl -X GET "https://api.replicate.com/v1/files/cneqzikepnug6xezperrr4z55o/download?expiry=1708515345&owner=mattt&signature=zuoghqlrcnw8YHywkpaXQlHsVhWen%2FDZ4aal76dLiOo%3D" +```python +file = replicate.files.get( + file_id="file_id", +) +print(file.id) ``` +Docs: https://replicate.com/docs/reference/http#files.get + +--- + +### `files.download` + +Download a file + ```python response = replicate.files.download( @@ -735,112 +587,79 @@ print(content) Docs: https://replicate.com/docs/reference/http#files.download -### `trainings.cancel` +--- -Cancel a training +### `trainings.create` + +Create a training ```python -response = replicate.trainings.cancel( - training_id="training_id", +training = replicate.trainings.create( + model_owner="model_owner", + model_name="model_name", + version_id="version_id", + destination="destination", + input={}, ) -print(response.id) +print(training.id) ``` -Docs: https://replicate.com/docs/reference/http#trainings.cancel +Docs: https://replicate.com/docs/reference/http#trainings.create + +--- ### `trainings.get` Get a training -Get the current state of a training. - -Example cURL request: -```console -curl -s \ - -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ - https://api.replicate.com/v1/trainings/zz4ibbonubfz7carwiefibzgga +```python +training = replicate.trainings.get( + training_id="training_id", +) +print(training.id) ``` -The response will be the training object: +Docs: https://replicate.com/docs/reference/http#trainings.get -```json -{ - "completed_at": "2023-09-08T16:41:19.826523Z", - "created_at": "2023-09-08T16:32:57.018467Z", - "error": null, - "id": "zz4ibbonubfz7carwiefibzgga", - "input": { - "input_images": "https://example.com/my-input-images.zip" - }, - "logs": "...", - "metrics": { - "predict_time": 502.713876 - }, - "output": { - "version": "...", - "weights": "..." - }, - "started_at": "2023-09-08T16:32:57.112647Z", - "status": "succeeded", - "urls": { - "web": "https://replicate.com/p/zz4ibbonubfz7carwiefibzgga", - "get": "https://api.replicate.com/v1/trainings/zz4ibbonubfz7carwiefibzgga", - "cancel": "https://api.replicate.com/v1/trainings/zz4ibbonubfz7carwiefibzgga/cancel" - }, - "model": "stability-ai/sdxl", - "version": "da77bc59ee60423279fd632efb4795ab731d9e3ca9705ef3341091fb989b7eaf", -} -``` +--- -`status` will be one of: +### `trainings.list` -- `starting`: the training is starting up. If this status lasts longer than a few seconds, then it's typically because a new worker is being started to run the training. -- `processing`: the `train()` method of the model is currently running. -- `succeeded`: the training completed successfully. -- `failed`: the training encountered an error during processing. -- `canceled`: the training was canceled by its creator. +List trainings -In the case of success, `output` will be an object containing the output of the model. Any files will be represented as HTTPS URLs. You'll need to pass the `Authorization` header to request them. -In the case of failure, `error` will contain the error encountered during the training. +```python +page = replicate.trainings.list() +page = page.results[0] +print(page.id) +``` + +Docs: https://replicate.com/docs/reference/http#trainings.list + +--- + +### `trainings.cancel` -Terminated trainings (with a status of `succeeded`, `failed`, or `canceled`) will include a `metrics` object with a `predict_time` property showing the amount of CPU or GPU time, in seconds, that the training used while running. It won't include time waiting for the training to start. +Cancel a training ```python -training = replicate.trainings.get( +response = replicate.trainings.cancel( training_id="training_id", ) -print(training.id) +print(response.id) ``` -Docs: https://replicate.com/docs/reference/http#trainings.get +Docs: https://replicate.com/docs/reference/http#trainings.cancel + +--- ### `hardware.list` List available hardware for models -Example cURL request: - -```console -curl -s \ - -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ - https://api.replicate.com/v1/hardware -``` - -The response will be a JSON array of hardware objects: - -```json -[ - {"name": "CPU", "sku": "cpu"}, - {"name": "Nvidia T4 GPU", "sku": "gpu-t4"}, - {"name": "Nvidia A40 GPU", "sku": "gpu-a40-small"}, - {"name": "Nvidia A40 (Large) GPU", "sku": "gpu-a40-large"}, -] -``` - ```python hardware = replicate.hardware.list() @@ -849,31 +668,12 @@ print(hardware) Docs: https://replicate.com/docs/reference/http#hardware.list +--- + ### `account.get` Get the authenticated account -Returns information about the user or organization associated with the provided API token. - -Example cURL request: - -```console -curl -s \ - -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ - https://api.replicate.com/v1/account -``` - -The response will be a JSON object describing the account: - -```json -{ - "type": "organization", - "username": "acme", - "name": "Acme Corp, Inc.", - "github_url": "https://github.com/acme", -} -``` - ```python account = replicate.account.get() @@ -882,28 +682,12 @@ print(account.type) Docs: https://replicate.com/docs/reference/http#account.get +--- + ### `webhooks.default.secret.get` Get the signing secret for the default webhook -Get the signing secret for the default webhook endpoint. This is used to verify that webhook requests are coming from Replicate. - -Example cURL request: - -```console -curl -s \ - -H "Authorization: Bearer $REPLICATE_API_TOKEN" \ - https://api.replicate.com/v1/webhooks/default/secret -``` - -The response will be a JSON object with a `key` property: - -```json -{ - "key": "..." -} -``` - ```python secret = replicate.webhooks.default.secret.get() @@ -912,6 +696,8 @@ print(secret.key) Docs: https://replicate.com/docs/reference/http#webhooks.default.secret.get +--- + ## Low-level API diff --git a/scripts/utils/update-api-docs.py b/scripts/utils/update-api-docs.py index bfdc7ec..acb3538 100644 --- a/scripts/utils/update-api-docs.py +++ b/scripts/utils/update-api-docs.py @@ -95,7 +95,6 @@ def remove_client_instantiation(code: str) -> str: def format_operation(operation_id: str, operation: dict[str, Any]) -> str: """Format a single operation as markdown.""" summary = operation.get("summary", "").strip() - description = operation.get("description", "").strip() # Extract code sample code_sample = "" @@ -120,16 +119,14 @@ def format_operation(operation_id: str, operation: dict[str, Any]) -> str: lines.append(summary) lines.append("") - if description and description != summary: - lines.append(description) - lines.append("") - if code_sample: lines.append(code_sample) lines.append("") lines.append(f"Docs: {docs_link}") lines.append("") + lines.append("---") + lines.append("") return "\n".join(lines) @@ -185,52 +182,54 @@ def get_ordered_operations(spec: dict[str, Any]) -> list[tuple[str, str, str, di operation = path_obj[method] op_id = extract_operation_id(path, method, operation) - # Try to match with our ordered list + # Try to match with our ordered list using multiple strategies matched_name = None - for ordered_name in operation_order: - # Convert ordered name to possible operation IDs - # e.g., "predictions.create" might be "predictionsCreate" or "predictions_create" - variants = [ - ordered_name, - ordered_name.replace(".", "_"), - ordered_name.replace(".", ""), - "".join(word.capitalize() if i > 0 else word for i, word in enumerate(ordered_name.split("."))), - ] - - if op_id in variants or any(v.lower() == op_id.lower() for v in variants): - matched_name = ordered_name - break - - # Also check if the operation path matches - path_parts = path.strip("/").split("/") - ordered_parts = ordered_name.split(".") - - # Match by path structure - if len(ordered_parts) >= 2: - resource = ordered_parts[0] - action = ordered_parts[-1] - - # Check if path contains the resource name - if resource in path and action.lower() == method: + + # Strategy 1: Direct operationId match + if op_id in operation_order: + matched_name = op_id + + # Strategy 2: Case-insensitive exact match + if not matched_name: + for ordered_name in operation_order: + if op_id.lower() == ordered_name.lower(): matched_name = ordered_name break - elif resource in path and action in ["create"] and method == "post": + + # Strategy 3: Convert ordered name to possible operation IDs + if not matched_name: + for ordered_name in operation_order: + # e.g., "predictions.create" might be "predictionsCreate" or "predictions_create" + variants = [ + ordered_name.replace(".", "_"), + ordered_name.replace(".", ""), + "".join(word.capitalize() if i > 0 else word for i, word in enumerate(ordered_name.split("."))), + ] + + if op_id in variants or any(v.lower() == op_id.lower() for v in variants): matched_name = ordered_name break - elif resource in path and action in ["list", "get"] and method == "get": - # Differentiate between list and get - if "{" in path and action == "get": - matched_name = ordered_name - break - elif "{" not in path and action == "list": + + # Strategy 4: Match by path structure and method + if not matched_name: + for ordered_name in operation_order: + ordered_parts = ordered_name.split(".") + if len(ordered_parts) >= 2: + resource = ordered_parts[0] + action = ordered_parts[-1] + + # Check various path patterns + path_lower = path.lower() + if (resource in path_lower and + ((action == "create" and method == "post") or + (action == "get" and method == "get" and "{" in path) or + (action == "list" and method == "get" and "{" not in path) or + (action == "update" and method in ["put", "patch"]) or + (action == "delete" and method == "delete") or + (action == "cancel" and method == "post" and "cancel" in path) or + (action == "search" and method == "get" and "search" in path))): matched_name = ordered_name break - elif resource in path and action in ["update"] and method in ["put", "patch"]: - matched_name = ordered_name - break - elif resource in path and action in ["delete"] and method == "delete": - matched_name = ordered_name - break key = matched_name or op_id operations[key] = (op_id, path, method, operation) @@ -257,6 +256,16 @@ def generate_api_docs(spec: dict[str, Any]) -> str: lines = [] operations = get_ordered_operations(spec) + # Generate sorted list of operations at the top + lines.append("Available operations:") + lines.append("") + for op_id, _path, _method, _operation in operations: + # Create anchor link from operation_id + anchor = op_id.lower().replace('.', '').replace('_', '') + lines.append(f"- [`{op_id}`](#{anchor})") + lines.append("") + + # Generate detailed documentation for each operation for op_id, _path, _method, operation in operations: lines.append(format_operation(op_id, operation))