OpenRouter API 入门：统一调用多家 AI 模型与成本控制

OpenRouter 通过一个兼容 OpenAI 的 API 提供多种模型与推理供应商的统一入口。本文从第一条请求开始，解释模型选择、供应商路由、fallback、用量与密钥保护，并给出上线前的检查方法。

资料核对日期：2026-10-22。 模型列表、供应商状态和计费规则会变化，实际调用前请查看官方 Models、Pricing 与账户 Activity 页面。

OpenRouter 适合什么场景

当应用需要比较多家模型、按任务切换模型，或希望减少对单一推理供应商的耦合时，OpenRouter 可以提供统一的 API 入口。你的应用仍然要决定提示词、模型 ID、超时和重试；OpenRouter 负责接受请求并按照模型及 provider 设置路由。

它不是一个新的基础模型，也不意味着所有模型具有相同能力、价格、数据政策或 SLA。选择具体模型前，应先在官方目录检查当前可用性和价格，并用自己的真实任务做小规模评估。

准备 API Key 与环境

在 OpenRouter 控制台创建 API Key。把它放在后端环境变量或 Secret Manager 中，不要放到网页 JavaScript、公开仓库、截图或日志里。建议为开发、测试、生产分别使用 Key，并给每个 Key 配置适合其用途的额度限制。限制功能和计费显示可能随账户设置变化，应以控制台为准。

macOS 或 Linux 当前终端可这样设置：

export OPENROUTER_API_KEY="替换为自己的密钥"

不要把上面的示例值当作真实密钥，也不要把真实 Key 写进命令历史或提交到 Git。

第一次请求

官方兼容 API 的基础地址为 https://openrouter.ai/api/v1。Chat Completions 路径为 /chat/completions。先从 Models 页面复制一个当前有效的模型 ID：模型名称、可用地区和供应商会变动，不要依赖教程中长期固定的价格或型号。

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "替换为当前模型 ID",
    "messages": [
      {"role": "user", "content": "用三句话说明什么是 RAG。"}
    ],
    "stream": false
  }'

成功时检查 HTTP 状态和 JSON 响应中的 choices。程序要处理超时、限流、服务端错误和无效模型，不应把任意非 2xx 响应当成正常回答。生产环境还应限制请求体、输出长度和并发。

通过 OpenAI Python SDK 调用

已有 OpenAI Python 客户端时，通常可以设置 OpenRouter 的 base URL，并在服务器侧读取 Key：

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key=os.environ["OPENROUTER_API_KEY"],
    timeout=30.0,
)

response = client.chat.completions.create(
    model=os.environ["OPENROUTER_MODEL"],
    messages=[{"role": "user", "content": "列出上线前的三项检查。"}],
)
print(response.choices[0].message.content)

SDK 的兼容性不代表所有厂商专属参数都能跨模型通用。先用最小请求验证，再逐项加入工具调用、JSON 格式或多模态输入，并针对目标模型测试。

模型路由与供应商路由

请求中的 model 选择模型。一个模型可能由多个推理 provider 提供服务；provider 规则控制具体由哪些供应商处理请求。默认路由策略可能随产品更新，不能把它理解成固定的最低价或固定顺序。

需要限制可用供应商时，可在请求中传入 provider 对象。以下是结构示意，具体支持项以官方 Provider Routing 文档为准：

{
  "model": "替换为当前模型 ID",
  "messages": [{"role": "user", "content": "你好"}],
  "provider": {
    "only": ["替换为允许的 provider"]
  }
}

只允许指定 provider 可以满足明确的供应商范围要求，但会降低容错能力；如需设置顺序，可使用 provider.order。若数据地域、合规或合同要求限定 provider，应明确允许列表，验证实际路由能力，并查看每家供应商自己的数据政策。不能仅凭统一 API 推断数据留存或训练规则。

模型级 fallback：请求失败时切换候选模型

当主模型所在 provider 不可用、限流或拒绝响应时，可以用顶层 models 数组设置模型尝试顺序。以下是官方 Chat Completions 请求形状的占位示例；替换为当前可用的模型 ID，并用代表性输入检查输出差异：

{
  "models": ["替换为主模型 ID", "替换为备用模型 ID"],
  "messages": [{"role": "user", "content": "总结这段文本。"}]
}

模型级 fallback 和 provider 路由是不同层级：前者可能改变所用模型，后者调整同一模型的推理供应商。fallback 并非服务可用性的保证，网关自身或网络故障未必能靠切换模型恢复。成功响应里的模型字段应纳入用量核对；若备选模型的计费不同，最终费用也可能不同。

应用侧仍应设置请求超时、有限重试和总耗时上限。对 JSON schema、工具调用、拒答处理等依赖特定行为的流程，给主模型和每个备选模型运行同一组回归样例。避免把网关回退与应用自动重试叠加成无上限循环。

机制	调整层级	适用情况	注意点
Provider 路由	同一模型的推理供应商	限定或优先某些 provider	限制范围会减少可用回退路径
Model fallback	顶层 models 候选模型	主模型不可用或返回特定错误时尝试其它模型	可能改变输出和最终计费模型
应用重试	你自己的调用逻辑	处理网络波动或短暂错误	应限制次数、退避和总耗时

选择模型与控制支出

可以把选型拆为四步：先列出任务需要的输入类型、上下文长度和输出格式；再从 Models 目录筛选当前可用模型；然后用同一组代表性输入比较回答质量、延迟和实际费用；最后设置 Key 额度、应用侧输出上限和告警。不要只看单次演示或榜单，也不要把某个目录价格当成最终账单保证。缓存、上下文长度和模型特性都会影响实际使用量。

建议从开发环境的小额请求开始，逐步提升并发。根据业务为不同任务选择模型，避免默认所有功能都调用最贵或能力过剩的模型。设置合理的最大输出长度；对重复上下文评估缓存和精简提示词；按时间段和 Key 定期核对 Activity 与自己的用量日志。若账单和预期不符，检查重试次数、输出 token、备选模型、工作区额度及计费规则，不要在公开 issue 中贴带 Authorization header 的完整请求。

上线前安全清单

Key 只存服务器端秘密配置；浏览器和公开仓库不应接触主 Key。
开发、测试、生产环境使用不同 Key，限制额度并确认撤销流程。
对敏感数据核对 OpenRouter 与实际 provider 的数据处理政策和允许路由范围。
对请求体、输入输出长度、并发、超时和重试设置边界。
监控请求 ID、状态、模型和耗时；不记录密钥，也避免保存不必要的原始提示。
为主模型和备选模型验证结构化输出、工具调用和拒答行为。

常见问题

能直接替换 OpenAI SDK 吗？

很多 Chat Completions 场景可通过改变 base URL、Key 和模型 ID 迁移；但参数、工具调用、多模态能力仍应逐模型验证。

fallback 会选到另一个模型吗？

供应商 fallback 通常仍服务于所选模型；模型级 fallback 则可能切换模型。配置层级和触发条件不同，应按官方文档分别设置。

能否把 Key 放进浏览器？

不应如此。浏览器代码可以被用户查看，Key 一旦暴露就可能被滥用。由自己的后端代为调用，并实施鉴权与限额。

官方资料

从一个小请求开始，先验证模型能力、路由限制和成本观测，再把调用接入真实业务。