Replicate Javascript client

This is a Javacript client for Replicate, written in TypeScript. It lets you run models from your browser, from node, or from a web worker. It is promise-based and designed with async / await in mind.

Getting Started

You can run a model and get its output:

From A Browser

<scripttype="module">// You can specify a specific version, branch, or sha: e.g. "https://cdn.jsdelivr.net/gh/nicholascelestin/replicate-js@0.0.6/replicate.js"importReplicatefrom"https://cdn.jsdelivr.net/gh/nicholascelestin/replicate-js/replicate.js"// NEVER put your token in any publically accessible client-side Javascript// Instead, use a proxy-- see Authentication section belowconstreplicate=newReplicate({proxyUrl: 'http://localhost:3000/api'});consthelloWorldModel=awaitreplicate.models.get('replicate/hello-world');consthelloWorldPrediction=awaithelloWorldModel.predict({text: "test"});console.log(helloWorldPrediction);</script>

From Node

npm install github:nicholascelestin/replicate-js

npm install node-fetch

Works with Node v16 and up.

Depends on node-fetch.

Uses ES6-style module imports. Either set type to module in your package.json file or use a .mjs file extension.

importReplicatefrom'replicate-js'constreplicate=newReplicate({token: 'YOUR_TOKEN'});// If you set the REPLICATE_API_TOKEN environment variable, you do not need to provide a token to the constructor.// const replicate = new Replicate();consthelloWorldModel=awaitreplicate.models.get('replicate/hello-world');consthelloWorldPrediction=awaithelloWorldModel.predict({text: "test"});console.log(helloWorldPrediction);

Usage

You can run a model and feed the output into another model:

constdalleMiniModel=awaitreplicate.models.get('kuprel/min-dalle')constdalleMiniImage=awaitdalleMiniModel.predict({text: "avocado armchair",grid_size: 1});constupscaledImage=awaitswinModel.predict({image: dalleMiniImage.pop()})console.log(upscaledImage);

Run a model and get its output while it's running:

consterlichModel=awaitreplicate.models.get('laion-ai/erlich');consterlichPredictor=erlichModel.predictor({prompt: "test",steps: 50,intermediate_outputs: true,batch_size:2});forawait(letpredictionoferlichPredictor){console.log(prediction);}

By default, model.predict() uses the latest version. If you want to pin to a particular version, you can get a version with its ID:

constmodel=awaitreplicate.models.get("replicate/hello-world")constversionedModel=awaitreplicate.models.get("replicate/hello-world","5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa");

By default,new Replicate() sets a polling interval of 5s. If you want it to poll at a diferent rate, you can set that option:

constreplicate=newReplicate({pollingInterval: 1000});constmodel=awaitreplicate.models.get("replicate/hello-world")// Until finished, checks for new predictions every 1 secondconstprediction=awaitreplicate.predict({text: "test"});

Advanced Usage

If you want to fetch a model's details directly, you can do so and handle the response data from the Replicate HTTP API yourself:

constmodelName='replicate/hello-world'constresponse=awaitreplicate.getModel(modelName);constmostRecentVersion=response.results[0].id;

If you know the specific version of the model you want to call, you can start a prediction directly and handle the response yourself:

constmostRecentVersion='5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa'constresponse=awaitreplicate.startPrediction(modelVersion,{text: "avocado armchair"});constpredictionId=response.id;

If you know the id of a prediction you want to get the status of, you can do so directly and handle the response yourself:

constpredictionId='n5eiqe47djb5bg53f35tsyzls5';constresponse=replicate.getPrediction(predictionId);

By default, this library uses fetch (polyfilled with node-fetch in node < 18), but you can override this behavior and use your own HTTP client by defining your own get and post methods.

These methods are called whenever an HTTP request (get or post) would be made, assuming that you will make the actual request yourself with the provided url and body (for post requests). Methods must be asynchronous and must return the JSON response body.

token is available for use in headers. event is is a string specifying the context under which an HTTP request is made. Possible values are:

• getModel - When fetching model details.
• startPrediction - When starting a new prediction.
• getPrediction - When checking the status of a prediction (ocurrs regularly due to polling)

// Example using axios instead of fetchimportaxiosfrom'axios';consthttpClient={// Method arguments use object destructuring// All arguments are optional, can be in any order, but cannot be renamedget: async({url, token, event})=>{constresponse=awaitaxios.get(url,{headers: {'Authorization': `Token ${token}`}})console.log(`Handling ${event} event`);// Possible values: getModel, getPredictionreturnresponse.data;},post: async({url, body, token, event})=>{constresponse=awaitaxios.post(url,body,{headers: {'Authorization': `Token ${token}`}})console.log(`Handling ${event} event`);// Possible values: startPredictionreturnresponse.data;}}constreplicateAxios=newReplicate({pollingInterval:5000,httpClient: httpClient});constmodel=awaitreplicateAxios.models.get("replicate/hello-world")// getModel eventconstprediction=awaitmodel.predict({text: "test"});// startPrediction, getPrediction events

Installation

For Node

npm install github:nicholascelestin/replicate-js

npm install node-fetch

For A Browser

<scripttype="module">// You can specify a specific version, branch, or sha: e.g. "https://cdn.jsdelivr.net/gh/nicholascelestin/replicate-js@0.0.6/replicate.js"importReplicatefrom"https://cdn.jsdelivr.net/gh/nicholascelestin/replicate-js/replicate.js"</script>

Authentication

For Node

In a Node.js environment, you can set the REPLICATE_API_TOKEN environment variable to your API token. For example, by running this before any Javascript that uses the API: export REPLICATE_API_TOKEN=<your token>.

Alternatively, you can pass your API token directly to the Replicate constructor. This takes precendence over the environment variable.

constreplicate=newReplicate({token: 'YOUR_TOKEN'});

For A Browser

This library will work in a browser, but:

• You should NEVER expose your API token in any publically accessible client-side Javascript.
• You should NEVER use the unmodified proxy in this repo in a public environment, and certainly not a production environment.

If you do so, you run the risk of your API token being stolen or being charged for unauthorized usage.

However, for private development and testing, you can use the lightweight proxy bundled in this repository. A proxy is necessary to avoid CORS issues with the Replicate HTTP API.

export REPLICATE_API_TOKEN=<your token>

node ./cors-proxy.js

<scripttype="module">importReplicatefrom"https://cdn.jsdelivr.net/gh/nicholascelestin/replicate-js/replicate.js"letreplicate=newReplicate({proxyUrl: 'http://localhost:3000/api'});</script>