OpenRouter的API怎么调用？调用方式与免费模型用法说明

你在做接入，看中 OpenRouter 一家能调很多家的模型，甚至有一部分不花钱的位。但真动手时会卡在几个地方：请求该发到哪、模型名怎么写、免费位为什么一会儿能用一会儿报错。这篇只讲调用方式本身，给你一套能照着发的请求格式、挑免费模型的判断标准，以及出错时先查哪一步。具体价格、免费额度和可用模型清单都在变，正文里不写死，指到站内对应页面去核。

你在做接入，看中 OpenRouter 一家能调很多家的模型，甚至有一部分不花钱的位。真动手时容易卡在三件事：请求该发到哪、模型名怎么写、免费位为什么一会儿能用一会儿报错。这篇只讲调用方式本身，不铺概念，给你一套照着发的请求格式、挑免费位的判断标准，以及出错时的排查顺序。

先说清楚一点：具体价格、免费额度、可用模型清单都在变，正文里不写死任何数字，需要核对时到站内对应页面看当天状态。你要拿走的是方法，不是某一刻的数值。

一次请求长什么样：入口、鉴权与两套协议

统一入口加一个标准 Bearer 鉴权头，key 从账号后台拿。请求体结构和 OpenAI 那套兼容，所以现成的 SDK 大多改 base 地址就能用。模型名统一写成「厂商/模型」的两段式，不带斜杠的名字不用。有些名字后面会带日期或变体后缀，含义到站内 /models 与 /ai-dict 对照，别凭记忆拼。

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"厂商/模型","messages":[{"role":"user","content":"你好"}]}'

免费模型怎么挑、怎么用才不折腾

免费位的判断标准不是看名字里带没带 free，而是看当前页面标的计价方式和限流口径。免费位通常有两类限制叠加：每分钟请求数和每天额度上限，两类都要看，只盯一个很容易误判。当天的状态到站内 /openrouter 榜单与 /models 核对。

• 先定任务类型：摘要、分类、简单对话这类容错高的，才适合先压免费位
• 再在同一档免费位里挑上下文够用的，不要一上来看名字长就选
• 把每分钟请求数和每天额度上限都记下来，换算成你自己的调用节奏
• 提前准备一个付费位的兜底模型名，免费位限流时能立刻切
• 别把免费位当唯一通道，生产任务从一开始就想好切换路径

什么情况下不适用：长期跑的生产任务、要求稳定首字延迟的场景、需要特定上下文长度的任务，都不建议压在免费位上。免费位的抖动是常态，把它当调试和验证通道更合适。

第一次调通的最小步骤清单

1. 备齐三样东西key、一个合法模型名、一个能打印完整响应的小脚本。先确认这三样都在，再谈接项目。
2. 发最短请求只发一条 user 消息，不加 system、不加额外参数，看能不能拿到正常返回。
3. 逐个加变量返回正常后，依次加 system 提示、加参数、加流式，每加一项都重跑一次。
4. 流式单独调先关流式确认通，再开流式看首字。出问题时能立刻判断是流式这一段还是前面的问题。
5. 留档把完整请求体、响应状态、模型名记下来。后面排查全靠这份记录。

报错先查哪一步：一个排查顺序

这套顺序的价值在于省时间：大部分报错在前两步就能定位，不用一上来就怀疑网络。错误码含义和退避写法，站内 /api-errors 与 /429-concurrency-backoff 已经讲透，这里只给顺序索引。

补一句适用边界：如果你接的是多模型路由做负载均衡，前两步的结论要放到整个路由池里看，单看某一次请求容易误判成上游全局问题。