OpenRouter SDK (Beta)

The OpenRouter SDK is a TypeScript toolkit designed to help you build AI-powered features and solutions in any JS or TS based runtime. Giving you easy access to over 300 models across providers in an easy and type-safe way.

To learn more about how to use the OpenRouter SDK, check out our API Reference and Documentation.

SDK Installation

The SDK can be installed with either npm, pnpm, bun or yarn package managers.

NPM

npm add @openrouter/sdk

PNPM

pnpm add @openrouter/sdk

Bun

bun add @openrouter/sdk

Yarn

yarn add @openrouter/sdk

Note

This package is published as an ES Module (ESM) only. For applications using CommonJS, use await import("@openrouter/sdk") to import and use this package.

Migrating callModel to @openrouter/agent

Important

callModel and its associated types have moved to the @openrouter/agent package. If you are using callModel, tool definitions, or related types from @openrouter/sdk, you should migrate to @openrouter/agent.

To assist with the migration, run:

npx skills add OpenRouterTeam/skills --skill openrouter-agent-migration

Requirements

For supported JavaScript runtimes, please consult RUNTIMES.md.

SDK Usage

import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter();

const result = await openRouter.chat.send({
  messages: [
    {
      role: "user",
      content: "Hello, how are you?",
    },
  ],
  model: "openai/gpt-5",
  provider: {
    zdr: true,
    sort: "price",
  },
  stream: true
});

for await (const chunk of result) {
  console.log(chunk.choices[0].delta.content)
}

Pagination

Some of the endpoints in this SDK support pagination. To use pagination, you make your SDK calls as usual, but the returned response object will also be an async iterable that can be consumed using the for await...of syntax.

Here's an example of one such pagination call:

import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.byok.list();

  for await (const page of result) {
    console.log(page);
  }
}

run();

File uploads

Certain SDK methods accept files as part of a multi-part request. It is possible and typically recommended to upload files as a stream rather than reading the entire contents into memory. This avoids excessive memory consumption and potentially crashing with out-of-memory errors when working with very large files. The following example demonstrates how to attach a file stream to a request.

Tip

Depending on your JavaScript runtime, there are convenient utilities that return a handle to a file without reading the entire contents into memory:

• Node.js v20+: Since v20, Node.js comes with a native openAsBlob function in node:fs.
• Bun: The native Bun.file function produces a file handle that can be used for streaming file uploads.
• Browsers: All supported browsers return an instance to a File when reading the value from an <input type="file"> element.
• Node.js v18: A file stream can be created using the fileFrom helper from fetch-blob/from.js.

import { OpenRouter } from "@openrouter/sdk";
import { openAsBlob } from "node:fs";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.files.upload({
    requestBody: {
      file: await openAsBlob("example.file"),
    },
  });

  console.log(result);
}

run();

Debugging

You can setup your SDK to emit debug logs for SDK requests and responses.

You can pass a logger that matches console's interface as an SDK option.

Warning

Beware that debug logging will reveal secrets, like API tokens in headers, in log messages printed to a console or files. It's recommended to use this feature only during local development and not in production.

import { OpenRouter } from "@openrouter/sdk";

const sdk = new OpenRouter({ debugLogger: console });

You can also enable a default debug logger by setting an environment variable OPENROUTER_DEBUG to true.

Development

Running Tests

To run the test suite, you'll need to set up your environment with an OpenRouter API key.

Local Development

1. Copy the example environment file:

   cp .env.example .env

2. Edit .env and add your OpenRouter API key:

   OPENROUTER_API_KEY=your_api_key_here

3. Run the tests:

   npx vitest

Maturity

This SDK is in beta, and there may be breaking changes between versions without a major version update. Therefore, we recommend pinning usage to a specific package version. This way, you can install the same version each time without breaking changes unless you are intentionally looking for the latest version.