快速开始

开始使用 OpenRouter

OpenRouter 通过单一 API 端点，让你接入数百种 AI 模型。它会自动处理回退，并为每次请求选择最具成本效益的选项。

根据你需要的控制程度，有三种方式可以集成 OpenRouter：

阅读 https://github.com/OpenRouterTeam/skills/tree/main/skills/create-agent-tui 并按照说明使用 OpenRouter 构建智能体。

在下面的示例中，OpenRouter 专用请求头是可选的。设置它们后，你的应用就可以出现在 OpenRouter 排行榜上。关于应用归因的详细说明，请参阅 应用归因指南。

使用 OpenRouter API

这是使用 OpenRouter 最直接的方式。向 /api/v1/chat/completions 端点发送标准 HTTP 请求即可，适用于任何语言或框架。

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>", # 可选。用于 openrouter.ai 排行榜的站点 URL。
    "X-OpenRouter-Title": "<YOUR_SITE_NAME>", # 可选。用于 openrouter.ai 排行榜的站点标题。
  },
  data=json.dumps({
    "model": "~openai/gpt-latest",
    "messages": [
      {
        "role": "user",
        "content": "人生的意义是什么？"
      }
    ]
  })
)

该 API 也支持 流式传输。你还可以将指向 OpenRouter 的 OpenAI SDK 作为即插即用替代方案。

使用客户端 SDK

客户端 SDK 封装了 OpenRouter API，提供完整的类型安全、由 OpenAPI 规范自动生成的类型，以及零样板代码。它刻意保持精简，是 REST API 上的一层薄封装。

首先安装 SDK：

npm install @openrouter/sdk

然后在代码中使用：

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

const client = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
  httpReferer: '<YOUR_SITE_URL>', // 可选。用于 openrouter.ai 排行榜的站点 URL。
  appTitle: '<YOUR_SITE_NAME>', // 可选。用于 openrouter.ai 排行榜的站点标题。
});

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

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

完整的 客户端 SDK 文档 涵盖流式传输、嵌入（embeddings）以及完整的 API 参考。

使用 Agent SDK

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

安装该包：

npm install @openrouter/agent

构建一个带工具的智能体：

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

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

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 = openrouter.callModel({
  model: '~anthropic/claude-sonnet-latest',
  messages: [
    { role: 'user', content: '旧金山的天气怎么样？' },
  ],
  tools: [weatherTool],
});

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

SDK 会发送提示词，接收模型返回的工具调用，执行 get_weather，将结果回传，并返回最终回复——全部在一次 callModel 调用中完成。

完整的 Agent SDK 文档 涵盖停止条件、流式传输、动态参数等更多内容。

使用 OpenAI SDK

你也可以将指向 OpenRouter 的 OpenAI SDK 作为即插即用替代方案。如果你已有基于 OpenAI SDK 的代码，想在不改动代码结构的前提下使用 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>', // 可选。用于 openrouter.ai 排行榜的站点 URL。
    'X-OpenRouter-Title': '<YOUR_SITE_NAME>', // 可选。用于 openrouter.ai 排行榜的站点标题。
  },
});

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

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

main();

使用第三方 SDK

关于在 OpenRouter 中使用第三方 SDK 和框架的信息，请 参阅我们的框架文档。

借助 AI 助手进行开发

如果你使用 AI 编程工具编写代码（Claude Code、Cursor、Codex 等），请连接 OpenRouter 的模型上下文协议（Model Context Protocol，MCP）服务器。这是由 OpenRouter 托管的远程服务器，无需本地安装。你的助手可以拉取实时的 OpenRouter 数据（有哪些模型、价格如何、你的额度余额、用量排名），并在你开发时检索这些文档。这样它的建议会基于当前数据，而不是过时的训练知识。向 MCP 客户端添加一个 URL，并批准 OAuth 登录即可：

https://mcp.openrouter.ai/mcp

各客户端的配置步骤和完整工具列表见 MCP 服务器指南。要在应用中运行模型，请继续直接调用 OpenRouter API。