openrouter免费模型怎么调用

你在 OpenRouter 上看到一堆标着免费额度的模型，接上去却发现有的限速、有的偶尔报错、有的跑一半断流。这篇不教你怎么注册账号，而是讲怎么筛、怎么调、怎么在跑批和生产里不被打断：请求怎么写、并发卡在哪、失败怎么退、日志记什么。

你在 OpenRouter 上看到一堆标着免费额度的模型，接上去却发现有的限速、有的偶尔报错、有的跑一半断流。这篇不教注册账号，只讲怎么筛、怎么调、怎么在跑批和生产里不被打断。核心思路是：把免费位当成一条会波动的通道来用，而不是当成一个稳定 API 来依赖。

下面按顺序讲八件事：先分清免费的口径，再用接口拉清单、定请求字段、摸清并发与上下文边界、做重试与降级、记对日志、上线前跑最小验证，最后说清什么场景不该硬撑免费位。每节都给可执行动作，不是概念科普。

先把「免费模型」的几种口径分清

OpenRouter 上说的免费，通常指带免费额度的型号。它和「完全不要钱」「用你自己的额度」是三件不同的事。混在一起判断，就会出现「明明挑的免费入口，却在付费」的怪事。判断一个模型能不能长期用，先看它有没有标注免费位、免费额度上限是多少、额度是按天重置还是按周期重置。

• 看标注: 模型页上是否明确标了免费位、免费额度上限、重置节奏，三项缺一项就要留个心眼
• 看入口: 同一个模型往往有付费版和免费版两个入口，模型 ID 差一点就换了一条计费通道，复制 ID 时别手打
• 看额度口径: 有的按天重置，有的按账号累计，跑批前先确认自己的量级落在哪一档
• 看变动: 名单和额度随时在改，先到 /openrouter 核对当前免费位与调用量口径，别照抄旧文章里的清单

什么情况下这条判断不适用

如果你用的是团队共用账号，额度状态可能已经被别人占用，单看模型页的标注不足以判断当下能不能调。这种情况要先去后台看账号维度的剩余量，或者干脆给关键任务准备一个独立账号或独立 Key，避免互相挤占。团队账号还容易出现「你以为在跑免费位，其实同事切了付费入口」的混乱。

用接口自己拉一遍可用模型清单，别手抄

模型清单是动态的，写死在代码里的模型名过一阵就会失效。正确做法是调用前先用清单接口拿到模型 ID、上下文长度、支持的参数，再做筛选。筛选结果落到本地配置或数据库里，隔一段时间重新拉一次，别每次请求都去拉。这样代码里引用的是自己维护的一份稳定清单，上游变动时只改一处。

1. 拉清单调用模型清单接口拿到全量模型信息，存成 JSON 落盘，别直接在业务请求里做这一步
2. 按三档过滤第一档看上下文长度够不够你的最长输入；第二档看支不支持流式；第三档看有没有工具调用等结构化字段。三档都不满足的直接丢掉
3. 交叉免费标记把过滤后的结果和免费位信息对一遍，只保留确定走免费通道的 ID，写成一份候选配置
4. 定时刷新用定时任务或启动时刷新一次候选配置，并在日志里记录本次清单的抓取时间，方便排查失效

筛选时不要只看模型名是不是眼熟，要看字段。上下文长度、是否支持流式、是否支持工具调用，这三项决定你能不能把它用在自己的场景里，比名字重要得多。清单里如果出现同一模型多个 ID，优先选标注明确的那条。

一次请求该带哪些字段

OpenAI 兼容风格是主流写法：messages 数组、model 字段，加上可选的 temperature 和 max_tokens。想固定用免费位，就在模型 ID 上带对应的后缀或标记，具体的后缀写法到 /official-api 核对当时的口径，别凭记忆写。流式和非流式的差别集中在 stream 开关上，其余结构基本一致。

{
  "model": "按站内核对后的模型ID",
  "messages": [{"role": "user", "content": "你好"}],
  "stream": false,
  "max_tokens": 512,
  "temperature": 0.7
}

另外建议在请求头里留一个可识别的标识，比如带自己项目名的 User-Agent 或自定义头。出问题的时候，后台能对号入座，排查效率差很多。别只靠请求体区分来源，尤其是同一个 Key 跑多个服务的时候。

免费额度的边界在哪：并发、频率、上下文

免费位常见的限制有两类：单位时间的请求数，以及每天的总量。两者都要在代码里留余量。并发别一上来就拉满，先用小并发跑通，再按报错节奏往上加。免费位的上下文上限往往比付费位低，超长输入会直接返回错误，拿付费位的预期去套很容易踩坑。

频率限制

单位时间内的请求次数上限，超了会报限速类错误，代码里要能识别并退避

每日总量

一天能用多少额度，跑批前先估算总量，别跑到一半断掉

上下文上限

免费位通常比付费位低，超长输入直接失败，长文任务要先量长度

并发余量

日常并发压在限制以下一档，别贴着上限跑，给突发留空间

出现限速类错误时，先降并发、再退避，不要立刻换 Key 硬顶。换 Key 能绕过的只是账号维度的限制，如果是模型维度的全局限速，换了也白搭，还会把多个 Key 一起打爆。降并发加退避是唯一稳妥的处理顺序。

报错怎么分类、怎么退

报错先分类，再决定动不动手。参数错、模型名错这类，重试多少次都不会好，得回去改代码或改配置。限速、临时不可用这类，等等就好，值得重试。鉴权类失败要先确认 Key 和额度状态，盲目重试只会刷次数，还会把自己搞进更严的限制里。

给每个模型准备一个备选模型，主线失败时自动切到备选，切换动作要记进日志。重试用指数退避加重试上限，次数到顶就当作失败往下走，别无限循环。备选模型也要提前验证能通，不然切过去一样失败，只是把错误换了张脸。

要记哪几个字段，才方便复盘

日志不是记越多越好，是记对。至少记模型名、请求时间、耗时、是否流式、结束原因、是否重试过。出错时把返回体的错误码和错误消息原文留下，别只记一句「调不通」。这两样东西是后面判断「这个免费位值不值得留」的唯一依据，缺了就只剩感觉。

• 必记: 模型名、请求时间、耗时、是否流式、结束原因、重试次数
• 出错必记: 错误码与错误消息原文，别截断成一句概括
• 统计口径: 按天统计各模型失败率与平均耗时，用来决定留不留
• 安全项: 日志里不要落完整 Key，敏感字段脱敏后再存

统计每天各模型的失败率和平均耗时，过一段时间你会发现有的免费位稳定、有的就是偶尔抽风。拿数据决定去留，比凭印象换模型靠谱得多。对失败率高的那条，优先减配到非关键任务，或者直接下线。

上线前跑一遍最小验证清单

上线前别直接上量，先跑一遍最小验证。先用一个最短提示词打通非流式，再打通流式，两步分开验，这样出问题时能立刻定位是哪种模式的问题。并发从 1 开始，逐步加到日常用量，记录每一档的错误率，找到能稳住的那一档再定生产参数。

1. 非流式打通用最短提示词发一次非流式请求，确认返回结构和结束原因正常
2. 流式打通再发一次流式请求，确认分片能正常收到、能正常结束
3. 并发阶梯从并发 1 开始逐档加，每档跑一段，记录错误率，找到稳定档位
4. 超时拆分连接超时和读取超时分开设置，别用一个很长的整体超时兜底
5. 换模型复验换到备选模型后重跑一遍上述步骤，验证方式可以参照 /relay-connectivity-verification 的思路

超时设置是最容易被忽略的一项。用一个很长的整体超时兜底，表面看很省事，实际会把连接失败和读取卡住混在一起，排查时根本分不清是哪一段出问题。拆开之后，日志里也能直接看出是哪类超时。

什么情况下别硬撑免费位

免费位适合省钱优先、能接受偶尔失败的任务。反过来，对延迟敏感、对稳定性有承诺的线上功能，不适合把免费位当唯一通道。跑批量大、要求整批完成的任务，免费位的每日额度通常是硬瓶颈，跑到一半断掉会比一开始就用付费位更麻烦。

• 延迟敏感型: 用户可感知的实时交互，免费位的抖动会直接变成体验问题
• 整批完成型: 大批量任务卡在每日额度上，断在半路最难收拾
• 结构化输出型: 需要工具调用或严格结构化输出时，先确认目标免费模型是不是真支持，不然白搭
• 可接受失败型: 省钱优先又能容忍偶尔失败的任务，才适合把免费位放主线、付费位当兜底

免费位不是免费 API，是一条会波动的通道：把它放在主线、付费位当兜底，而不是反过来。