OpenRouter TypeScript SDK（@openrouter/sdk）是官方提供的 TypeScript/JavaScript 客户端，处于 beta 阶段。基于 OpenAPI spec 自动生成，提供完整 TypeScript 类型推断（编译时捕获错误），支持同步/流式 chat completions。npm install @openrouter/sdk 即可使用，适合单次推理、streaming、embeddings 等直接 API 调用场景。

Beta：TypeScript SDK 及文档处于 beta 阶段，如遇问题请在 GitHub 提 issue。

OpenRouter TypeScript SDK 提供类型安全的接口，用一行代码调用 300+ 语言模型。

安装

npm install @openrouter/sdk

从 openrouter.ai/settings/keys 获取 API key。

快速示例

import OpenRouter from '@openrouter/sdk';

const client = new OpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY
});

const response = await client.chat.send({
  model: "openai/gpt-4o",
  messages: [
    { role: "user", content: "Hello!" }
  ]
});

console.log(response.choices[0].message.content);

核心特性

自动同步 API 变更

SDK 从 OpenRouter OpenAPI spec 自动生成。新模型、参数、接口在每次 API 更新后立即可用，IDE 自动补全实时跟进，无需手动升级。

TypeScript 类型安全

每个参数、响应字段、配置选项都有完整的类型定义，编译时就能发现错误：

const response = await client.chat.send({
  model: "openai/gpt-4o",
  messages: [
    { role: "user", content: "Hello" }  // IDE 验证消息结构
  ],
  temperature: 0.7,  // 类型检查
  stream: true       // 响应类型随此参数变化
});

错误信息清晰可操作，例如：

"Model 'openai/o1-preview' requires at least 2 messages. You provided 1 message."

Streaming 流式输出

const stream = await client.chat.send({
  model: "openai/gpt-4o",
  messages: [{ role: "user", content: "Write a story" }],
  stream: true
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content;
  if (content) process.stdout.write(content);
}

TypeScript SDK vs Agent SDK

如果只需要直接调用 API，使用 @openrouter/sdk；如果需要多轮 agent 循环、工具定义和 stop conditions，使用 @openrouter/agent。

	TypeScript SDK	Agent SDK
定位	直接 API 调用	Agent 原语
对话状态	自行维护	callModel 自动管理
工具执行	自行派发	tool() 自动执行
迁移指南	—	从 SDK 迁移

常见问题

Q: @openrouter/sdk 和直接调 OpenRouter REST API 有什么区别？

A: SDK 提供完整 TypeScript 类型推断、自动处理认证头、封装好的流式迭代接口，减少样板代码。功能上没有本质差异，但开发体验更好。

Q: SDK 更新频率如何？

A: SDK 从 OpenAPI spec 自动生成，每次 OpenRouter API 更新后同步生成新版本，不需要等待手动维护。

Q: 如果我需要 Agent 功能，应该怎么迁移？

A: 参考迁移指南，主要是替换导入路径，将 @openrouter/sdk/funcs/call-model 等子路径改为 @openrouter/agent/call-model。