JavaScript Client

Overview

ModelRunner provides a unified JavaScript/TypeScript SDK to call any supported model with a consistent interface. Use it in Node.js, serverless runtimes, and—via a proxy—in the browser.

For client-side apps, never expose secrets. Use the proxy pattern shown below to safely forward requests.

Installation

npm i @modelrunner/client

yarn add @modelrunner/client

pnpm add @modelrunner/client

Configure credentials

Configure the client with a single key. Environment variables are recommended on the server.

import { modelrunner } from "@modelrunner/client";

modelrunner.config({
  credentials: process.env.MODELRUNNER_KEY,
});

Get your credentials from your ModelRunner account. Keep them server-only.

Call a model

Leverage the queue for long-running tasks. Optionally listen to queue updates.

import { modelrunner } from "@modelrunner/client";

const result = await modelrunner.subscribe("bytedance/sdxl-lightning-4step", {
  input: { "prompt": "two friends cooking together" },
  onQueueUpdate(update) {
    if (update.status === "IN_QUEUE") {
      console.log(`Position in queue: ${update.position}`);
    }
  },
});

console.log(result.data.output);

run and subscribe resolve to a wrapper, not the model record itself — so result.output is always undefined. The model’s own fields live one level down, under result.data.

type Result<T> = {
  data: T;           // the model record — `output`, `logs`, and the rest
  requestId: string; // useful for logs and support
};

Tag requests with metadata

Attach your own flat string map to a request — job ids, environments, batch labels — by passing metadata next to input. It’s supported on run, subscribe, queue.submit, and stream:

const result = await modelrunner.subscribe("bytedance/sdxl-lightning-4step", {
  input: { prompt: "two friends cooking together" },
  metadata: { project: "onboarding-demo", env: "prod" },
});

metadata is sent as a reserved top-level sibling of your input fields — never nested inside input, and never forwarded to the model. It’s stored on the request so you can filter your history by it later; the client itself has no read-back or filtering API, so read tags back through the request lifecycle metadata filter or the MCP list_my_requests tool. The client validates metadata before dispatching, mirroring the API:

Constraint	Value
Max keys	16
Key length	1–64 characters
Values	strings only, ≤512 characters

A violation throws a ValidationError ("Invalid metadata", status 400) before any request is sent — every offending key is reported at once and is addressable with error.getFieldErrors("<key>"). Omitting metadata leaves the body untouched; an explicit {} is valid and is sent as-is.

metadata is reserved at the top level of the request body. If a model’s own input schema declares a field named metadata, sending it this way is rejected by that model’s validation — it’s treated as a request tag, not model input.

Get called back with webhooks

Instead of holding a subscribe open, pass a webhookUrl and ModelRunner POSTs the result to you when the request settles. Nothing is lost if your process restarts mid-request, which is what makes this the right choice for long video and training jobs.

const { request_id } = await modelrunner.queue.submit("bytedance/sdxl-lightning-4step", {
  input: { prompt: "two friends cooking together" },
  webhookUrl: "https://example.com/hooks/modelrunner",
  webhookEvents: ["completed"], // optional — this is the default
});

webhookUrl also works on subscribe, if you want both a callback and in-process updates. See the webhooks guide for the events, the retry schedule, and the full payload shape.

Requires @modelrunner/client 1.2.0 or newer. In earlier versions this option was accepted and silently ignored — no callback was ever sent, and no error was raised. Upgrading also means the URL is now validated, so a bad value that used to be quietly dropped will fail the submit with a 400.

Verify a delivery

Every delivery is signed. Fetch your signing secret once and keep it in your server environment — never in a browser:

const { key } = await modelrunner.webhooks.getSecret();

Then verify each delivery against the raw request body:

import express from "express";
import { modelrunner, WebhookVerificationError } from "@modelrunner/client";

app.post(
  "/hooks/modelrunner",
  // The signature covers the delivered bytes, so the raw body is required.
  // express.json() would parse and discard it.
  express.raw({ type: "application/json" }),
  async (req, res) => {
    let payload;
    try {
      payload = await modelrunner.webhooks.verify({
        secret: process.env.MODELRUNNER_WEBHOOK_SECRET,
        headers: req.headers,
        body: req.body,
      });
    } catch (error) {
      // WebhookVerificationError — a missing header, a stale timestamp, or a
      // signature that doesn't match. Treat every case the same way.
      return res.sendStatus(401);
    }

    res.sendStatus(200); // acknowledge first, then do the work
    await handleResult(payload);
  },
);

verify is async because it uses the Web Crypto API, which is what lets the same code run in Node, serverless runtimes and edge workers. It returns the parsed payload and throws WebhookVerificationError on any failure.

Read billingStatus, not status. A generation that failed at the provider still arrives as status: "COMPLETED", with billingStatus: "failed" and a populated error. Code that treats status alone as success will report every failure as a success.

if (payload.billingStatus === "charged" || payload.billingStatus === "partial") {
  console.log(payload.output);
}

Two more things your endpoint must do, both easy to get wrong:

Return 2xx directly. Redirects are not followed, so a 301 — a missing trailing slash, an http→https upgrade — is recorded as a failed attempt and you see nothing but silence.
Deduplicate on the webhook-id header. Delivery is at-least-once and that id is stable across retries of the same delivery.

Rotate the secret

const { key } = await modelrunner.webhooks.rotateSecret();

The previous secret keeps verifying for 24 hours, and deliveries are signed with both during that window — so you can roll the new value out without dropping anything. Pass both to bridge the gap:

await modelrunner.webhooks.verify({
  secrets: [process.env.WEBHOOK_SECRET_NEXT, process.env.WEBHOOK_SECRET_CURRENT],
  headers: req.headers,
  body: req.body,
});

Rotating twice inside that window ends it early and breaks receivers still holding the original secret, so this call is never retried automatically. Rotate once, deploy, then rotate again if you need to.

Upload files

Upload local files to ModelRunner storage and receive a temporary URL you can pass to model inputs (for example, image or audio URLs).

import { modelrunner } from "@modelrunner/client";
import fs from "node:fs";

const fileBuffer = fs.readFileSync("./image.jpeg");
const url = await modelrunner.storage.upload(new Blob([fileBuffer]));
console.log(url);

You can then pass the returned url to your model input:

const result = await modelrunner.subscribe("swook/inspyrenet", {
  input: { image_path: url,},
});

In Node.js, Blob is available in modern runtimes (Node 18+). If you use an older version, consider upgrading or using a compatible polyfill.The storage service accepts any binary file type (images, audio, video, documents).

Using the client in browsers (via proxy)

To keep secrets safe, use the official server proxy so credentials stay on your server.

// /pages/api/modelrunner/proxy.ts
export { handler as default } from "@modelrunner/server-proxy/nextjs";

// /app/api/modelrunner/proxy/route.ts
import { route } from "@modelrunner/server-proxy/nextjs";
export const { GET, POST, PUT } = route;

import { modelrunner } from "@modelrunner/client";

modelrunner.config({
  proxyUrl: "/api/modelrunner/proxy",
});

const result = await modelrunner.subscribe("bytedance/sdxl-lightning-4step", {
  input: { prompt: "two friends cooking together" },
});

Set MODELRUNNER_KEY in your server environment. The proxy reads this value to authenticate requests. Never expose it in the browser.

Getting started

Wrappers

Platform features

SDKs & recipes

Overview

Installation

Configure credentials

Call a model

Tag requests with metadata

Get called back with webhooks

Verify a delivery

Rotate the secret

Upload files

Using the client in browsers (via proxy)

​Overview

​Installation

​Configure credentials

​Call a model

​Tag requests with metadata

​Get called back with webhooks

​Verify a delivery

​Rotate the secret

​Upload files

​Using the client in browsers (via proxy)

Overview

Installation

Configure credentials

Call a model

Tag requests with metadata

Get called back with webhooks

Verify a delivery

Rotate the secret

Upload files

Using the client in browsers (via proxy)