OpenRouter TypeScript SDK

技能简介

OpenRouter TypeScript SDK（@openrouter/sdk）是由 OpenRouter 官方提供的 TypeScript/JavaScript 开发工具包，为开发者构建 AI 应用提供了访问全球 400 余款大语言模型的统一接口。OpenRouter 本身是一个模型聚合网关，支持 Anthropic Claude、OpenAI GPT 系列、Google Gemini、Cohere、Mistral 等主流模型提供商，并提供模型竞价、负载均衡、费用托管等高级能力。该 SDK 以 TypeScript 编写，提供完整的类型推导支持，兼容 Node.js、Bun、Deno 等主流运行时。通过统一 API，开发者无需为每个模型单独编写适配层，一套代码可根据场景灵活切换模型，降低模型供应商锁定风险，提升应用可靠性。

核心能力

1. 400+ 模型统一接入：一个 SDK 接口访问全球所有主流模型提供商的最新模型，通过 model 参数指定模型标识符（如 openai/gpt-4o、anthropic/claude-3-5-sonnet），无需安装多个独立 SDK。

2. TypeScript 类型安全：完整类型定义覆盖所有 API 参数和响应字段，IDE 自动补全、编译期类型检查，开发体验接近 OpenAPI 规范的最佳实践。

3. 多运行时兼容：支持 npm、pnpm、bun、yarn 四大包管理器，可在 Node.js（≥18）、Bun、Deno 及现代浏览器环境中运行。

4. 流式输出（Streaming）：内置 async iterable 流式接口，支持逐 token 实时输出，可用于构建类 ChatGPT 的流式对话界面。

5. Provider 竞价与负载均衡：通过 provider 参数指定模型提供商偏好（如 { zdr: true, sort: "price" }），SDK 自动路由到最优或最便宜的可用 Provider，支持请求级别的 Failover。

6. BYOK（自带 Key）支持：可传入外部模型提供商的 API Key（BYOK），由 OpenRouter 代为中转路由，灵活管理多模型凭据。

7. 文件上传支持：集成 STT（语音转写）接口，支持流式文件上传，可构建语音识别类 AI 应用。

8. 分页接口：部分端点（如 BYOK 密钥列表）内置 async iterable 分页，直接用 for await...of 遍历所有页面，无需手动处理 cursor。

9. 调试日志：通过 debugLogger 选项或 OPENROUTER_DEBUG 环境变量开启 SDK 内部请求/响应日志，方便排查 API 调用问题。

10. OpenRouter 平台代付：无需在每个模型提供商分别开设账户，OpenRouter 提供统一账单，一个 Key 访问全量模型。

安装配置

1. 安装 SDK：

   # npm
   npm add @openrouter/sdk
   # 或 pnpm
   pnpm add @openrouter/sdk
   # 或 bun
   bun add @openrouter/sdk
   # 或 yarn
   yarn add @openrouter/sdk

2. 获取 OpenRouter API Key：访问 https://openrouter.ai/keys 注册并创建 API Key（平台支持 Google/GitHub 登录）。

3. 配置环境变量（推荐）：

   export OPENROUTER_API_KEY=sk-or-...

4. 初始化客户端：

   import { OpenRouter } from "@openrouter/sdk";
   
   const openRouter = new OpenRouter({
     apiKey: process.env["OPENROUTER_API_KEY"],
     appTitle: "My AI App",       // 可选，帮助 OpenRouter 识别应用来源
     appCategories: "productivity" // 可选
   });

5. ESM 注意事项：该包为纯 ESM 模块，若在 CommonJS 项目中使用，需用动态 import：

   const { OpenRouter } = await import("@openrouter/sdk");

使用步骤

1. 发送对话请求：

   const result = await openRouter.chat.send({
     messages: [
       { role: "user", content: "用 Python 写一个快速排序" }
     ],
     model: "openai/gpt-4o"
   });

2. 流式输出：

   const result = await openRouter.chat.send({
     messages: [{ role: "user", content: "解释什么是 MCP 协议" }],
     model: "anthropic/claude-3-5-sonnet",
     stream: true
   });
   for await (const chunk of result) {
     process.stdout.write(chunk.choices[0].delta.content);
   }

3. 指定 Provider 偏好（降本/高可用）：

   const result = await openRouter.chat.send({
     model: "openai/gpt-4o",
     provider: { zdr: true, sort: "price" } // 优先选择更便宜的 Provider
   });

4. 使用 BYOK（自有 Key）：

   const result = await openRouter.byok.list(); // 需配合 OpenRouter BYOK 功能

5. 接入代理日志排查问题：

   const sdk = new OpenRouter({ debugLogger: console });
   // 或设置环境变量：OPENROUTER_DEBUG=true

适用场景

1. AI 应用快速构建：开发者不想受单一模型限制，希望一套代码可按需切换 GPT-4、Claude 3.5、Gemini 等模型，通过 OpenRouter SDK 快速实现模型无关的应用架构。

2. 模型成本优化：通过 Provider 竞价参数，让 OpenRouter 自动将请求路由到当前价格最优的 Provider，无需人工比较每个模型提供商的价格。

3. 多模型 A/B 测试：在应用中同时向多个模型发送相同请求，对比输出质量，用于评估不同模型在特定任务上的表现差异。

4. 流式对话应用：构建实时 AI 助手、在线教育答疑、代码解释器等需要流式输出的产品，SDK 内置的 for await...of 接口简化了流式处理。

5. 企业多模型管理：大型团队通过 OpenRouter 统一管理多个模型提供商的 API 凭据，SDK 提供集中式接口，避免在代码中分散管理多个 API Key。

6. AI Gateway 自建：有自建 AI Gateway 需求的企业，通过 OpenRouter SDK 接入聚合层，自定义路由规则和费用管控策略。

适用人群

• 全栈工程师 / 应用开发者：需要在产品中集成 AI 能力，不希望被单一模型绑定，希望灵活切换模型的开发者。
• AI 应用创业团队：希望快速接入多个模型进行产品原型验证，或通过模型竞价降低 AI 推理成本的早期团队。
• 平台工程师 / AI Infra：负责构建企业内部 AI Gateway、模型路由层、费用管控系统的工程师。
• TypeScript 生态深度用户：偏好 TypeScript 类型安全、IDE 补全和编译期检查，不希望使用无类型的 JavaScript SDK。

工作原理

OpenRouter TypeScript SDK 封装了 OpenRouter REST API 的所有端点。开发者通过 new OpenRouter() 初始化客户端（传入 API Key），SDK 内部构造符合 OpenRouter API 规范的 HTTP 请求（默认指向 https://openrouter.ai/api/v1），使用 Bearer Token 认证。chat.send() 方法将 messages 和 model 参数序列化为请求体，POST 到 /chat/completions 端点。流式模式下，SDK 将 HTTP 响应体作为 async iterable 返回，调用方用 for await...of 逐块消费 Server-Sent Events（SSE）数据块。Provider 竞价通过请求体的 provider 对象控制，OpenRouter 服务器端据此决定实际路由目标模型提供商。

官方链接

• npm：https://www.npmjs.com/package/@openrouter/sdk
• OpenRouter 官方文档：https://openrouter.ai/docs/sdks/typescript
• SDK API 参考：https://openrouter.ai/docs/sdks/typescript/reference
• OpenRouter 模型列表：https://openrouter.ai/models