OpenRouter 提供统一 API，一个端点即可访问数百个 AI 模型，自动处理 fallback 和成本优化。本页介绍三种集成方式：直接调用 REST API（最灵活，支持任意语言）、使用 Client SDK（类型安全、零样板代码）、使用 Agent SDK（适合多轮对话和工具调用）。此外还介绍如何将现有 OpenAI SDK 代码无缝切换到 OpenRouter。

OpenRouter 提供统一 API，通过单个端点访问数百个 AI 模型，并自动处理 fallback、智能选择最具成本效益的方案。

三种集成方式，根据控制粒度选择：

方式	适用场景
直接调用 API	完全控制，支持任意语言，无需依赖
Client SDK	类型安全的模型调用，极少样板代码
Agent SDK	构建带工具调用、循环和状态管理的 Agent

关于免费模型和速率限制，请参阅 FAQ。

以下示例中，OpenRouter 特定的请求头是可选的，设置后你的应用会出现在 OpenRouter 排行榜上。详情参见 App Attribution 指南。

---

方式一：直接调用 OpenRouter API

最直接的方式，向 /api/v1/chat/completions 发送标准 HTTP 请求，与任何语言或框架兼容。

你也可以使用 Request Builder 交互式生成各语言的请求代码。

Python 示例：

import requests
import json

response = requests.post(
  url="https://openrouter.ai/api/v1/chat/completions",
  headers={
    "Authorization": "Bearer <OPENROUTER_API_KEY>",
    "HTTP-Referer": "<YOUR_SITE_URL>",      # 可选，用于排行榜展示
    "X-OpenRouter-Title": "<YOUR_SITE_NAME>",  # 可选，用于排行榜展示
  },
  data=json.dumps({
    "model": "openai/gpt-4o",
    "messages": [
      {
        "role": "user",
        "content": "生命的意义是什么？"
      }
    ]
  })
)

API 同样支持 streaming。

---

方式二：使用 Client SDK

Client SDK 对 OpenRouter API 做了类型安全封装，由 OpenAPI spec 自动生成，零样板代码，是 REST API 的轻量薄层。

安装：

npm install @openrouter/sdk

TypeScript 示例：

import OpenRouter from '@openrouter/sdk';

const client = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
  defaultHeaders: {
    'HTTP-Referer': '<YOUR_SITE_URL>',       // 可选
    'X-OpenRouter-Title': '<YOUR_SITE_NAME>', // 可选
  },
});

const completion = await client.chat.send({
  model: 'openai/gpt-4o',
  messages: [
    {
      role: 'user',
      content: '生命的意义是什么？',
    },
  ],
});

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

完整文档参见 Client SDK 文档，包含 streaming、embeddings 和完整 API 参考。

---

方式三：使用 Agent SDK

Agent SDK（@openrouter/agent）提供更高层次的 Agent 构建原语，通过 callModel 函数自动处理多轮对话循环、工具执行和状态管理。

安装：

npm install @openrouter/agent

带工具的 Agent 示例：

import { callModel, tool } from '@openrouter/agent';
import { z } from 'zod';

const weatherTool = tool({
  name: 'get_weather',
  description: '获取指定地点的当前天气',
  inputSchema: z.object({
    location: z.string().describe('城市名称'),
  }),
  execute: async ({ location }) => {
    return { temperature: 72, condition: 'sunny', location };
  },
});

const result = await callModel({
  model: 'anthropic/claude-sonnet-4-6',
  messages: [
    { role: 'user', content: '旧金山现在天气怎么样？' },
  ],
  tools: [weatherTool],
});

const text = await result.getText();
console.log(text);

SDK 会自动处理完整流程：发送 prompt → 接收 tool call → 执行 get_weather → 将结果返回给模型 → 输出最终响应，全部在一次 callModel 调用中完成。

完整文档参见 Agent SDK 文档，包含停止条件、streaming、动态参数等内容。

---

方式四：使用 OpenAI SDK（兼容模式）

如果你已有基于 OpenAI SDK 的代码，可以直接将 baseURL 指向 OpenRouter，无需修改代码结构即可访问 OpenRouter 的模型目录。

import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: 'https://openrouter.ai/api/v1',
  apiKey: '<OPENROUTER_API_KEY>',
  defaultHeaders: {
    'HTTP-Referer': '<YOUR_SITE_URL>',       // 可选
    'X-OpenRouter-Title': '<YOUR_SITE_NAME>', // 可选
  },
});

async function main() {
  const completion = await openai.chat.completions.create({
    model: 'openai/gpt-4o',
    messages: [
      {
        role: 'user',
        content: '生命的意义是什么？',
      },
    ],
  });

  console.log(completion.choices[0].message);
}

main();

关于更多第三方 SDK 和框架的使用，请参阅框架集成文档。

---

常见问题

Q: OpenRouter 的 API key 在哪里申请？

A: 前往 openrouter.ai/settings/keys 创建 API key，需先注册账号并充值。

Q: OpenRouter 和直接调用 OpenAI 有什么区别？

A: OpenRouter 提供统一 API 接口访问数百个模型（包括 Claude、Gemini、Llama 等），自动 fallback、统一计费，价格透明，pass-through 原始提供商的定价。

Q: HTTP-Referer 和 X-OpenRouter-Title 是必填的吗？

A: 不是必填，但填写后你的应用会出现在 OpenRouter 公开排行榜上，便于追踪使用情况。