OpenRouter 快速上手指南：API 调用、token 计费与常见报错排查

OpenRouter 已经成为很多 AI 应用开发者绕不开的模型网关。过去两年它的周 token 量从早期量级增长到今天的数千倍这个数字背后不只是营销热度而是真实开发流程的变化越来越多团队在同一个 API 网关下切换不同大模型比较效果、控制成本、统一结算。下面按从入门到排错的顺序把 OpenRouter 是什么、token 怎么计费、如何注册并获取 API Key、怎么写第一个可运行的调用代码以及登录时报 token exchange failed、403 forbidden country 这类问题时该按什么顺序排查完整过一遍。1. 先理解 OpenRouter 为什么快速成为开发者的默认入口1.1 一个 API Key 调用多家模型解决的是真实碎片化问题实际开发中对比不同模型是常态。一个功能可能需要某个模型做总结另一个模型写文案第三个模型做结构化信息抽取。如果没有统一网关团队需要注册多个平台、分别申请 API Key、适配不同 SDK、分别处理账单。OpenRouter 做的事情是把这些统一到一个入口客户端只对接 OpenRouter 的接口OpenRouter 再路由到上游模型服务商。OpenRouter 的接口和 OpenAI 兼容这意味着熟悉 OpenAI API 的开发者几乎不需要重新学习。发起请求时只需要把model参数换成目标模型的 ID其他消息结构、鉴权方式、返回字段基本一致。这种低迁移成本是它能被快速接入的重要原因。1.2 周 token 量两年激增约 9000 倍说明它开始成为生产依赖公开数据里常被提到的信息是OpenRouter 的周 token 量在两年内激增约 9000 倍。这里的 token 不是某一个模型的输出量而是平台侧所有请求的输入输出总和。这个增长背后有两个信号。第一大量个人开发者和创业团队在真实业务里接入了它。第二很多 AI 应用的上游已经不是单一模型而是通过网关做多模型路由。对开发者来说网关的价值在于降低模型切换成本而不是绑定某一家模型厂商。但把这个数字作为选型理由时要冷静。平台整体用量高不代表每个模型稳定性都好。上游模型可能限流、下架、调价OpenRouter 自身也可能出现故障。对于团队项目网关是强需求但不能把网关当成保证可用性的唯一手段。1.3 OpenRouter 的技术边界要理解 OpenRouter关键是把它当成“中间层”或“聚合网关”而不是模型厂商。它不训练模型底层能力来自多家模型服务商。因此需要注意几个边界模型可用性受上游影响上游故障时 OpenRouter 也会报错计费受上游价格影响不同模型单位 token 价格差异很大数据请求会经过 OpenRouter 再转发对数据隐私要求高的项目要提前评估服务可用区域由平台判断不在支持范围内时会看到 403 错误。这些边界决定了后续所有使用方式。后面讲到的注册、计费、报错排查很多问题都来自这些边界。2. 注册账号、区分 credits 和 token、创建 API Key先说明操作目标跑通账号拿到一个可用的 API Key。这一步需要区分三个概念账号、API Key、credits。2.1 注册与登录打开 OpenRouter 官网使用支持的第三方账号登录。登录后进入后台一般能看到余额、Key 管理、活动记录等入口。注册本身不复杂但很多人卡在登录报错上。常见提示是sign-in could not be completed token exchange failed token endpoint returned status 403 forbidden: country, region, or territory not supported这个错误表示 OAuth 过程中的 token 交换失败并且平台根据当前出口 IP 判断所在地区不受支持。这不是账号或密码问题而是服务可用区域限制。遇到这个报错时不要反复重试先确认当前网络出口所在地区是否在平台支持范围内。如果确实不在范围内合规的做法是使用受支持地区可用的网络环境或者选择其他满足业务需要的服务。不要尝试使用任何绕过限制的工具或手段。注意如果错误信息里明确包含 country, region, or territory not supported问题指向的是当前网络出口所在地区而不是账号或 Key。换浏览器、重新登录通常无效。2.2 credits 和 token 的区别热词里有人问 credits 和 token 有什么区别这是新手最容易混淆的概念。简单说token 是模型文本处理的单位。英文一般是子词中文可能一个字对应一到多个 token。每次请求的输入和输出都会统计成 token模型成本按 token 计算。credits 是 OpenRouter 账户里的余额相当于充值额度。每次调用模型平台根据 token 用量和模型单价从 credits 中扣除对应费用。用表格说明概念含义作用token文本切分单位输入输出都计决定模型处理成本和上下文长度credits账户余额预付费模式用来支付所有模型的调用费用API Key调用凭证类似密钥标识调用者身份扣费绑定到账户2.3 创建 API Key在 Keys 页面可以创建新的密钥。建议创建带权限的 Key而不是使用全功能主 Key。例如某些场景只需要读取模型列表不需要修改操作就创建只读 Key。创建完成后不要把 Key 写进前端页面或提交到 Git 仓库。本地开发时保存在环境变量里例如export OPENROUTER_API_KEYsk-or-...需要注意OpenRouter 的 Key 具体前缀以平台实际返回为准。在后端代码里所有请求都要使用这个 Key 作为鉴权凭据。3. 最小可运行案例从 curl 到 Python 再到接入终端客户端这部分目标是发出第一个真实请求并拿到模型返回。建议先走 curl因为 curl 可以排除编程语言和 SDK 层面的干扰直接验证网络、Key、模型 ID 三个关键变量是否正常。3.1 确认模型 ID在官方 Models 页面搜索模型点进去可以看到完整的 model 参数值。不同模型 ID 命名规则通常是“组织名/模型名”例如anthropic/claude-3.5-sonnet openai/gpt-4o mistralai/mistral-small这些 ID 会随平台上架和下架调整写代码前要在官方模型列表复制最新 ID不要凭记忆拼。3.2 curl 验证请求链路在终端执行curl https://openrouter.ai/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $OPENROUTER_API_KEY \ -d { model: openai/gpt-4o, messages: [ {role: user, content: 用一句话解释什么是 token} ] }正常返回是 JSON重点关注以下字段id请求 ID排查问题时需要用到model实际命中的模型choices[0].message.content模型输出文本usage.prompt_tokens输入 token 数usage.completion_tokens输出 token 数usage.total_tokens总 token 数。如果返回 401先检查 Key 是否被正确设置返回 404 或 model not found检查模型 ID返回 403检查地区限制或账号权限返回 429说明限流或余额不足。3.3 使用 Python 调用项目使用 Python 时可以直接使用 openai 官方 SDK把base_url指向 OpenRouterfrom openai import OpenAI client OpenAI( base_urlhttps://openrouter.ai/api/v1, api_keysk-or-..., ) response client.chat.completions.create( modelopenai/gpt-4o, messages[ {role: user, content: 用一句话解释什么是 token} ], ) print(response.choices[0].message.content) print(response.usage.total_tokens)使用 SDK 时要注意两点第一OpenRouter 是 OpenAI 兼容接口但某些高级参数不一定在目标上游模型上生效第二即使 SDK 封装好了请求仍然要读取usage字段否则成本不可观测。也可以使用 requests 写最小请求import os import requests key os.environ[OPENROUTER_API_KEY] response requests.post( https://openrouter.ai/api/v1/chat/completions, headers{ Authorization: fBearer {key}, Content-Type: application/json, }, json{ model: openai/gpt-4o, messages: [{role: user, content: 用一句话解释什么是 token}], }, timeout30, ) print(response.status_code) print(response.json())requests 版本适合排查网络超时、参数错误和完整响应体因为你能直接看到原始返回内容。3.4 在 Claude Code 中接入 OpenRouter很多开发者在终端工具里想切换不同模型会尝试把 Claude Code 指向 OpenRouter。Claude Code 支持通过环境变量改变 API 地址和认证方式常用配置如下export ANTHROPIC_BASE_URLhttps://openrouter.ai/api/v1 export ANTHROPIC_AUTH_TOKENsk-or-... export ANTHROPIC_MODELanthropic/claude-3.5-sonnet需要说明的是Claude Code 这类终端工具对响应格式、工具调用协议、模型能力有更严格的要求不是所有 OpenRouter 上的模型都能完全兼容。如果接入后出现协议错误或工具调用失败优先确认所使用的模型是否支持 Anthropic 兼容格式并参考工具官方文档核对环境变量名。注意终端类工具对接 OpenRouter 时工具对模型响应格式有额外要求。先用 curl 验证同一个模型能返回正常内容再接入工具能省去大量排查时间。4. token 计费与用量控制token 是文章标题里的核心关键词也是新手最关心的问题。下面拆开讲。4.1 token 怎样被统计模型处理文本时不是按字符数计费而是按 token 数。英文一个单词大约产生 1 到 3 个 token中文一个字可能产生 1 到 2 个 token。不同模型的 tokenizer 不同同一句话在不同模型下统计出的 token 数也会有差异。一个请求包含两类 tokenprompt_tokens输入部分包括 system 提示、历史对话、用户输入completion_tokens模型生成的输出部分。很多在线工具可以帮助估算 token 数但最准确的方式仍然是读取响应里的usage字段。4.2 单次请求的成本构成每次请求的成本大致是成本 prompt_tokens × 输入单价 completion_tokens × 输出单价不同模型输入和输出单价不同通常输出比输入更贵。OpenRouter 官方价格页展示的通常是每百万 token 的价格。下面用表格演示计算思路数值仅为示例实际以平台定价页为准模型输入单价每百万 token输出单价每百万 token一次 1000 输入 500 输出的成本示例模型 A515(1000 * 5 500 * 15) / 1,000,000 0.0125 美元示例模型 B0.51.5(1000 * 0.5 500 * 1.5) / 1,000,000 0.00125 美元实际项目中成本计算还要考虑多轮对话。对话轮数越多历史消息作为输入被重复计算的次数越多。因此长对话场景下输入 token 往往占据大部分成本优化方向是控制上下文长度。4.3 如何控制成本控制成本不是等到月底看账单而是要在代码里记录每一次请求的消耗。比较实用的方式通过 Activity 页面查看每日、每模型的消耗量设置账户余额上限避免余额意外耗尽在请求日志里记录 request_id、model、prompt_tokens、completion_tokens对超长上下文做裁剪、摘要或截断对高价模型设置单独调用通道避免所有业务都使用最贵模型不要把 Key 放在公网可访问的页面里防止被盗刷。用量控制不是上线后才做的事。开发阶段就应在日志里带上 token 消耗和估算成本这样异常发生时可以直接定位到具体请求。5. 常见报错排查链路下面把搜索热词里的高频报错整理成一条排查路径。核心思路是先判断是登录阶段、API 调用阶段还是网络出口阶段的问题。5.1 登录阶段sign-in could not be completed token exchange failed现象是点击第三方登录后页面提示以下内容之一sign-in could not be completed token exchange failed token endpoint returned status 403 forbidden: country, region, or territory not supported或者login server error: token exchange failed: error sending request这是 OAuth 登录流程里的 token 交换失败。常见原因有三类原因判断方式处理方式地区限制错误里包含 country, region, or territory not supported确认当前出口 IP 所在地区是否受支持网络不稳定错误里包含 error sending request等待后重试并检查网络连通性浏览器缓存或扩展干扰无痕窗口下可以登录使用无痕窗口清理 Cookie 或更换浏览器不要一上来就反复点登录按钮。如果错误明确提到地区限制重复点击不会解决问题。对于地区限制只能使用受支持地区的合规网络环境或者在服务条款范围内选择其他可用平台。5.2 API 调用阶段403 forbidden如果登录正常但调用 API 时返回{ error: { message: 403 forbidden: country, region, or territory not supported, type: forbidden } }这个错误与 API Key 本身无关而是平台根据请求出口 IP 判断当前地区不可用。排查顺序确认出口 IP 所在地区确认账号是否有该模型的访问权限如果是地区限制按照当时可用的合规方式访问或选择其他服务。5.3 API 调用阶段401 invalid tokenunexpected status 401 unauthorized: invalid token这个返回表示请求携带的密钥无效。检查点环境变量是否已加载Key 是否有多余空格、换行、引号Key 是否被撤销或过期是否在请求头里写成了Authorization: Token而不是Bearer。推荐在本地直接检查环境变量是否为空echo ${#OPENROUTER_API_KEY}这个命令输出 Key 长度。如果输出为 0说明环境变量没有加载。5.4 模型层找不到模型很多人会在后台配好 Key 后发现某个模型找不到搜索某个特定模型 ID 得到空结果或 404。常见原因模型 ID 拼写错误模型已经下架或改名模型未对当前账号开放模型只在特定区域或特定套餐下可用。最直接的核验方式是列出当前可用的模型列表curl https://openrouter.ai/api/v1/models \ -H Authorization: Bearer $OPENROUTER_API_KEY返回结果里包含可用模型 ID用这个结果核对目标模型是否存在再去判断是下架还是权限问题。5.5 请求层429 或 context length exceeded429 表示限流或余额不足需要检查 Activity 页面的消费记录。如果账号余额正常则说明触发了速率限制应降低请求频率并增加退避重试。context length exceeded表示输入 token 超过模型上下文窗口。解决方式有两种减少历史消息或者改用上下文窗口更大的模型。6. 学习环境与生产环境的使用差异6.1 学习环境怎么快速跑通个人验证时目标是尽快看到第一个返回。建议步骤注册账号充入少量 credits在 Keys 页面创建一个 Key用 curl 调用最简单的 chat/completions把请求封装成 Python 函数在代码里打印 usage。这个阶段不需要过度设计。关键是验证调用链路确认模型能正常返回内容。6.2 生产环境还需要补齐的环节生产环境不能只依赖一个请求函数。至少要考虑关注点学习环境生产环境Key 管理本地环境变量密钥管理服务按服务拆分 Key日志不记录记录 request_id、model、usage、耗时超时默认设置合理 timeout避免无限等待重试手动对 5xx 和网络错误做退避重试限流无应用层限流避免集中打到上游成本忽略每日额度、告警、用量分析隐私随意发送评估数据经过网关的合规性生产环境还建议对下游返回做校验防止上游返回异常结构时直接透传给业务方。7. 最佳实践、常见坑和检查清单7.1 至少六个常见坑第一个坑API Key 泄露。有人把 Key 写在 GitHub 仓库、前端 JS 或公共代码片段里。Key 泄露意味着 credits 可能被盗刷。解决方式是创建独立 Key、配置权限范围、设置异常告警发现异常立即撤销并重建。第二个坑忽略 usage 和成本。只打印模型输出不记录 token 消耗等到月底额度耗尽才发现。解决方式是在每次请求后记录 usage 字段并按业务维度聚合。第三个坑请求超长导致 context length exceeded。多轮对话里把所有历史一次性塞入导致输入 token 超限。解决方式是做上下文裁剪、摘要或使用支持更长上下文的模型。第四个坑不处理上游限流。OpenRouter 是网关上游模型可能返回 429 或 5xx。调用方需要做指数退避重试否则高峰期体验很差。第五个坑把网关返回结构散落到业务代码里。OpenRouter 只是一个可替换组件业务代码应该通过一层薄薄的模型调用抽象访问它而不是在几十个页面里直接写client.chat.completions.create。这样平台变更或切换其他网关时改动范围可控。第六个坑登录报错后反复点提交。OAuth token exchange failed 通常不是点击次数能解决的。先看错误信息里有没有 403 country、error sending request 等关键字再决定是换网络、清缓存还是等待服务恢复。7.2 可复用检查清单发布前可以用下面这张清单自检检查项是否完成说明API Key 已放到环境变量或密钥服务是/否未出现在代码仓库请求代码能读取 usage 并记录日志是/否确保成本可观测超时和重试已配置是/否避免无限等待限流和异常分支有兜底是/否返回给用户的不是上游原始错误已核对目标模型 ID是/否以官方 Models 页面为准已确认地区限制是/否生产服务器出口 IP 判断已设置预算或用量告警是/否防止盗刷和超支注意发布前的成本检查不能只看功能是否正常还要确认使用量、错误率和费用都有日志可查。7.3 扩展方向掌握基础调用后可以继续做三件事多模型路由根据任务类型、成本和效果把请求分发到不同模型提示词优化通过压缩历史、精简 system 提示降低输入 token效果评测集建立一组固定测试用例在多个模型下横向对比输出质量。这三件事都依赖同一个基础能力准确解析请求响应里的 usage、model 和 cost。建议在项目早期就封装一个统一的模型调用模块把日志、成本、重试都放在这个模块里而不是让每个业务页面直接调 SDK。从长期维护角度看OpenRouter 是一个值得放在工具箱里的网关但也要把服务边界、可用区域、隐私风险和成本控制想清楚。对个人开发者来说先用最小案例跑通链路再逐步加上预算、日志和重试比一开始就追求复杂架构更实际。