replicate/replicate-javascript

replicate/replicate-javascript

Description: Node.js client for Replicate

Language: TypeScript

License: Apache-2.0

Stars: 596

Forks: 245

Open issues: 16

Created: 2022-11-18T19:28:10Z

Pushed: 2025-11-17T22:50:08Z

Default branch: main

Fork: no

Archived: no

README:

Replicate Node.js client

A Node.js client for Replicate. It lets you run models from your Node.js code, and everything else you can do with Replicate's HTTP API.

> [!IMPORTANT] > This library can't interact with Replicate's API directly from a browser. > For more information about how to build a web application > check out our "Build a website with Next.js" guide.

Supported platforms

• Node.js >= 18
• Bun >= 1.0
• Deno >= 1.28

You can also use this client library on most serverless platforms, including Cloudflare Workers, Vercel functions, and AWS Lambda.

Installation

Install it from npm:

npm install replicate

Usage

Import or require the package:

// CommonJS (default or using .cjs extension)
const Replicate = require("replicate");

// ESM (where `"module": true` in package.json or using .mjs extension)
import Replicate from "replicate";

Instantiate the client:

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

Run a model and await the result:

const model = "stability-ai/stable-diffusion:27b93a2413e7f36cd83da926f3656280b2931564ff050bf9575f1fdf9bcd7478";
const input = {
prompt: "a 19th century portrait of a raccoon gentleman wearing a suit",
};
const [output] = await replicate.run(model, { input });
// FileOutput('https://replicate.delivery/pbxt/GtQb3Sgve42ZZyVnt8xjquFk9EX5LP0fF68NTIWlgBMUpguQA/out-0.png')

console.log(output.url()); // 'https://replicate.delivery/pbxt/GtQb3Sgve42ZZyVnt8xjquFk9EX5LP0fF68NTIWlgBMUpguQA/out-0.png'
console.log(output.blob()); // Blob

> [!NOTE] > A model that outputs file data returns a FileOutput object by default. This is an implementation > of ReadableStream that returns the file contents. It has a .blob() method for accessing a > Blob representation and a .url() method that will return the underlying data-source. > > We recommend accessing file data directly either as readable stream or via .blob() as the > .url() property may not always return a HTTP URL in future.

You can also run a model in the background:

let prediction = await replicate.predictions.create({
version: "27b93a2413e7f36cd83da926f3656280b2931564ff050bf9575f1fdf9bcd7478",
input: {
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);
console.log(prediction.output);
// ['https://replicate.delivery/pbxt/RoaxeXqhL0xaYyLm6w3bpGwF5RaNBjADukfFnMbhOyeoWBdhA/out-0.png']

To run a model that takes a file input you can pass either a URL to a publicly accessible file on the Internet or a handle to a file on your local device.

const fs = require("node:fs/promises");

// Or when using ESM.
// import fs from "node:fs/promises";

const model = "nightmareai/real-esrgan:42fed1c4974146d4d2414e2be2c5277c7fcf05fcc3a73abf41610695738c1d7b";
const input = {
image: await fs.readFile("path/to/image.png"),
};
const [output] = await replicate.run(model, { input });
// FileOutput('https://replicate.delivery/mgxm/e7b0e122-9daa-410e-8cde-006c7308ff4d/output.png')

> [!NOTE] > File handle inputs are automatically uploaded to Replicate. > See [replicate.files.create](#replicatefilescreate) for more information. > The maximum size for uploaded files is 100MiB. > To run a model with a larger file as an input, > upload the file to your own storage provider > and pass a publicly accessible URL.

TypeScript usage

This library exports TypeScript definitions. You can import them like this:

import Replicate, { type Prediction } from 'replicate';

Here's an example that uses the Prediction type with a custom onProgress callback:

import Replicate, { type Prediction } from 'replicate';

const replicate = new Replicate();
const model = "black-forest-labs/flux-schnell";
const prompt = "a 19th century portrait of a raccoon gentleman wearing a suit";
function onProgress(prediction: Prediction) {
console.log({ prediction });
}

const output = await replicate.run(model, { input: { prompt } }, onProgress)
console.log({ output })

See the full list of exported types in [index.d.ts](./index.d.ts).

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.

See example

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

Create the prediction passing in the webhook URL to webhook and specify which events you want to receive in webhook_events_filter out of "start", "output", ”logs” and "completed":

const Replicate = require("replicate");
const replicate = new Replicate();

const input = {
image: "https://replicate.delivery/pbxt/KWDkejqLfER3jrroDTUsSvBWFaHtapPxfg4xxZIqYmfh3zXm/Screenshot%202024-02-28%20at%2022.14.00.png",
denoising_strength: 0.5,…