Replicate Reproducible machine learning

Back to API documentation

Contents

• Authentication
• Create a prediction
• Get a prediction
• Get a list of predictions
• Cancel a prediction
• Get model versions

Authentication

All API requests must be authenticated with a token. Include this header with all requests:

Authorization: Token 

Create a prediction

POST https://api.replicate.com/v1/predictions

The request body takes these parameters:

• version: The ID of the model version you want to run. You can get your model's versions using the API, or find them on the website by clicking the "Versions" tab on the Replicate model page, e.g. replicate.com/replicate/hello-world/versions, then copying the full SHA256 hash from the URL. The version id is the same as the Docker image ID that's created when you build your model.
• input: The model's input as a JSON object. Files should be passed as data URLs or HTTP URLs.

For example:

{
  "version": "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa",
  "input": {
    "text": "Alice"
  }
}

Example curl request:

$ curl -s -X POST \
  -d '{"version": "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa", "input": {"text": "Alice"}}' \
  -H "Authorization: Token $REPLICATE_API_TOKEN" \
  -H 'Content-Type: application/json' \
  https://api.replicate.com/v1/predictions

The response is a JSON object in the following format:

{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa",
  "urls": {
    "get": "https://api.replicate.com/v1/predictions/ufawqhfynnddngldkgtslldrkq",
    "cancel": "https://api.replicate.com/v1/predictions/ufawqhfynnddngldkgtslldrkq/cancel"
  },
  "created_at": "2022-04-26T22:13:06.224088Z",
  "completed_at": "2022-04-26T22:13:06.580379Z",
  "status": "starting",
  "input": {
    "text": "Alice"
  },
  "output": null,
  "error": null,
  "logs": null
}

Get a prediction

GET https://api.replicate.com/v1/predictions/{prediction_id}

Returns same response as POST. status will be one of:

• starting: the prediction is starting up. If this status lasts longer than a few seconds 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 the user.

In the case of success, output will be an object containing the output of the model. Any files will be represented as URLs. You will need to pass the `Authorization` header to request them.

In the case of failure, error will contain the error encountered during the prediction.

Get a list of predictions

GET https://api.replicate.com/v1/predictions

Get a paginated list of predictions you've created with your account. This includes predictions created from the API and the Replicate website. Returns 100 records per page.

Example curl request:

$ curl -s \
  -H "Authorization: Token $REPLICATE_API_TOKEN" \
  -H 'Content-Type: application/json' \
  https://api.replicate.com/v1/predictions

The response is a JSON object in the following format:

{
  "previous": null, 
  "next": "https://api.replicate.com/v1/predictions?cursor=cD0yMDIyLTAxLTIxKzIzJTNBMTglM0EyNC41MzAzNTclMkIwMCUzQTAw",
  "results": [{}, {}, {}]
}

The results key is a list of prediction objects in the following format:

{
  "id": "jpzd7hm5gfcapbfyt4mqytarku",
  "version": "b21cbe271e65c1718f2999b038c18b45e21e4fba961181fbfae9342fc53b9e05",
  "urls": {
    "get": "https://api.replicate.com/v1/predictions/jpzd7hm5gfcapbfyt4mqytarku",
    "cancel": "https://api.replicate.com/v1/predictions/jpzd7hm5gfcapbfyt4mqytarku/cancel"
  },
  "created_at": "2022-04-26T20:00:40.658234Z",
  "completed_at": "2022-04-26T20:02:27.648305Z",
  "source": "web",
  "status": "succeeded"
}

• id: The unique ID of the prediction. Can be used to get a single prediction.
• version: The unique ID of model version used to create the prediction.
• urls: A convenience object that can be used to construct new API requests against the given prediction.
• source: Indicates where the prediction was created. Possible values are `web` or `api`.
• status: Status of the prediction. See get a single prediction for possible values.

Cancel a prediction

POST https://api.replicate.com/v1/predictions/{prediction_id}/cancel

List model's versions

GET https://api.replicate.com/v1/models/{model_owner}/{model_name}/versions

The request path takes these parameters:

• model_owner: The name of the user or organization that owns the model.
• model_name: The name of the model.

Example curl request:

$ curl -s \
  -H "Authorization: Token $REPLICATE_API_TOKEN" \
  -H 'Content-Type: application/json' \
  https://api.replicate.com/v1/models/replicate/hello-world/versions

The response is a JSON array of Version objects, sorted with the most recent version first:

{
  "previous": null,
  "next": null,
  "results": [
    {
      "id": "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa",
      "created_at": "2022-04-26T19:29:04.418669Z",
      "cog_version": "0.3.0",
      "openapi_schema": {...}
    },
    {
      "id": "e2e8c39e0f77177381177ba8c4025421ec2d7e7d3c389a9b3d364f8de560024f",
      "created_at": "2022-03-21T13:01:04.418669Z",
      "cog_version": "0.3.0",
      "openapi_schema": {...}
    }
  ]
}

Get a version

GET https://api.replicate.com/v1/models/{model_owner}/{model_name}/versions/{id}

The request path takes these parameters:

• model_owner: The name of the user or organization that owns the model.
• model_name: The name of the model.
• id: The ID of the version.

Example curl request:

$ curl -s \
  -H "Authorization: Token $REPLICATE_API_TOKEN" \
  -H 'Content-Type: application/json' \
  https://api.replicate.com/v1/models/replicate/hello-world/versions/5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa

The response is the version object:

{
  "id": "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa",
  "created_at": "2022-04-26T19:29:04.418669Z",
  "cog_version": "0.3.0",
  "openapi_schema": {...}
}