openapi: 3.1.0
info:
contact:
email: team@replicate.com
description: AI can do extraordinary things, but its still too hard to use. We don't believe AI is inherently hard. We just don't have the right tools and abstractions yet. Were building tools so all software engineers can use AI as if it were normal software. You should be able to import an image generator the same way you import an npm package. You should be able to customize a model as easily as you can fork something on GitHub.
termsOfService: https://replicate.com/terms
title: Replicate Accounts Owner API
version: 1.0.0-a1
servers:
- url: https://api.replicate.com/v1
security:
- bearerAuth: []
tags:
- name: Owner
paths:
/deployments/{deployment_owner}/{deployment_name}:
delete:
description: "Delete a deployment\n\nDeployment deletion has some restrictions:\n\n- You can only delete deployments that have been offline and unused for at least 15 minutes.\n\nExample cURL request:\n\n```command\ncurl -s -X DELETE \\\n -H \"Authorization: Bearer $REPLICATE_API_TOKEN\" \\\n https://api.replicate.com/v1/deployments/acme/my-app-image-generator\n```\n\nThe response will be an empty 204, indicating the deployment has been deleted.\n"
operationId: deployments.delete
parameters:
- description: 'The name of the user or organization that owns the deployment.
'
in: path
name: deployment_owner
required: true
schema:
type: string
- description: 'The name of the deployment.
'
in: path
name: deployment_name
required: true
schema:
type: string
responses:
'204':
description: Success
summary: Delete a Deployment
tags:
- Owner
get:
description: "Get information about a deployment by name including the current release.\n\nExample cURL request:\n\n```console\ncurl -s \\\n -H \"Authorization: Bearer $REPLICATE_API_TOKEN\" \\\n https://api.replicate.com/v1/deployments/replicate/my-app-image-generator\n```\n\nThe response will be a JSON object describing the deployment:\n\n```json\n{\n \"owner\": \"acme\",\n \"name\": \"my-app-image-generator\",\n \"current_release\": {\n \"number\": 1,\n \"model\": \"stability-ai/sdxl\",\n \"version\": \"da77bc59ee60423279fd632efb4795ab731d9e3ca9705ef3341091fb989b7eaf\",\n \"created_at\": \"2024-02-15T16:32:57.018467Z\",\n \"created_by\": {\n \"type\": \"organization\",\n \"username\": \"acme\",\n \"name\": \"Acme Corp, Inc.\",\n \"github_url\": \"https://github.com/acme\",\n },\n \"configuration\": {\n \"hardware\": \"gpu-t4\",\n \"min_instances\": 1,\n \"max_instances\": 5\n }\n }\n}\n```\n"
operationId: deployments.get
parameters:
- description: 'The name of the user or organization that owns the deployment.
'
in: path
name: deployment_owner
required: true
schema:
type: string
- description: 'The name of the deployment.
'
in: path
name: deployment_name
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties:
current_release:
properties:
configuration:
properties:
hardware:
description: The SKU for the hardware used to run the model.
type: string
max_instances:
description: The maximum number of instances for scaling.
type: integer
min_instances:
description: The minimum number of instances for scaling.
type: integer
type: object
created_at:
description: The time the release was created.
format: date-time
type: string
created_by:
properties:
github_url:
description: The GitHub URL of the account that created the release.
format: uri
type: string
name:
description: The name of the account that created the release.
type: string
type:
description: The account type of the creator. Can be a user or an organization.
enum:
- organization
- user
type: string
username:
description: The username of the account that created the release.
type: string
type: object
model:
description: The model identifier string in the format of `{model_owner}/{model_name}`.
type: string
number:
description: The release number.
type: integer
version:
description: The ID of the model version used in the release.
type: string
type: object
name:
description: The name of the deployment.
type: string
owner:
description: The owner of the deployment.
type: string
type: object
description: Success
summary: Get a Deployment
tags:
- Owner
patch:
description: "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).\n\nExample cURL request:\n\n```console\ncurl -s \\\n -X PATCH \\\n -H \"Authorization: Bearer $REPLICATE_API_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"min_instances\": 3, \"max_instances\": 10}' \\\n https://api.replicate.com/v1/deployments/acme/my-app-image-generator\n```\n\nThe response will be a JSON object describing the deployment:\n\n```json\n{\n \"owner\": \"acme\",\n \"name\": \"my-app-image-generator\",\n \"current_release\": {\n \"number\": 2,\n \"model\": \"stability-ai/sdxl\",\n \"version\": \"da77bc59ee60423279fd632efb4795ab731d9e3ca9705ef3341091fb989b7eaf\",\n \"created_at\": \"2024-02-15T16:32:57.018467Z\",\n \"created_by\": {\n \"type\": \"organization\",\n \"username\": \"acme\",\n \"name\": \"Acme Corp, Inc.\",\n \"github_url\": \"https://github.com/acme\",\n },\n \"configuration\": {\n \"hardware\": \"gpu-t4\",\n \"min_instances\": 3,\n \"max_instances\": 10\n }\n }\n}\n```\n\nUpdating any deployment properties will increment the `number` field of the `current_release`.\n"
operationId: deployments.update
parameters:
- description: 'The name of the user or organization that owns the deployment.
'
in: path
name: deployment_owner
required: true
schema:
type: string
- description: 'The name of the deployment.
'
in: path
name: deployment_name
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
hardware:
description: The SKU for the hardware used to run the model. Possible values can be retrieved from the `hardware.list` endpoint.
type: string
max_instances:
description: The maximum number of instances for scaling.
maximum: 20
minimum: 0
type: integer
min_instances:
description: The minimum number of instances for scaling.
maximum: 5
minimum: 0
type: integer
version:
description: The ID of the model version that you want to deploy
type: string
type: object
responses:
'200':
content:
application/json:
schema:
properties:
current_release:
properties:
configuration:
properties:
hardware:
description: The SKU for the hardware used to run the model.
type: string
max_instances:
description: The maximum number of instances for scaling.
type: integer
min_instances:
description: The minimum number of instances for scaling.
type: integer
type: object
created_at:
description: The time the release was created.
format: date-time
type: string
created_by:
properties:
github_url:
description: The GitHub URL of the account that created the release.
format: uri
type: string
name:
description: The name of the account that created the release.
type: string
type:
description: The account type of the creator. Can be a user or an organization.
enum:
- organization
- user
type: string
username:
description: The username of the account that created the release.
type: string
type: object
model:
description: The model identifier string in the format of `{model_owner}/{model_name}`.
type: string
number:
description: The release number.
type: integer
version:
description: The ID of the model version used in the release.
type: string
type: object
name:
description: The name of the deployment.
type: string
owner:
description: The owner of the deployment.
type: string
type: object
description: Success
summary: Update a Deployment
tags:
- Owner
/deployments/{deployment_owner}/{deployment_name}/predictions:
post:
description: "Create a prediction for the deployment and inputs you provide.\n\nExample cURL request:\n\n```console\ncurl -s -X POST -H 'Prefer: wait' \\\n -d '{\"input\": {\"prompt\": \"A photo of a bear riding a bicycle over the moon\"}}' \\\n -H \"Authorization: Bearer $REPLICATE_API_TOKEN\" \\\n -H 'Content-Type: application/json' \\\n https://api.replicate.com/v1/deployments/acme/my-app-image-generator/predictions\n```\n\nThe request will wait up to 60 seconds for the model to run. If this time is exceeded the prediction will be returned in a `\"starting\"` state and need to be retrieved using the `predictions.get` endpiont.\n\nFor a complete overview of the `deployments.predictions.create` API check out our documentation on [creating a prediction](https://replicate.com/docs/topics/predictions/create-a-prediction) which covers a variety of use cases.\n"
operationId: deployments.predictions.create
parameters:
- description: 'The name of the user or organization that owns the deployment.
'
in: path
name: deployment_owner
required: true
schema:
type: string
- description: 'The name of the deployment.
'
in: path
name: deployment_name
required: true
schema:
type: string
- $ref: '#/components/parameters/parameters_prefer_header'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/schemas_prediction_request'
responses:
'201':
description: 'Prediction has been created. If the `Prefer: wait` header is provided it will contain the final output.'
'202':
description: Prediction has been created but does not yet have all outputs
summary: Create a Prediction Using a Deployment
tags:
- Owner
/models/{model_owner}/{model_name}:
delete:
description: "Delete a model\n\nModel deletion has some restrictions:\n\n- You can only delete models you own.\n- You can only delete private models.\n- You can only delete models that have no versions associated with them. Currently you'll need to [delete the model's versions](#models.versions.delete) before you can delete the model itself.\n\nExample cURL request:\n\n```command\ncurl -s -X DELETE \\\n -H \"Authorization: Bearer $REPLICATE_API_TOKEN\" \\\n https://api.replicate.com/v1/models/replicate/hello-world\n```\n\nThe response will be an empty 204, indicating the model has been deleted.\n"
operationId: models.delete
parameters:
- description: 'The name of the user or organization that owns the model.
'
in: path
name: model_owner
required: true
schema:
type: string
- description: 'The name of the model.
'
in: path
name: model_name
required: true
schema:
type: string
responses:
'204':
description: Success
summary: Delete a Model
tags:
- Owner
get:
description: "Example cURL request:\n\n```console\ncurl -s \\\n -H \"Authorization: Bearer $REPLICATE_API_TOKEN\" \\\n https://api.replicate.com/v1/models/replicate/hello-world\n```\n\nThe response will be a model object in the following format:\n\n```json\n{\n \"url\": \"https://replicate.com/replicate/hello-world\",\n \"owner\": \"replicate\",\n \"name\": \"hello-world\",\n \"description\": \"A tiny model that says hello\",\n \"visibility\": \"public\",\n \"github_url\": \"https://github.com/replicate/cog-examples\",\n \"paper_url\": null,\n \"license_url\": null,\n \"run_count\": 5681081,\n \"cover_image_url\": \"...\",\n \"default_example\": {...},\n \"latest_version\": {...},\n}\n```\n\nThe `cover_image_url` string is an HTTPS URL for an image file. This can be:\n\n- An image uploaded by the model author.\n- The output file of the example prediction, if the model author has not set a cover image.\n- The input file of the example prediction, if the model author has not set a cover image and the example prediction has no output file.\n- A generic fallback image.\n\nThe `default_example` object is a [prediction](#predictions.get) created with this model.\n\nThe `latest_version` object is the model's most recently pushed [version](#models.versions.get).\n"
operationId: models.get
parameters:
- description: 'The name of the user or organization that owns the model.
'
in: path
name: model_owner
required: true
schema:
type: string
- description: 'The name of the model.
'
in: path
name: model_name
required: true
schema:
type: string
responses:
'200':
description: Success
summary: Get a Model
tags:
- Owner
/models/{model_owner}/{model_name}/predictions:
post:
description: "Create a prediction for the deployment and inputs you provide.\n\nExample cURL request:\n\n```console\ncurl -s -X POST -H 'Prefer: wait' \\\n -d '{\"input\": {\"prompt\": \"Write a short poem about the weather.\"}}' \\\n -H \"Authorization: Bearer $REPLICATE_API_TOKEN\" \\\n -H 'Content-Type: application/json' \\\n https://api.replicate.com/v1/models/meta/meta-llama-3-70b-instruct/predictions\n```\n\nThe request will wait up to 60 seconds for the model to run. If this time is exceeded the prediction will be returned in a `\"starting\"` state and need to be retrieved using the `predictions.get` endpiont.\n\nFor a complete overview of the `deployments.predictions.create` API check out our documentation on [creating a prediction](https://replicate.com/docs/topics/predictions/create-a-prediction) which covers a variety of use cases.\n"
operationId: models.predictions.create
parameters:
- description: 'The name of the user or organization that owns the model.
'
in: path
name: model_owner
required: true
schema:
type: string
- description: 'The name of the model.
'
in: path
name: model_name
required: true
schema:
type: string
- $ref: '#/components/parameters/parameters_prefer_header'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/schemas_prediction_request'
responses:
'201':
description: 'Prediction has been created. If the `Prefer: wait` header is provided it will contain the final output.'
'202':
description: Prediction has been created but does not yet have all outputs
summary: Create a Prediction Using an Official Model
tags:
- Owner
/models/{model_owner}/{model_name}/versions:
get:
description: "Example cURL request:\n\n```console\ncurl -s \\\n -H \"Authorization: Bearer $REPLICATE_API_TOKEN\" \\\n https://api.replicate.com/v1/models/replicate/hello-world/versions\n```\n\nThe response will be a JSON array of model version objects, sorted with the most recent version first:\n\n```json\n{\n \"next\": null,\n \"previous\": null,\n \"results\": [\n {\n \"id\": \"5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa\",\n \"created_at\": \"2022-04-26T19:29:04.418669Z\",\n \"cog_version\": \"0.3.0\",\n \"openapi_schema\": {...}\n }\n ]\n}\n```\n"
operationId: models.versions.list
parameters:
- description: 'The name of the user or organization that owns the model.
'
in: path
name: model_owner
required: true
schema:
type: string
- description: 'The name of the model.
'
in: path
name: model_name
required: true
schema:
type: string
responses:
'200':
description: Success
summary: List Model Versions
tags:
- Owner
/models/{model_owner}/{model_name}/versions/{version_id}:
delete:
description: "Delete a model version and all associated predictions, including all output files.\n\nModel version deletion has some restrictions:\n\n- You can only delete versions from models you own.\n- You can only delete versions from private models.\n- You cannot delete a version if someone other than you has run predictions with it.\n- You cannot delete a version if it is being used as the base model for a fine tune/training.\n- You cannot delete a version if it has an associated deployment.\n- You cannot delete a version if another model version is overridden to use it.\n\nExample cURL request:\n\n```command\ncurl -s -X DELETE \\\n -H \"Authorization: Bearer $REPLICATE_API_TOKEN\" \\\n https://api.replicate.com/v1/models/replicate/hello-world/versions/5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa\n```\n\nThe response will be an empty 202, indicating the deletion request has been accepted. It might take a few minutes to be processed.\n"
operationId: models.versions.delete
parameters:
- description: 'The name of the user or organization that owns the model.
'
in: path
name: model_owner
required: true
schema:
type: string
- description: 'The name of the model.
'
in: path
name: model_name
required: true
schema:
type: string
- description: 'The ID of the version.
'
in: path
name: version_id
required: true
schema:
type: string
responses:
'202':
description: Deletion request has been accepted. It might take a few minutes to be processed.
summary: Delete a Model Version
tags:
- Owner
get:
description: "Example cURL request:\n\n```console\ncurl -s \\\n -H \"Authorization: Bearer $REPLICATE_API_TOKEN\" \\\n https://api.replicate.com/v1/models/replicate/hello-world/versions/5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa\n```\n\nThe response will be the version object:\n\n```json\n{\n \"id\": \"5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa\",\n \"created_at\": \"2022-04-26T19:29:04.418669Z\",\n \"cog_version\": \"0.3.0\",\n \"openapi_schema\": {...}\n}\n```\n\nEvery model describes its inputs and outputs with [OpenAPI Schema Objects](https://spec.openapis.org/oas/latest.html#schemaObject) in the `openapi_schema` property.\n\nThe `openapi_schema.components.schemas.Input` property for the [replicate/hello-world](https://replicate.com/replicate/hello-world) model looks like this:\n\n```json\n{\n \"type\": \"object\",\n \"title\": \"Input\",\n \"required\": [\n \"text\"\n ],\n \"properties\": {\n \"text\": {\n \"x-order\": 0,\n \"type\": \"string\",\n \"title\": \"Text\",\n \"description\": \"Text to prefix with 'hello '\"\n }\n }\n}\n```\n\nThe `openapi_schema.components.schemas.Output` property for the [replicate/hello-world](https://replicate.com/replicate/hello-world) model looks like this:\n\n```json\n{\n \"type\": \"string\",\n \"title\": \"Output\"\n}\n```\n\nFor 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)\n"
operationId: models.versions.get
parameters:
- description: 'The name of the user or organization that owns the model.
'
in: path
name: model_owner
required: true
schema:
type: string
- description: 'The name of the model.
'
in: path
name: model_name
required: true
schema:
type: string
- description: 'The ID of the version.
'
in: path
name: version_id
required: true
schema:
type: string
responses:
'200':
description: Success
summary: Get a Model Version
tags:
- Owner
/models/{model_owner}/{model_name}/versions/{version_id}/trainings:
post:
description: "Start a new training of the model version you specify.\n\nExample request body:\n\n```json\n{\n \"destination\": \"{new_owner}/{new_name}\",\n \"input\": {\n \"train_data\": \"https://example.com/my-input-images.zip\",\n },\n \"webhook\": \"https://example.com/my-webhook\",\n}\n```\n\nExample cURL request:\n\n```console\ncurl -s -X POST \\\n -d '{\"destination\": \"{new_owner}/{new_name}\", \"input\": {\"input_images\": \"https://example.com/my-input-images.zip\"}}' \\\n -H \"Authorization: Bearer $REPLICATE_API_TOKEN\" \\\n -H 'Content-Type: application/json' \\\n https://api.replicate.com/v1/models/stability-ai/sdxl/versions/da77bc59ee60423279fd632efb4795ab731d9e3ca9705ef3341091fb989b7eaf/trainings\n```\n\nThe response will be the training object:\n\n```json\n{\n \"id\": \"zz4ibbonubfz7carwiefibzgga\",\n \"model\": \"stability-ai/sdxl\",\n \"version\": \"da77bc59ee60423279fd632efb4795ab731d9e3ca9705ef3341091fb989b7eaf\",\n \"input\": {\n \"input_images\": \"https://example.com/my-input-images.zip\"\n },\n \"logs\": \"\",\n \"error\": null,\n \"status\": \"starting\",\n \"created_at\": \"2023-09-08T16:32:56.990893084Z\",\n \"urls\": {\n \"cancel\": \"https://api.replicate.com/v1/predictions/zz4ibbonubfz7carwiefibzgga/cancel\",\n \"get\": \"https://api.replicate.com/v1/predictions/zz4ibbonubfz7carwiefibzgga\"\n }\n}\n```\n\nAs 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.\n\nWhen a training completes, it creates a new [version](https://replicate.com/docs/how-does-replicate-work#terminology) of the model at the specified destination.\n\nTo find some models to train on, check out the [trainable language models collection](https://replicate.com/collections/trainable-language-models).\n"
operationId: trainings.create
parameters:
- description: 'The name of the user or organization that owns the model.
'
in: path
name: model_owner
required: true
schema:
type: string
- description: 'The name of the model.
'
in: path
name: model_name
required: true
schema:
type: string
- description: 'The ID of the version.
'
in: path
name: version_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/schemas_training_request'
responses:
'201':
description: Success
summary: Create a Training
tags:
- Owner
components:
schemas:
schemas_prediction_request:
additionalProperties: false
properties:
input:
description: 'The model''s input as a JSON object. The input schema depends on what model you are running. To see the available inputs, click the "API" tab on the model you are running or [get the model version](#models.versions.get) and look at its `openapi_schema` property. For example, [stability-ai/sdxl](https://replicate.com/stability-ai/sdxl) takes `prompt` as an input.
Files should be passed as HTTP URLs or data URLs.
Use an HTTP URL when:
- you have a large file > 256kb
- you want to be able to use the file multiple times
- you want your prediction metadata to be associable with your input files
Use a data URL when:
- you have a small file <= 256kb
- you don''t want to upload and host the file somewhere
- you don''t need to use the file again (Replicate will not store it)
'
type: object
stream:
description: '**This field is deprecated.**
Request a URL to receive streaming output using [server-sent events (SSE)](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events).
This field is no longer needed as the returned prediction will always have a `stream` entry in its `url` property if the model supports streaming.
'
type: boolean
webhook:
description: 'An HTTPS URL for receiving a webhook when the prediction has new output. The webhook will be a POST request where the request body is the same as the response body of the [get prediction](#predictions.get) operation. If there are network problems, we will retry the webhook a few times, so make sure it can be safely called more than once. Replicate will not follow redirects when sending webhook requests to your service, so be sure to specify a URL that will resolve without redirecting.
'
type: string
webhook_events_filter:
description: "By default, we will send requests to your webhook URL whenever there are new outputs or the prediction has finished. You can change which events trigger webhook requests by specifying `webhook_events_filter` in the prediction request:\n\n- `start`: immediately on prediction start\n- `output`: each time a prediction generates an output (note that predictions can generate multiple outputs)\n- `logs`: each time log output is generated by a prediction\n- `completed`: when the prediction reaches a terminal state (succeeded/canceled/failed)\n\nFor example, if you only wanted requests to be sent at the start and end of the prediction, you would provide:\n\n```json\n{\n \"input\": {\n \"text\": \"Alice\"\n },\n \"webhook\": \"https://example.com/my-webhook\",\n \"webhook_events_filter\": [\"start\", \"completed\"]\n}\n```\n\nRequests for event types `output` and `logs` will be sent at most once every 500ms. If you request `start` and `completed` webhooks, then they'll always be sent regardless of throttling.\n"
items:
enum:
- start
- output
- logs
- completed
type: string
type: array
required:
- input
type: object
schemas_training_request:
properties:
destination:
description: 'A string representing the desired model to push to in the format `{destination_model_owner}/{destination_model_name}`. This should be an existing model owned by the user or organization making the API request. If the destination is invalid, the server will return an appropriate 4XX response.
'
type: string
input:
description: 'An object containing inputs to the Cog model''s `train()` function.
'
type: object
webhook:
description: An HTTPS URL for receiving a webhook when the training completes. The webhook will be a POST request where the request body is the same as the response body of the [get training](#trainings.get) operation. If there are network problems, we will retry the webhook a few times, so make sure it can be safely called more than once. Replicate will not follow redirects when sending webhook requests to your service, so be sure to specify a URL that will resolve without redirecting.
type: string
webhook_events_filter:
description: "By default, we will send requests to your webhook URL whenever there are new outputs or the training has finished. You can change which events trigger webhook requests by specifying `webhook_events_filter` in the training request:\n\n- `start`: immediately on training start\n- `output`: each time a training generates an output (note that trainings can generate multiple outputs)\n- `logs`: each time log output is generated by a training\n- `completed`: when the training reaches a terminal state (succeeded/canceled/failed)\n\nFor example, if you only wanted requests to be sent at the start and end of the training, you would provide:\n\n```json\n{\n \"destination\": \"my-organization/my-model\",\n \"input\": {\n \"text\": \"Alice\"\n },\n \"webhook\": \"https://example.com/my-webhook\",\n \"webhook_events_filter\": [\"start\", \"completed\"]\n}\n```\n\nRequests for event types `output` and `logs` will be sent at most once every 500ms. If you request `start` and `completed` webhooks, then they'll always be sent regardless of throttling.\n"
items:
enum:
- start
- output
- logs
- completed
type: string
type: array
required:
- destination
- input
type: object
parameters:
parameters_prefer_header:
description: 'Leave the request open and wait for the model to finish generating output. Set to `wait=n` where n is a number of seconds between 1 and 60.
See https://replicate.com/docs/topics/predictions/create-a-prediction#sync-mode for
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/replicate/refs/heads/main/openapi/replicate-owner-api-openapi.yml