Authentication

export REPLICATE_API_TOKEN=<paste-your-token-here>

REPLICATE_API_TOKEN=<paste-your-token-here>

curl https://api.replicate.com/v1/account -H "Authorization: Bearer $REPLICATE_API_TOKEN"
# {"type":"user","username":"aron","name":"Aron Carroll","github_url":"https://github.com/aron"}

echo "$REPLICATE_API_TOKEN"
# "r8_xyz"

Setup

NodeJS supports two module formats ESM and CommonJS. Below details the setup for each environment. After setup, the code is identical regardless of module format.

ESM

First you’ll need to ensure you have a NodeJS project:

npm create esm -y

Then install the replicate JavaScript library using npm:

npm install replicate

To use the library, first import and create an instance of it:

import Replicate from "replicate";

const replicate = new Replicate();

This will use the REPLICATE_API_TOKEN API token you’ve setup in your environment for authorization.

CommonJS

First you’ll need to ensure you have a NodeJS project:

npm create -y

Then install the replicate JavaScript library using npm:

npm install replicate

To use the library, first import and create an instance of it:

const Replicate = require("replicate");

const replicate = new Replicate();

This will use the REPLICATE_API_TOKEN API token you’ve setup in your environment for authorization.

Run the model

Use the replicate.run() method to run the model:

const input = {};

const output = await replicate.run("zust-ai/zust-diffusion:f545aeffe96a19a00079a23823af0d9260ca26f8795f54b1f21efe8c217827cd", { input });

import { writeFile } from "node:fs/promises";
for (const [index, item] of Object.entries(output)) {
  await writeFile(`output_${index}`, item);
}
//=> file output written to disk

You can learn about pricing for this model on the model page.

The run() function returns the output directly, which you can then use or pass as the input to another model. If you want to access the full prediction object (not just the output), use the replicate.predictions.create() method instead. This will include the prediction id, status, logs, etc.

Prediction lifecycle

Running predictions and trainings can often take significant time to complete, beyond what is reasonable for an HTTP request/response.

When you run a model on Replicate, the prediction is created with a “starting” state, then instantly returned. This will then move to "processing" and eventual one of “successful”, "failed" or "canceled".

You can explore the prediction lifecycle by using the predictions.get() method to retrieve the latest version of the prediction until completed.

const input = {};
const prediction = await replicate.predictions.create({
  version: "f545aeffe96a19a00079a23823af0d9260ca26f8795f54b1f21efe8c217827cd",
  input
});
// { "id": "xyz...", "status": "starting", ... }

const latest = await replicate.predictions.get(prediction.id);
// { "id": "xyz...", "status": "processing", ... }

let completed;
for (let i = 0; i < 5; i++) {
  const latest = await replicate.predictions.get(prediction.id);
  if (latest.status !== "starting" && latest.status !== "processing") {
    completed = latest;
    break;
  }
  // Wait for 2 seconds and then try again.
  await new Promise((resolve) => setTimeout(resolve, 2000));
}

console.log(completed.output);
//=> file output written to disk

Webhooks

Webhooks provide real-time updates about your prediction. Specify an endpoint when you create a prediction, and Replicate will send HTTP POST requests to that URL when the prediction is created, updated, and finished.

It is possible to provide a URL to the predictions.create() function that will be requested by Replicate when the prediction status changes. This is an alternative to polling.

To receive webhooks you’ll need a web server. The following example uses Hono, a web standards based server, but this pattern applies to most frameworks.

import { serve } from '@hono/node-server';
import { Hono } from 'hono';

const app = new Hono();
app.get('/webhooks/replicate', async (c) => {
  // Get the prediction from the request.
  const prediction = await c.req.json();
	console.log(prediction);
  //=> {"id": "xyz", "status": "successful", ... }

  // Acknowledge the webhook.
  c.status(200);
  c.json({ok: true});
}));

serve(app, (info) => {
  console.log(`Listening on http://localhost:${info.port}`)
  //=> Listening on http://localhost:3000
});

Then create the prediction passing in the webhook URL and specify which events you want to receive out of "start", "output", ”logs” and "completed".

const input = {};

const callbackURL = `https://my.app/webhooks/replicate`;
await replicate.predictions.create({
  version: "f545aeffe96a19a00079a23823af0d9260ca26f8795f54b1f21efe8c217827cd",
  input: input,
  webhook: callbackURL,
  webhook_events_filter: ["completed"],
});

// The server will now handle the event and log:
// => {"id": "xyz", "status": "successful", ... }

Co-ordinating between a prediction request and a webhook response will require some glue. A simple implementation for a single JavaScript server could use an event emitter to manage this.

import { EventEmitter } from "node:events";
const webhooks = new EventEmitter();

// In server code, emit the prediction on the event emitter.
app.get('/webhooks/replicate', async (c) => {
  const prediction = await c.req.json();

  // Emit the prediction on the EventEmitter.
  webhooks.emit(prediction.id, prediction)

  // ...
}));

// In request code
await replicate.predictions.create({
  model: "yorickvp/llava-13b",
  version: "a0fdc44e4f2e1f20f2bb4e27846899953ac8e66c5886c5878fa1d6b73ce009e5",
  input: input,
  webhook: callbackURL,
  webhook_events_filter: ["completed"],
});

// Wait for prediction to be emitted on the EventEmitter.
const prediction = await new Promise(resolve => webhooks.addEventListener(prediction.id, resolve));
// {"id": "xyz", "status": "successful", ... }

From a security perspective it is also possible to verify that the webhook came from Replicate. Check out our documentation on verifying webhooks for more information.

Access a prediction

You may wish to access the prediction object. In these cases it’s easier to use the replicate.predictions.create() or replicate.deployments.predictions.create() functions which will return the prediction object.

Though note that these functions will only return the created prediction, and it will not wait for that prediction to be completed before returning. Use replicate.predictions.get() to fetch the latest prediction.

const input = {};
const prediction = replicate.predictions.create({
  version: "f545aeffe96a19a00079a23823af0d9260ca26f8795f54b1f21efe8c217827cd",
  input
});
// { "id": "xyz123", "status": "starting", ... }

Cancel a prediction

You may need to cancel a prediction. Perhaps the user has navigated away from the browser or canceled your application. To prevent unnecessary work and reduce runtime costs you can use the replicate.predictions.cancel function and pass it a prediction id.

await replicate.predictions.cancel(prediction.id);