OpenRouter 是什么？

OpenRouter 是多模型 API 路由平台，用统一的聊天补全接口连接不同模型与提供商，并支持模型回退、提供商选择和集中结算。

OpenRouter API 是否免费？

官方提供多款免费模型和有限的每日请求，适合学习与原型；生产使用通常需要充值并按最终模型计费，具体额度与价格以官方页面为准。

可以直接用 OpenAI SDK 调用 OpenRouter 吗？

可以。把 SDK 的 baseURL 设置为 https://openrouter.ai/api/v1，并使用 OPENROUTER_API_KEY；但仍要验证各模型对参数、工具调用和结构化输出的支持。

OpenRouter 模型回退怎样计费？

回退列表按顺序尝试，最终由成功处理请求的模型计费。应记录响应中的实际模型、token 用量和价格，不能只按首选模型估算。

OpenRouter 会保存提示词和响应吗？

官方说明默认不保存提示词和响应内容，除非用户选择相关日志或改进计划，但会保存请求元数据；实际模型提供商仍可能有自己的数据政策。

生产环境使用 OpenRouter 最重要的安全措施是什么？

密钥只放服务端 Secret，按环境拆分并设置额度；限制敏感数据，检查实际提供商政策，配置数据收集或 ZDR 约束，并避免在日志中记录完整提示词和响应。

OpenRouter 多模型 API 教程 2026：统一接入、回退路由与成本控制完整指南（开发者实战版）

先说结论

OpenRouter 适合需要在一个应用中测试、切换或组合多个大模型的开发者。它提供统一的聊天补全接口，并兼容常见的 OpenAI SDK 调用方式。你可以先接入一个模型，再通过有序模型列表配置自动回退；也可以约束提供商、数据收集策略和零数据保留要求。

它不是“无限免费的模型 API”，也不是所有模型提供商的隐私与稳定性担保人。OpenRouter 负责统一路由和结算，实际请求仍会交给选定的模型提供商处理。生产环境必须同时评估模型费用、平台购点费用、速率限制、提供商政策、失败回退和日志中的敏感信息。

本文从最小请求开始，依次实现 Node.js 接入、OpenAI SDK 兼容调用、模型回退、提供商约束、错误处理、成本控制和上线检查。所有示例只读取环境变量 OPENROUTER_API_KEY，不要把真实密钥写进代码、前端或 Git 仓库。

OpenRouter 解决什么问题

直接对接多个模型厂商时，团队通常要分别处理不同 API 地址、认证方式、模型名称、定价单位、速率限制、区域可用性和故障机制。OpenRouter 把这些差异收敛到一个统一入口。原型阶段可以快速更换 model；生产应用可以提供有序候选，让服务在首选模型限速、下线或错误时继续尝试下一项。

系统也因此多了一层依赖。最终可用性由 OpenRouter、选定提供商、目标模型和自身应用共同决定。统一接口不代表统一 SLA，也不代表所有模型具有相同的隐私规则。

第一步：创建并保护 API Key

在 OpenRouter 控制台创建 API Key。官方认证文档支持为 Key 设置可选额度上限，这对测试环境和团队分发很重要。创建后不要把完整密钥粘贴到工单、聊天记录或截图中。

在本地 shell 中设置：

bash

export OPENROUTER_API_KEY="your-key-here"

生产环境应使用部署平台的 Secret Manager、Kubernetes Secret 或云厂商密钥服务。不要把 Key 放进前端环境变量，因为浏览器中的密钥最终会暴露给用户；也不要提交包含真实值的 .env 文件。仓库只保留：

text

OPENROUTER_API_KEY=

开发、预发布和生产最好使用不同 Key，并设置不同额度。发生泄露时只需吊销受影响的 Key。

第二步：用 fetch 发送最小请求

聊天补全端点是 https://openrouter.ai/api/v1/chat/completions。Node.js 18+ 示例：

const apiKey = process.env.OPENROUTER_API_KEY;

if (!apiKey) {
  throw new Error("Missing OPENROUTER_API_KEY");
}

const response = await fetch(
  "https://openrouter.ai/api/v1/chat/completions",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
      "HTTP-Referer": "https://your-app.example",
      "X-Title": "Your App Name"
    },
    body: JSON.stringify({
      model: "openai/gpt-4.1-mini",
      messages: [
        {
          role: "user",
          content: "用三点解释为什么 API 密钥不能放在前端。"
        }
      ]
    })
  }
);

const body = await response.json();

if (!response.ok) {
  throw new Error(
    `OpenRouter ${response.status}: ${JSON.stringify(body)}`
  );
}

console.log(body.choices[0].message.content);
console.log("Actual model:", body.model);

HTTP-Referer 和 X-Title 是可选应用标识，不能替代认证。模型名称会变化，运行前应从 OpenRouter 模型页面选择当前可用模型。教程里的模型只是结构示范，不应成为永久硬编码的业务假设。

第三步：复用 OpenAI SDK

已有 OpenAI JavaScript SDK 的项目可以修改 baseURL：

import OpenAI from "openai";

const apiKey = process.env.OPENROUTER_API_KEY;

if (!apiKey) {
  throw new Error("Missing OPENROUTER_API_KEY");
}

const client = new OpenAI({
  apiKey,
  baseURL: "https://openrouter.ai/api/v1",
  defaultHeaders: {
    "HTTP-Referer": "https://your-app.example",
    "X-Title": "Your App Name"
  }
});

const completion = await client.chat.completions.create({
  model: "openai/gpt-4.1-mini",
  messages: [
    {
      role: "system",
      content: "回答必须简洁，并明确不确定性。"
    },
    {
      role: "user",
      content: "给我一个 API 失败重试检查表。"
    }
  ]
});

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

接口格式兼容不等于能力一致。结构化输出、工具调用、多模态输入、推理参数和最大输出长度都可能因模型而异，必须针对实际模型做回归测试。

第四步：配置模型回退

OpenRouter 支持用 models 数组提供有序候选。当首选模型发生上下文长度错误、内容审核、速率限制或服务故障等情况时，可以尝试下一项：

const response = await fetch(
  "https://openrouter.ai/api/v1/chat/completions",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      models: [
        "anthropic/claude-sonnet-4",
        "openai/gpt-4.1-mini",
        "google/gemini-2.5-flash"
      ],
      messages: [
        {
          role: "user",
          content: "把这段会议记录整理成行动项。"
        }
      ]
    })
  }
);

const body = await response.json();

if (!response.ok) {
  throw new Error(
    `OpenRouter ${response.status}: ${JSON.stringify(body)}`
  );
}

console.log("Model used:", body.model);
console.log(body.choices[0].message.content);

候选顺序是业务决策。不要只按能力排序，还要考虑价格、延迟、上下文长度、工具调用、区域和输出稳定性。回退后按最终实际使用的模型计费，应记录响应中的模型标识、请求 ID、延迟和 token 用量。

第五步：限制提供商与数据处理

同一模型可能由多个提供商端点托管。OpenRouter 支持通过 provider 控制路由。处理隐私敏感数据时，不要只看模型名称，要检查最终端点的数据政策。

不允许选择会收集数据的端点：

const request = {
  model: "openai/gpt-4.1-mini",
  messages: [
    {
      role: "user",
      content: "总结这份已经脱敏的产品反馈。"
    }
  ],
  provider: {
    data_collection: "deny"
  }
};

OpenRouter 官方说明，默认不会保存提示词与响应内容，除非用户选择加入日志或改进计划，但会保存请求元数据。实际提供商仍可能有自己的政策。

如果组织要求零数据保留，应阅读 ZDR 文档并配置相应约束。ZDR 是端点级能力，不应仅凭厂商品牌推断。约束越严格，可选端点越少，可能影响价格、延迟与可用性。无论如何，都应先在应用侧删除不必要的个人信息、密钥、支付数据和机密文档。

第六步：正确处理错误与重试

常见状态包括：

400：参数、模型或上下文不正确；
401：Key 缺失、无效或被撤销；
402：余额或额度不足；
403：内容策略或访问条件阻止请求；
408：请求超时；
429：速率限制；
502：上游模型或提供商失败；
503：没有端点满足路由条件。

只对可能恢复的 408、429、502 和 503 重试。400、401、402、403 通常需要修改请求、权限、余额或内容，立即重复只会制造更多失败。

const retryable = new Set([408, 429, 502, 503]);

const sleep = (ms) =>
  new Promise((resolve) => setTimeout(resolve, ms));

async function requestWithRetry(makeRequest, maxAttempts = 3) {
  let lastError;

  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
    const response = await makeRequest();

    if (response.ok) {
      return response.json();
    }

    const body = await response.text();
    lastError = new Error(
      `OpenRouter ${response.status}: ${body}`
    );

    if (!retryable.has(response.status) || attempt === maxAttempts) {
      throw lastError;
    }

    const retryAfter = Number(response.headers.get("retry-after"));
    const backoff = Number.isFinite(retryAfter)
      ? retryAfter * 1000
      : 500 * 2 ** (attempt - 1) + Math.random() * 250;

    await sleep(backoff);
  }

  throw lastError;
}

生产代码还要设置整体超时、取消信号和幂等边界。流式响应开始输出后再失败，不能简单重放并把两段内容同时展示。

第七步：查看 Key 额度和速率

官方提供 GET /api/v1/key 查看当前 Key 的额度与使用信息，可用于后台监控，但不要每次用户请求都同步查询：

const response = await fetch("https://openrouter.ai/api/v1/key", {
  headers: {
    Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`
  }
});

if (!response.ok) {
  throw new Error(`Key status failed: ${response.status}`);
}

console.log(await response.json());

为 Key 设置上限只是第一层防线。应用还要按用户和功能设置预算，限制输入长度、最大输出 token 与并发，为批量任务建立队列，记录实际模型、用量、价格和失败率，并在费用异常时告警。Agent 循环必须有最大轮次和总预算。

官方定价页当前列出 25 款以上免费模型和有限的每日请求；按量使用还涉及模型价格与平台购点费用。生产预算应读取官方最新价格，不能依赖教程中的静态数字。

可维护的模型策略

不要在业务代码各处散落模型字符串。建立集中配置：

export const modelPolicies = {
  fast: {
    models: [
      "google/gemini-2.5-flash",
      "openai/gpt-4.1-mini"
    ],
    maxTokens: 800
  },
  quality: {
    models: [
      "anthropic/claude-sonnet-4",
      "openai/gpt-4.1"
    ],
    maxTokens: 2000
  }
};

配置名描述业务目标，而不是绑定厂商。模型下线、价格变化或评测结果变化时可以统一切换。上线前用固定测试集比较准确率、格式遵循、工具调用、延迟和成本。

同时设计“无模型可用”的降级体验，例如提示稍后重试、转为搜索结果、进入人工队列，或提供不需要生成模型的基础功能。回退不是无限循环，也不应隐藏所有故障。

上线前检查表

Key 只存在于服务端 Secret，已设置额度上限和轮换流程；
开发、预发布、生产使用不同 Key；
模型和提供商策略集中配置；
已测试首选失败、回退成功和全部失败；
仅对可恢复错误指数退避，并设置整体超时；
日志不记录完整提示词、密钥和敏感响应；
记录实际模型、提供商、token、延迟、费用和请求 ID；
已评估 OpenRouter 与实际提供商的数据政策；
隐私要求已转化为数据收集或 ZDR 路由约束；
有预算告警、速率限制和异常用量熔断；
关键输出有人工审核或确定性校验。

常见误区

兼容 OpenAI SDK，就能无差别替换所有模型？ 不能。格式兼容不等于参数和输出行为一致。

配置回退，就不会宕机？ 不能保证。网络、账户余额、严格路由条件和所有候选端点都可能失败。

免费模型适合正式产品？ 更适合学习与原型。免费端点可能限速、排队或变化。

OpenRouter 不存提示词，请求就绝对不会被记录？ 还要检查实际提供商和自身日志系统。

最终建议

第一次接入只做三件事：用环境变量保护 Key，用一个模型跑通最小请求，并记录实际模型和用量。第二步再加入有序回退与可恢复错误重试。最后才引入提供商约束、ZDR、预算和自动评测。

OpenRouter 的核心价值是降低多模型接入与迁移成本，而不是替你做所有架构决策。把模型、价格、提供商和隐私要求当作可配置策略，配合清晰日志、预算与降级路径，统一路由才会成为可靠能力。

先说结论

OpenRouter 解决什么问题

第一步：创建并保护 API Key

在本地 shell 中设置：

bash

export OPENROUTER_API_KEY="your-key-here"

text

OPENROUTER_API_KEY=

开发、预发布和生产最好使用不同 Key，并设置不同额度。发生泄露时只需吊销受影响的 Key。

第二步：用 fetch 发送最小请求

聊天补全端点是 https://openrouter.ai/api/v1/chat/completions。Node.js 18+ 示例：

const apiKey = process.env.OPENROUTER_API_KEY;

if (!apiKey) {
  throw new Error("Missing OPENROUTER_API_KEY");
}

const response = await fetch(
  "https://openrouter.ai/api/v1/chat/completions",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
      "HTTP-Referer": "https://your-app.example",
      "X-Title": "Your App Name"
    },
    body: JSON.stringify({
      model: "openai/gpt-4.1-mini",
      messages: [
        {
          role: "user",
          content: "用三点解释为什么 API 密钥不能放在前端。"
        }
      ]
    })
  }
);

const body = await response.json();

if (!response.ok) {
  throw new Error(
    `OpenRouter ${response.status}: ${JSON.stringify(body)}`
  );
}

console.log(body.choices[0].message.content);
console.log("Actual model:", body.model);

第三步：复用 OpenAI SDK

已有 OpenAI JavaScript SDK 的项目可以修改 baseURL：

import OpenAI from "openai";

const apiKey = process.env.OPENROUTER_API_KEY;

if (!apiKey) {
  throw new Error("Missing OPENROUTER_API_KEY");
}

const client = new OpenAI({
  apiKey,
  baseURL: "https://openrouter.ai/api/v1",
  defaultHeaders: {
    "HTTP-Referer": "https://your-app.example",
    "X-Title": "Your App Name"
  }
});

const completion = await client.chat.completions.create({
  model: "openai/gpt-4.1-mini",
  messages: [
    {
      role: "system",
      content: "回答必须简洁，并明确不确定性。"
    },
    {
      role: "user",
      content: "给我一个 API 失败重试检查表。"
    }
  ]
});

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

接口格式兼容不等于能力一致。结构化输出、工具调用、多模态输入、推理参数和最大输出长度都可能因模型而异，必须针对实际模型做回归测试。

第四步：配置模型回退

OpenRouter 支持用 models 数组提供有序候选。当首选模型发生上下文长度错误、内容审核、速率限制或服务故障等情况时，可以尝试下一项：

const response = await fetch(
  "https://openrouter.ai/api/v1/chat/completions",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      models: [
        "anthropic/claude-sonnet-4",
        "openai/gpt-4.1-mini",
        "google/gemini-2.5-flash"
      ],
      messages: [
        {
          role: "user",
          content: "把这段会议记录整理成行动项。"
        }
      ]
    })
  }
);

const body = await response.json();

if (!response.ok) {
  throw new Error(
    `OpenRouter ${response.status}: ${JSON.stringify(body)}`
  );
}

console.log("Model used:", body.model);
console.log(body.choices[0].message.content);

第五步：限制提供商与数据处理

同一模型可能由多个提供商端点托管。OpenRouter 支持通过 provider 控制路由。处理隐私敏感数据时，不要只看模型名称，要检查最终端点的数据政策。

不允许选择会收集数据的端点：

const request = {
  model: "openai/gpt-4.1-mini",
  messages: [
    {
      role: "user",
      content: "总结这份已经脱敏的产品反馈。"
    }
  ],
  provider: {
    data_collection: "deny"
  }
};

OpenRouter 官方说明，默认不会保存提示词与响应内容，除非用户选择加入日志或改进计划，但会保存请求元数据。实际提供商仍可能有自己的政策。

第六步：正确处理错误与重试

常见状态包括：

400：参数、模型或上下文不正确；
401：Key 缺失、无效或被撤销；
402：余额或额度不足；
403：内容策略或访问条件阻止请求；
408：请求超时；
429：速率限制；
502：上游模型或提供商失败；
503：没有端点满足路由条件。

只对可能恢复的 408、429、502 和 503 重试。400、401、402、403 通常需要修改请求、权限、余额或内容，立即重复只会制造更多失败。

const retryable = new Set([408, 429, 502, 503]);

const sleep = (ms) =>
  new Promise((resolve) => setTimeout(resolve, ms));

async function requestWithRetry(makeRequest, maxAttempts = 3) {
  let lastError;

  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
    const response = await makeRequest();

    if (response.ok) {
      return response.json();
    }

    const body = await response.text();
    lastError = new Error(
      `OpenRouter ${response.status}: ${body}`
    );

    if (!retryable.has(response.status) || attempt === maxAttempts) {
      throw lastError;
    }

    const retryAfter = Number(response.headers.get("retry-after"));
    const backoff = Number.isFinite(retryAfter)
      ? retryAfter * 1000
      : 500 * 2 ** (attempt - 1) + Math.random() * 250;

    await sleep(backoff);
  }

  throw lastError;
}

生产代码还要设置整体超时、取消信号和幂等边界。流式响应开始输出后再失败，不能简单重放并把两段内容同时展示。

第七步：查看 Key 额度和速率

官方提供 GET /api/v1/key 查看当前 Key 的额度与使用信息，可用于后台监控，但不要每次用户请求都同步查询：

const response = await fetch("https://openrouter.ai/api/v1/key", {
  headers: {
    Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`
  }
});

if (!response.ok) {
  throw new Error(`Key status failed: ${response.status}`);
}

console.log(await response.json());

可维护的模型策略

不要在业务代码各处散落模型字符串。建立集中配置：

export const modelPolicies = {
  fast: {
    models: [
      "google/gemini-2.5-flash",
      "openai/gpt-4.1-mini"
    ],
    maxTokens: 800
  },
  quality: {
    models: [
      "anthropic/claude-sonnet-4",
      "openai/gpt-4.1"
    ],
    maxTokens: 2000
  }
};

上线前检查表

Key 只存在于服务端 Secret，已设置额度上限和轮换流程；
开发、预发布、生产使用不同 Key；
模型和提供商策略集中配置；
已测试首选失败、回退成功和全部失败；
仅对可恢复错误指数退避，并设置整体超时；
日志不记录完整提示词、密钥和敏感响应；
记录实际模型、提供商、token、延迟、费用和请求 ID；
已评估 OpenRouter 与实际提供商的数据政策；
隐私要求已转化为数据收集或 ZDR 路由约束；
有预算告警、速率限制和异常用量熔断；
关键输出有人工审核或确定性校验。

常见误区

兼容 OpenAI SDK，就能无差别替换所有模型？ 不能。格式兼容不等于参数和输出行为一致。

配置回退，就不会宕机？ 不能保证。网络、账户余额、严格路由条件和所有候选端点都可能失败。

免费模型适合正式产品？ 更适合学习与原型。免费端点可能限速、排队或变化。

OpenRouter 不存提示词，请求就绝对不会被记录？ 还要检查实际提供商和自身日志系统。

OpenRouter 多模型 API 教程：2026 年统一接入、路由与成本控制指南

先说结论

OpenRouter 解决什么问题

第一步：创建并保护 API Key

第二步：用 fetch 发送最小请求

第三步：复用 OpenAI SDK

第四步：配置模型回退

第五步：限制提供商与数据处理

第六步：正确处理错误与重试

第七步：查看 Key 额度和速率

可维护的模型策略

上线前检查表

常见误区

最终建议

常见问题

OpenRouter 多模型 API 教程：2026 年统一接入、路由与成本控制指南

先说结论

OpenRouter 解决什么问题

第一步：创建并保护 API Key

第二步：用 fetch 发送最小请求

第三步：复用 OpenAI SDK

第四步：配置模型回退

第五步：限制提供商与数据处理

第六步：正确处理错误与重试

第七步：查看 Key 额度和速率

可维护的模型策略

上线前检查表

常见误区

最终建议

常见问题