openrouter-ai-sdks

openrouter-ai-sdks

A small Node.js client for OpenRouter, the API that gives you one HTTP interface to hundreds of chat models (OpenAI, Anthropic, Google, Meta, and more) instead of a different SDK and a different bill for each one.

Hand-rolling this yourself means writing the same axios boilerplate every project: attach the bearer token, retry on rate limits, parse the Server-Sent-Events stream token by token, and turn a raw HTTP error into something you can actually branch on. This package does that part so your code can just call chat().

Install

npm install openrouter-ai-sdks

Works from both import (ESM) and require() (CommonJS). TypeScript types are included, nothing extra to install.

Quick start

import { OpenRouterAI } from "openrouter-ai-sdks";

// Reads OPENROUTER_API_KEY from the environment if you don't pass apiKey.
// This package never reads a .env file itself — that's your application's job.
const ai = new OpenRouterAI({ apiKey: process.env.OPENROUTER_API_KEY });

const reply = await ai.chat({
    model: "openai/gpt-4-turbo",
    messages: [{ role: "user", content: "Say hello in one sentence." }],
});

console.log(reply);

Usage

Streaming a reply token by token

Pass stream: true and iterate the result. Useful for printing a response as it arrives instead of waiting for the whole thing.

const stream = await ai.chat({
    model: "anthropic/claude-3.5-sonnet",
    messages: [{ role: "user", content: "Write a haiku about the ocean." }],
    stream: true,
});

for await (const token of stream as AsyncIterable<string>) {
    process.stdout.write(token);
}

Listing available models

const models = await ai.listModels();
console.log(models.map((m) => m.id));
// ["openai/gpt-4-turbo", "anthropic/claude-3.5-sonnet", ...]

Handling errors

Every failure is a subclass of OpenRouterError, so you can catch broadly or narrow to what you actually need to handle differently.

import { OpenRouterAI, OpenRouterAPIError, OpenRouterAuthError } from "openrouter-ai-sdks";

try {
    await ai.chat({ messages: [{ role: "user", content: "Hi" }] });
} catch (error) {
    if (error instanceof OpenRouterAuthError) {
        console.error("No API key configured:", error.message);
    } else if (error instanceof OpenRouterAPIError) {
        // error.status is the real HTTP status, error.data is OpenRouter's response body
        console.error(`OpenRouter rejected the request (${error.status}):`, error.data);
    } else {
        throw error;
    }
}

Configuring retries

429 (rate limited) and 5xx (server error) responses are retried automatically with exponential backoff. Tune it per client if the defaults don't fit your workload:

const ai = new OpenRouterAI({
    apiKey: process.env.OPENROUTER_API_KEY,
    maxRetries: 5, // default is 3
    retryDelayMs: 1000, // default is 500, doubles each attempt
});

API

new OpenRouterAI(options)

Option	Type	Default	Description
apiKey	string	process.env.OPENROUTER_API_KEY	Your OpenRouter API key. Throws OpenRouterAuthError if neither is set.
baseUrl	string	https://openrouter.ai/api	Override for self-hosted proxies or testing.
model	string	gpt-4-turbo	Default model when a request doesn't specify one.
maxRetries	number	3	Retry attempts on 429 / 5xx before giving up.
retryDelayMs	number	500	Base backoff delay in ms; doubles on each retry.

ai.chat(request)

request.messages is required: an array of { role: "user" | "assistant" | "system", content: string }.

Returns a Promise<string> normally, or Promise<AsyncIterable<string>> when request.stream is true.

ai.listModels()

Returns Promise<OpenRouterModel[]> — the models OpenRouter currently has available, as reported by GET /v1/models.

Errors

Class	Thrown when
OpenRouterError	Base class. Catch this to handle any failure from this package.
OpenRouterAuthError	No API key was passed in options or found in the environment.
OpenRouterAPIError	OpenRouter responded with an error status. Has .status and .data.
OpenRouterRequestError	The request never reached OpenRouter (network failure, timeout).

Limits

Worth knowing before you rely on this:

• Node.js only. Streaming reads a Node Readable (Buffer chunks); it has not been tested in a browser bundle.
• Retries cover 429 and 5xx only. A network-level failure (timeout, DNS, connection reset) is not retried — it throws OpenRouterRequestError immediately.
• No function/tool calling helpers. You can still send tools in a raw request body yourself; there's just no typed wrapper for it yet.
• Streaming parses OpenRouter's current SSE format (data: {...} lines, data: [DONE] to end). If OpenRouter changes that format, parsing breaks until this package is updated.
• Small surface on purpose. Chat completions, streaming, and model listing are all it does. See CONTRIBUTING.md if you want to add something.

Contributing

See CONTRIBUTING.md. Security issues go through SECURITY.md, not a public issue.

License

MIT

---

Maintained by Tisankan Jeyakumar hello@tisankan.dev · https://tisankan.dev · https://github.com/Tisankan-dev