OpenRouter 免费 API 怎么拿？从注册到第一次调用

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

OpenRouter 的「免费 API」其实是两样东西叠在一起：一是新账号会拿到的一小笔免费额度，二是站上那批本身就不计费的免费模型。前者是钱，后者是模型。官方对新用户额度只说了「所有新用户会收到一小笔免费额度用于试用」，没有进一步说明它的适用范围；而免费模型也并非与余额完全无关——账户余额为负时，官方说你可能会看到错误，且这种失败会波及免费模型。真正要动手的只有三步——去 keys 页建一把 key 并顺手设上额度上限，把 model 写成 openrouter/free 或者给某个模型 ID 追加 :free，然后按 OpenAI 兼容的方式往 /api/v1/chat/completions 发一次请求。最容易踩空的地方不在调用本身，而在两个认知：免费模型的每日请求上限是按你累计购买过多少额度分档的，以及多开账号、多建 key 都不会让限额变大，因为官方是全局管控容量的。

先分清两个「免费」，不然后面全是误会

官方 FAQ 里「What free tier options exist?」这一条写得很直白：所有新用户都会得到一小笔免费额度，用来试一试 OpenRouter；同时站上有一批免费模型，官方对它们的描述是每日请求上限较低，通常不适合用于生产环境。

这两句话说的是两件事。

免费额度是账户余额的一部分，它跟普通充值进来的额度形态一样，可以花在任何按 token 计费的模型上，花完就没了。免费模型则是模型侧的属性——你调它本身不产生推理费用，跟你账户里还剩多少额度没有直接关系。

所以「OpenRouter 免费 API 怎么拿」这个问题，如果你想要的是长期、可持续地零成本调用，答案落在免费模型那一侧，而不是那笔试用额度。

还有一个反直觉的机制值得先记住：免费模型的限速并不是所有人一个数。官方 FAQ「How are rate limits calculated?」的原话是，免费模型的限速由你购买过的额度决定；累计购买达到一定量之后，免费模型的每日请求上限会提高。也就是说，「免费」这一档的宽松程度反而取决于你付过多少钱。具体的分档门槛与每日上限数值，本文不写，以官方定价页与限额页当前版本为准。

第一步：建 key，顺手把额度上限设上

官方 Authentication 页给的路径很短：先去 keys 页创建一把 key，给它起个名字，创建时可以选择性地设一个额度上限（credit limit）。

这一页还有一条容易被跳过的提示：OpenRouter 的 API key 比你直接找模型厂商申请的 key 「更强」——它允许你为应用设置额度上限，也能用在 OAuth 流程里。权限更大意味着泄露的代价也更大，所以官方在同一页反复强调：绝不要把 key 提交进公开仓库，强烈建议用环境变量把它挡在代码库之外。

OpenRouter 是 GitHub secret scanning 的合作方，另外还有别的手段检测泄露的 key。如果官方判定你的 key 已经泄露，你会收到邮件通知；收到通知或者自己怀疑泄露了，官方给的动作是立刻去 key 设置页删掉那把被泄露的 key，再新建一把。关于 key 该怎么存、怎么分环境隔离，可以配合API key 安全管理那篇一起看。

对刚开始试的人来说，创建时那个可选的额度上限值得点上。原因在下一节的字段里：GET /api/v1/key 的响应里 limit、limit_reset、limit_remaining 这三个字段描述的就是这个 key 上的上限、重置方式和剩余量。设了上限，你才有一个可编程读取的刹车；不设的话这三个字段会是 null，表示不限、从不重置。

第二步：挑一个真正免费的模型

官方给了三条路，用途不太一样。

:free 变体。 Free Variant 文档说得很简单：给任意模型 ID 后面追加 :free，就能访问该模型的免费版本。但同一页紧接着有一句限定必须一起看——免费变体「may have different rate limits or availability compared to paid versions」，是「可能」与付费版在限速或可用性上不同，不是保证一致。FAQ 的变体清单里也把 :free 归为静态变体，说明是「始终免费提供，且限速较低」。

openrouter/free 免费模型路由器。 这条更适合刚上手。官方的描述是它会从当前可用的免费模型里随机挑一个，并且会按你这次请求需要的能力做过滤——文档点名的是图像理解、工具调用和结构化输出这几项。好处是你不用盯着某个具体模型是不是还在线；代价是每次用的可能不是同一个模型。返回体里的 model 字段会告诉你这次实际是谁应答的，官方示例代码里专门打印了这个字段。

自己浏览。 模型页支持按价格筛选，官方给的链接就带着 max_price=0 参数；想在网页里直接试，去 Chat Playground，点 Add Model 按钮或者按 Cmd+K / Ctrl+K 打开模型选择器，在搜索框输入 free 就能过滤出免费模型，Free Models Router 也在这个列表里。要程序化拿到全部可用 slug，调 GET /api/v1/models。

至于免费池里具体有哪些模型、哪个更适合你的任务，那是选型问题，OpenRouter 免费模型的能力边界那篇讲得更细，这里不展开。

第三步：发出第一次调用

端点是 https://openrouter.ai/api/v1/chat/completions，鉴权把 Authorization 头设成 Bearer token。官方 Quickstart 把集成方式列成三条路径：直接调 HTTP API（全控制、任何语言、无依赖）、用 Client SDK（类型安全、样板代码少）、用 Agent SDK（带工具执行、多轮循环与状态管理）。

另外还有一条经常被用到的：OpenAI SDK 可以直接指向 OpenRouter 当作 drop-in 替代，把 base URL 设成 https://openrouter.ai/api/v1、api key 设成你的 OpenRouter key 就行。官方在文档里对 LLM 单独留了一句说明，意思是默认建议用自家 SDK，除非使用者明确要求用 OpenAI SDK。

一个最小的直接调用长这样：

import requests, json

response = requests.post(
  url="https://openrouter.ai/api/v1/chat/completions",
  headers={
    "Authorization": "Bearer <OPENROUTER_API_KEY>",
    "Content-Type": "application/json",
  },
  data=json.dumps({
    "model": "openrouter/free",
    "messages": [{"role": "user", "content": "Hello!"}]
  })
)

Quickstart 示例里还出现过两个头：HTTP-Referer 和 X-OpenRouter-Title。官方在示例注释里明确标了 Optional，作用是让你的应用出现在 OpenRouter 的榜单上，不设并不影响调用。需要流式输出的话，请求里加 stream: true，官方说明走的是 SSE。

第四步：确认自己现在处在哪一档

调通之后别急着往下写业务，先花一次请求把账户状态摸清楚。GET https://openrouter.ai/api/v1/key 会返回这把 key 的状态，官方给出的类型定义里有几个字段特别值得看：

• limit / limit_reset / limit_remaining：这把 key 的额度上限、重置方式、剩余量，为 null 表示不限或从不重置
• usage、usage_daily、usage_weekly、usage_monthly：累计用量，以及当前 UTC 日、当前 UTC 周（官方注释写明从周一开始）、当前 UTC 月的用量。注意这里是 UTC 口径，你本地时区的「今天」和它统计的那一天不是同一段时间，跨日核对时容易对不上
• is_free_tier：官方注释是「用户此前是否付过费」。注意官方并没有说明这个字段与限速分档之间是什么关系，也没有进一步说明取值含义，别拿它当档位判据
• include_byok_in_limit：外部 BYOK 用量是否计入这把 key 的额度上限
• 响应里还有一个 rate_limit 对象，官方注释直接标了已废弃、可以安全忽略——看到它不要照着写代码

Limits 页开头那张表还给了另一条线索：额度类的限制去 GET /api/v1/key 看 limit_remaining，而速率类的限制要看错误响应上的 X-RateLimit-* 头。两类限制的检查位置不一样，别混着找。

第一次调用就失败了，按什么分诊

先记住一条容易被写错的前提。官方原文说的是，HTTP 响应状态码与 error.code 相同，成立条件是：你的原始请求非法，或者你的 key / 账户额度不足。除此之外的情况——比如模型已经开始产出内容之后才出的错——HTTP 状态是正常的，错误会出现在响应体里或者作为 SSE 数据事件抛出。所以「状态码正常就等于成功」这个判断在流式场景下不成立。

真正稳妥的分诊依据是 error_type 字段。官方说它是规范化的错误分类，在三种 API 风格下都稳定，即便原生协议的错误码信息有损。对新手第一次调用来说，最常撞上的是这几个：

• authentication：key 缺失、无效或已被吊销。先检查 Authorization 头有没有拼错、有没有漏掉 Bearer 前缀。详细排查见 OpenRouter 401 报错
• payment_required：账户或这把 key 的额度不足。这里有个坑跟免费模型直接相关——官方在 Credit limits 一节写着，如果账户余额为负，你可能会看到报错，包括调用免费模型时；把余额补回零以上就能重新使用那些模型。注意官方用的是 may，不是一定会
• rate_limit_exceeded：请求级或 token 级限流。官方要求重试前尊重 Retry-After 响应头，它给出的是应等待的秒数。OpenAI SDK、Anthropic SDK、Vercel AI SDK 和 OpenRouter SDK 都已经遵守这个头，直接用 fetch 的需要自己处理。系统性的应对策略见 OpenRouter 429 限流
• not_found：请求的资源（模型、文件等）不存在。官方对它的描述就这一句，没有列举具体诱因
• permission_denied：key 有效但缺少所需权限，或者请求被 guardrail 拦下——它不是区域限制的意思，别往那个方向猜

免费额度还没用完之前，有三件事别做

别靠多开账号或多建 key 来扩额度。 官方在 Limits 页开头的提示框里写得很清楚：额外创建账号或 API key 不会影响你的限速，因为容量是全局管控的。同一段话里给了唯一一条官方认可的分摊思路——不同模型有不同的限速，所以真的撞上瓶颈时，可以换用其他模型来分担负载。

别用脚本对免费模型猛打。 官方明确提到 Cloudflare 的 DDoS 防护会拦截显著超出合理用量的请求。按官方的分类，它属于速率限制那一类下面的一项，而不是独立的第三类；它也不在 GET /api/v1/key 的返回里体现。

别把免费档直接放进生产。 这不是我的判断，是官方 FAQ 自己写的：这些模型限速低，通常不适合生产使用。它适合的是学接口、跑 demo、做一次性的小批量实验。当你的调用量开始逼近上限、或者需要稳定的响应可用性时，该考虑的是切到付费模型，而不是继续想办法在免费档里挤。

最后：官方文档没写的部分

有两件事这份官方文档里我没有找到对应说明，这里照实说明，不做推测。

一是注册环节的具体流程，比如是否需要在创建账号阶段绑定支付方式、免费额度什么时候到账，文档里没有找到相关说明，以你在官网注册时看到的实际流程为准。

二是中国大陆网络环境下访问 OpenRouter 的情况，官方文档里同样没有说明。这一点请你按自身合规要求自行判断，本文不提供任何规避手段。

真遇到卡住的问题，官方给的入口是：技术类问题去官方 Discord 的 #help 论坛问社区，账单与账户管理类问题发邮件到 support@openrouter.ai。下一步建议先把 GET /api/v1/key 的返回打印出来存一份，它是你后续所有限额判断的基准线。