OpenRouter 怎么用：从第一次调用到接进现有项目

数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。

OpenRouter 的用法可以拆成四步：账户里先有额度、建一把 API key、用 /api/v1/chat/completions 发出第一个请求、再决定用哪种集成方式接进现有项目。 官方文档把集成路径明确分成三条——直接调 API、用 Client SDK、用 Agent SDK，另外还支持把 OpenAI SDK 的 baseURL 指过来做 drop-in 替换。真正容易卡住的不是第一个请求，而是接进项目之后：model 字段该填什么、fallback 怎么配、额度和限额分别在哪里查。这几件事官方文档都有明文，下面按真实操作顺序走一遍。

先决定走哪条集成路径

官方 Quickstart 一开头就摆了一张表，把三种接入方式和各自的适用场景对上了：

• API：直接发标准 HTTP 请求。官方给的定位是”完全控制、任何语言、无依赖”。
• Client SDKs（@openrouter/sdk，Python 侧包名 openrouter）：官方描述是对 REST API 的一层薄封装，类型由 OpenAPI spec 自动生成，适合要类型安全但不想引入额外开销的场景。
• Agent SDK（@openrouter/agent）：提供更高层的原语，通过 callModel 自动处理多轮对话循环、工具执行和状态管理，适合做 agent。

这张表值得先看一眼再动手，因为三条路的心智负担差别很大。如果你只是想在现有服务里换个模型来源，直接调 API 或者用 OpenAI SDK 指过来就够了；如果你要做的是带工具调用的 agent，官方明确把 Agent SDK 定位在这个位置——它会把”发提示词、收到模型返回的工具调用、执行工具、把结果喂回去、拿最终回复”这一整圈都收在一次 callModel 调用里。

顺带一提，官方文档还提到如果你用 AI 编码工具写代码，可以连它托管的 MCP server（远程服务，不需要本地安装，加一个 URL 再走一次 OAuth 登录即可），让助手拿到当前有哪些模型、余额多少这类实时数据，而不是靠训练时的旧知识猜。但官方也补了一句：真正跑模型还是要直接调 OpenRouter API。

第一次调用前要准备的两样东西

第一样是额度。 官方 FAQ 里”怎么开始”那条说得很直白：先注册账号，在 Credits 页面加额度；额度就是存在 OpenRouter 上的一笔预付款，你用 API 或者网页聊天界面时，从里面扣掉这次请求的成本。每个模型、每个供应商的单价不同，具体数字看官方模型页，本文不列。

第二样是 API key。 官方文档的做法是去 keys 页面创建，给它起个名字，然后可以选择性地设一个额度上限。这个可选上限很关键，后面排查 402 的时候还会再遇到它——它和账户余额是两套独立的闸门。另外官方在 Authentication 一节专门加了一条警告：OpenRouter 的 API key 比直接找模型厂商拿的 key “更强”，因为它能给应用设额度上限，还能用在 OAuth 流程里。权限更大意味着泄漏的代价更大，key 的存放和轮换建议参考API 密钥安全管理的通用做法。

发出第一个请求

端点是 https://openrouter.ai/api/v1/chat/completions，鉴权走 Bearer token。官方给的 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>",       # Optional
    "X-OpenRouter-Title": "<YOUR_SITE_NAME>", # Optional
  },
  data=json.dumps({
    "model": "~openai/gpt-latest",
    "messages": [{"role": "user", "content": "What is the meaning of life?"}]
  })
)

请求体形状和大多数人熟悉的 chat completions 一致；官方的请求 schema 里注明的是 messages 与 prompt 二者取其一，具体必填组合以官方 schema 为准。两个 OpenRouter 专用的头都是可选的，官方在 Quickstart 里的原话是：设上它们能让你的应用出现在 OpenRouter 的榜单上。

这两个头的行为在 App Attribution 那篇文档里说得更细，也更容易踩坑：

• HTTP-Referer 是必需的那个。它是应用在榜单里的主标识，不带它就不会生成应用页面，用量也不会出现在排行里。
• X-OpenRouter-Title 只负责设置或修改展示名称，单独设它不会创建应用页面，必须和 HTTP-Referer 配对使用。旧的 X-Title 出于向后兼容仍然支持。
• 有一个额外条件：用 localhost 作为 URL 的应用，必须同时带上 X-OpenRouter-Title 才会被统计。本地开发阶段想看到数据的话，这条要注意。
• 还有一个 X-OpenRouter-Categories，用逗号分隔的小写连字符形式给应用打市场分类。官方把分类分成 Coding、Creative、Productivity、Entertainment 四组（cli-agent、ide-extension、writing-assistant 这类取值属于其中），并说明无法识别的取值会被静默丢弃、不报错。取值清单以官方文档当前版本为准。

“静默丢弃不报错”这个设计有点反直觉：分类没生效时你不会收到任何错误提示，只能回榜单页面看结果。

model 字段到底填什么

模型 slug 可以在官方模型页浏览，也可以用 GET /api/v1/models 把全部可用 slug 拉下来。这个接口在自动化场景里比人肉抄 slug 靠谱得多——模型上下线频繁，硬编码一个 slug 迟早会踩到模型已下线的情况（官方在 Embeddings 接口的错误说明里，把 404 解释为指定模型不存在或不适用于该接口）。

官方还提供了一类 latest 别名，形如 ~author/family-latest，永远解析到该系列里最新的具体模型。文档给的场景是：模型作者发布新版本时，OpenRouter 会自动把别名路由过去，老代码不用重新部署就跟着升级了。它适合”我要最好的那个”而不是”我要复现某次结果”的场合；需要可复现性的地方仍然应该钉死具体版本。

一个实用细节：响应体的 model 字段返回的是实际服务了这次请求的具体版本。也就是说你用别名发请求，读一下响应里的 model 就知道它落到了哪个模型上。这个字段在配了 fallback 之后同样有用，见下一节。至于 OpenRouter 在多个供应商之间怎么选，属于路由机制的范畴。

接进现有项目：改一行还是改一层

如果项目已经建在 OpenAI SDK 上，官方明确支持把它当 drop-in 替换用：base_url 设成 https://openrouter.ai/api/v1，api_key 换成 OpenRouter 的 key，代码结构不用动。这是改动量最小的一条路。

比”能不能调通”更值得先设计的是失败时怎么办。官方提供了 models 参数：传一个按优先级排序的模型 ID 数组，第一个模型报错时自动往下试。文档列出了默认会触发 fallback 的错误类型，包括上下文长度校验错误、被过滤模型的审核标记、限流、以及宕机。要注意兜底不是无限的——如果 fallback 模型也挂了或者也报错，OpenRouter 就把那个错误返回给你。

计费口径也在这里说清楚了：按最终真正服务请求的那个模型计价，具体是哪个看响应体的 model 属性。所以配了 fallback 之后，账单上出现你以为没在用的模型并不奇怪，对账时先看这个字段。

用 OpenAI SDK 时，models 数组要放进 extra_body 里传。另外 OpenRouter 也提供了 Anthropic Messages 形状的端点 /api/v1/messages，它接受 fallbacks 参数，形状与 Anthropic SDK 一致，但底层映射到的还是 OpenRouter 自己的 models 路由——官方特意加了注释说明这不是 Anthropic 的服务端 fallback 功能。它有几条硬限制：每个 fallbacks 条目只接受 model 字段，max_tokens、thinking 这类逐次覆盖会被拒；fallbacks 不能和 models 同时传；条目数有上限。违反这几条都会返回 400，具体上限以官方文档为准。

上线前把额度与限额的监控挂上

官方 Limits 文档把限制明确分成两类，别混着排查：

限制类型	管什么	去哪儿查
Credit limits	你能花多少（账户余额 + 单 key 的额度上限）	GET /api/v1/key 的 limit_remaining
Rate limits	你能发多少请求（免费模型请求上限、DDoS 防护）	错误响应上的 X-RateLimit-* 头

GET /api/v1/key 是接项目时最该先加进监控的一个调用。它返回的字段里，limit / limit_reset / limit_remaining 描述的是这把 key 上那个可选的消费上限（为 null 表示不限）；usage、usage_daily、usage_weekly、usage_monthly 分别是累计、当前 UTC 日、当前 UTC 周（周一起算）、当前 UTC 月的消耗；byok_usage 系列是同口径的外部 BYOK 用量；is_free_tier 表示这个用户此前有没有付过费。另外响应里还有一个 rate_limit 对象，官方注释里写明它已废弃、可以安全忽略——照着它做逻辑就是给自己挖坑。

余额这一侧有条容易写反的规则：官方说账户余额为负时，你可能会看到报错，而且这种失败会波及免费模型；把余额补到零以上就能重新使用这些模型。注意情态词是”可能”不是”一定”。所以”免费模型突然全挂了”的排查顺序里，先看余额是不是负的，这一步比看限流早。

限流这一侧还有条反直觉的说明：官方在 Limits 页顶部的提示里写了，多开账号或多建 API key 不会提高你的限额，因为容量是全局管控的。但不同模型的限额不同，所以真遇到瓶颈可以用换模型的方式分摊负载。触发限流时返回的错误体里带 metadata.error_type 为 rate_limit_exceeded，重试策略可以参考429 的通用处理思路。

最后：三个最容易栽的地方

第一，别用多建 key 来”绕限流”——官方已经说明容量是全局的，这条路走不通，只会让你的 key 管理变乱。

第二，别在没读响应 model 字段的情况下配 fallback。计费按最终执行的模型算，不看这个字段就无法解释账单构成。

第三，把 402 和 429 分开处理。前者是钱的问题，官方给的顺序是先充值把余额补正，再检查单 key 的 limit_remaining 是不是耗尽了（必要时提高上限或等 limit_reset），最好是主动调 GET /api/v1/key 提前监控；后者是频次问题，走退避重试。两者的排查入口完全不同，混在一起查会绕远路。

想先搞清楚这套东西在整条模型调用链上的位置，可以回头看OpenRouter 是什么。