Replicate JavaScript client

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,
});

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	Identifier of your app. Defaults to `replicate-javascript/${packageJSON.version}`
`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.

jemgold / replicate-javascript