Replicate JavaScript client

SDK for Replicate’s REST API.

Installation

This is not on npm yet, but you can install it from GitHub:

npm install replicate/replicate-javascript

Usage

Create the client:

import Replicate from "replicate";

const replicate = new Replicate({
  // get your token from https://replicate.com/account
  auth: process.env.REPLICATE_API_TOKEN,
  userAgent: "my-app/1.2.3",
});

Run a model and await the result:

const model = "owner/model:version-id";
const input = { text: "Hello, world!" };
const output = await replicate.run(model, { input });

You can also run a model without awaiting the result:

let prediction = await replicate.predictions.create({
  version: "<MODEL VERSION>",
  input: {
    // your model inputs need to be set here
    prompt: "painting of a cat by andy warhol",
  },
});

Then fetch the prediction result later:

prediction = await replicate.predictions.get(prediction.id);

Or wait for the prediction to finish:

prediction = await replicate.wait(prediction);

Features

• async API
• Type annotations
• Tests
• Pagination

API

Constructor

const replicate = new Replicate(options);

name	type	description
options.auth	string	Required. API access token
options.userAgent	string	Required. Identifier of your app
options.baseUrl	string	Defaults to https://api.replicate.com/v1

replicate.models.get

const response = await replicate.models.get(model_owner, model_name);

name	type	description
model_owner	string	Required. The name of the user or organization that owns the model.
model_name	string	Required. The name of the model.

{
  "url": "https://replicate.com/replicate/hello-world",
  "owner": "replicate",
  "name": "hello-world",
  "description": "A tiny model that says hello",
  "visibility": "public",
  "github_url": "https://github.com/replicate/cog-examples",
  "paper_url": null,
  "license_url": null,
  "latest_version": {
    /* ... */
  }
}

replicate.models.versions.list

const response = await replicate.models.versions.list(model_owner, model_name);

name	type	description
model_owner	string	Required. The name of the user or organization that owns the model.
model_name	string	Required. The name of the model.

{
  "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": {
        /* ... */
      }
    }
  ]
}

replicate.models.versions.get

const response = await replicate.models.versions.get(
  model_owner,
  model_name,
  version_id
);

name	type	description
model_owner	string	Required. The name of the user or organization that owns the model.
model_name	string	Required. The name of the model.
version_id	string	Required. The model version

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

replicate.collections.get

const response = await replicate.collections.get(collection_slug);

name	type	description
collection_slug	string	Required. The slug of the collection. See http://replicate.com/collections

replicate.predictions.create

const response = await replicate.predictions.create(options);

name	type	description
options.version	string	Required. The model version
options.input	object	Required. An object with the models inputs
options.webhook_completed	string	A URL which will receive a POST request upon completion of the prediction

{
  "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",
  "started_at": null,
  "completed_at": null,
  "status": "succeeded",
  "input": {
    "text": "Alice"
  },
  "output": null,
  "error": null,
  "logs": null,
  "metrics": {}
}

replicate.predictions.get

const response = await replicate.predictions.get(prediction_id);

name	type	description
prediction_id	number	Required. The prediction id

{
  "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",
  "started_at": null,
  "completed_at": null,
  "status": "starting",
  "input": {
    "text": "Alice"
  },
  "output": null,
  "error": null,
  "logs": null,
  "metrics": {}
}

replicate.predictions.list

const response = await replicate.predictions.list();

replicate.predictions.list() takes no arguments.

{
  "previous": null,
  "next": "https://api.replicate.com/v1/predictions?cursor=cD0yMDIyLTAxLTIxKzIzJTNBMTglM0EyNC41MzAzNTclMkIwMCUzQTAw",
  "results": [
    {
      "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",
      "started_at": "2022-04-26T20:00:84.583803Z",
      "completed_at": "2022-04-26T20:02:27.648305Z",
      "source": "web",
      "status": "succeeded"
    }
    /* ... */
  ]
}

replicate.paginate

Pass another method as an argument to iterate over results that are spread across multiple pages.

This method is implemented as an async generator function, which you can use in a for loop or iterate over manually.

// iterate over paginated results in a for loop
for await (const page of replicate.paginate(replicate.predictions.list)) {
  /* do something with page of results */
}

// iterate over paginated results one at a time
let paginator = replicate.paginate(replicate.predictions.list);
const page1 = await paginator.next();
const page2 = await paginator.next();
// etc.

replicate.request

const response = await replicate.request(route, parameters);

name	type	description
options.route	string	Required. REST API endpoint path.
options.parameters	object	URL, query, and request body parameters for the given route.

The replicate.request() method is used by the other methods to interact with the Replicate API. You can call this method directly to make other requests to the API.

TypeScript

The Replicate constructor and all replicate.* methods are fully typed.