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 more information.' in: header name: Prefer schema: example: wait=5 pattern: ^wait(=([1-9]|[1-9][0-9]|60))?$ type: string securitySchemes: bearerAuth: bearerFormat: 'All API requests must include a valid API token in the `Authorization` request header. The token must be prefixed by "Bearer", followed by a space and the token value. Example: `Authorization: Bearer r8_Hw***********************************` Find your tokens at https://replicate.com/account/api-tokens ' scheme: bearer type: http externalDocs: description: Replicate HTTP API url: https://replicate.com/docs/reference/http