过去几年大模型 API 的调用量增长有多夸张OpenRouter 近期公开的数据给了一个很直观的参考周 token 量在两年时间激增约 9000 倍。很多开发者第一次看到这个数字时会以为统计口径有误但它恰恰反映了最近两年 AI 应用从“尝鲜”走向“规模化”的真实变化。token 是模型计费的基本单位周 token 量激增说明真实业务请求在快速涌入而不再只是开发者测试时的零星调用。这篇文章不打算只停留在数据解读上。我会围绕 OpenRouter 是什么、token 与 Credits 怎么区分、如何快速接入 API、如何把模型接到 Claude Code 这类 AI 工具以及 token 相关高报错如何排查这几个维度展开。文章里包含可复制的 curl、Python 示例和工程配置适合刚接触 OpenRouter 的开发者也适合已经在项目里接入了多家模型、正在做成本控制和稳定性治理的同学。1. 9000 倍增长的背后OpenRouter 为什么突然爆发1.1 9000 倍是什么概念假如第一年每周 token 消耗量是 1那么两年后同一周消耗量就是 9000。这个增长不是线性放大而是指数级扩散。它意味着大量 AI 应用从“偶尔调用一次模型”变成了“每条消息、每个用户、每小时都持续触发调用”。推动这个趋势的三个关键因素很明显模型数量爆发。GPT、Claude、Gemini、Llama、Qwen 等模型不断迭代开发者希望用同一个 API 访问不同模型OpenRouter 这类网关正好解决了问题。多模型组合成为常态。复杂任务用大模型简单任务用轻量模型规划用一类模型结构化抽取用另一类模型。AI 编程、Agent、自动化脚本等高频场景全面走向线上。这些场景天然按 token 计费对网关的稳定性、兼容性和成本可见性都有很高要求。1.2 为什么是 OpenRouter市面上有不少模型聚合服务OpenRouter 的特点是“接口兼容 OpenAI 风格 模型路由 统一计费”。对普通开发者来说学习成本很低——如果你已经会调 OpenAI 的 Chat Completions那么把 base_url 指向 OpenRouter 就能立刻使用其他模型。这个低迁移成本是它被广泛接受的重要原因。另一个原因是它的透明性。模型列表页会展示每个模型的价格、上下文长度、可用性和延迟信息。你在选型时不用挨个去各家官网查价格一个页面基本就能完成对比。1.3 本文要解决什么问题围绕 OpenRouter 和 token我整理了四个方面核心概念token、Credits、模型 ID、API Key。接入实战curl、Python SDK、工具配置。错误排查token exchange failed、401 invalid token、模型不存在。成本控制怎么减少 token 消耗怎么避免 credits 被快速耗尽。2. OpenRouter 到底是什么一个“模型网关”而不是模型厂商2.1 最直白的理解OpenRouter 本身不训练模型不拥有底层模型权重。它做的是“路由”和“封装”。你可以把它理解成手机里的聚合打车平台出租车、专车、顺风车来自不同服务商但你在同一个 App 里下单、支付、查看行程。OpenRouter 也类似它把多个模型厂商的接口统一成一套 API你只需要持有一个 OpenRouter API Key就能调用平台上提供的各种模型。从协议角度看OpenRouter 主要提供与 OpenAI 兼容的接口格式。你在代码里使用 OpenAI 的 SDK把 base_url 改为https://openrouter.ai/api/v1再把 api_key 换成 OpenRouter 的 Key就可以开始调用。2.2 核心能力拆解OpenRouter 有五个值得关注的工程能力统一接口 上游模型服务商的 API 格式可能各不相同OpenRouter 在下游把它们转换成统一的请求和响应结构开发者不需要为每个模型写一套适配代码。多模型路由与回退 你可以在请求参数中配置models列表或 fallback 列表。当第一个模型不可用、超时或触发限流时OpenRouter 可以自动尝试下一个模型。这对生产环境的稳定性很重要。统一计费 OpenRouter 用 Credits 作为账户余额按模型的实际 token 消耗统一扣费。开发者可以从后台查看每次请求的输入 token、输出 token 和费用明细。流式输出 聊天、代码补全、Agent 工具调用等场景默认需要流式输出OpenRouter 支持 SSE 流式返回能明显降低首字延迟。模型状态透明 模型列表页会展示各模型是否可用、平均延迟、价格和上下文长度。你可以根据状态选择模型而不是把某个模型锁死到代码里。2.3 适合谁用个人开发者想快速体验多家模型不想申请和维护一堆官方的 Key。AI 应用团队需要按任务分配模型并统一管理用量和成本。做模型评测的工程师需要在同一套请求逻辑下对比多个模型效果。AI 工具用户想通过 OpenRouter 把 Claude Code、Cursor 等工具接到自己想要的模型上。如果你的场景只使用单一模型的官方 API直接使用官方通道会更简洁如果需要在多个模型之间切换、自动回退、统一计量成本那么 OpenRouter 这类网关价值会非常明显。3. Token 与 CreditsOpenRouter 里的两套核心单位3.1 Token 到底是什么大语言模型并不是严格按“字”处理文本而是按 token 处理。token 可以理解成模型对文本的最小切分单元。不同语言的 token 切分效率不一样英文里一个常见的单词可能是 1 个 token部分长单词会被拆成多个 token。中文里一个汉字大约对应 1~2 个 token。所以同样的一段文本中文的 token 数量通常会比英文多。这也是为什么中文应用的 token 成本往往比想象中更高。token 对开发者有三个直接影响计费模型按 input token 和 output token 分开计费。上下文窗口模型能接收的最大 token 数是有限制的。性能长文本会显著增加首字延迟和整体调用耗时。3.2 Credits 和 Token 的关系OpenRouter 账户里有两个容易混淆的概念Credits你充值的余额以美元计价。Token模型调用时的计量单位。一次请求发生之后OpenRouter 会计算这次请求消耗了多少 input token 和 output token再根据模型单价折算成美元从 Credits 中扣除。模型价格通常写作“每百万 token 多少美元”。比如一个模型输入价格是 0.15 美元/M tokens输出价格是 0.60 美元/M tokens。如果一次请求消耗了 1000 个输入 token 和 500 个输出 token费用约等于(1000 / 1_000_000) * 0.15 (500 / 1_000_000) * 0.60 0.00015 0.0003 0.00045 美元虽然单次费用很低但一旦请求量级变大成本就会迅速累积。实际业务中应该单独统计 tok en 消耗而不是只看某一次调用的费用。3.3 注册时有没有免费额度很多文章会提到“新用户注册送多少”但赠送额度会随平台活动和注册地区变化。更稳妥的做法是注册后打开账户后台看 Credits 页面以页面显示的实际可用额度为准。需要注意API Key 本身的创建是免费的免费与否的关键在于你调用哪些模型。OpenRouter 上有一部分低价甚至零费用模型适合联调和做原型验证但生产环境不要依赖免费模型因为它们可能没有稳定的可用性承诺。3.4 充值与支付OpenRouter 的充值入口在账户后台的 Credits 页面。支持的具体支付渠道会随着账号所属地区、币种和平台策略变化不同人看到的支付方式可能不完全一样。如果你在页面里没有看到期望的支付渠道不要轻信第三方“代充”服务。正确的做法是先查阅官方说明确认你的账户当前支持哪些方式。支付涉及真金白银和账号安全尽量走官方页面避免账号风险。4. OpenRouter 接入实战从 API Key 到第一个对话请求4.1 注册并获取 API Key第一步是登录 OpenRouter 官网选择支持的登录方式完成注册。第二步是进入账户后台的 API Keys 页面创建一个新的 Key。建议给 Key 设置一个能明确用途的名称比如local-dev、prod-agent方便后续管理。第三步是立即复制并保存 Key。很多平台在 Key 创建页面刷新之后就不会再完整展示忘记保存只能重新生成。API Key 使用时有几个基本安全规范不要提交到 Git 仓库。不要写进前端页面。不要在日志中打印完整 Key。优先通过环境变量或密钥管理服务注入。4.2 用 curl 验证网络连通性拿到 Key 后先用一个最简接口确认网络和 Key 是否正常。查询模型列表curl https://openrouter.ai/api/v1/models \ -H Authorization: Bearer $OPENROUTER_API_KEY如果返回 JSON 且包含models数组说明网络与 Key 基本正常。这个接口也是一个非常有用的排查工具后面“找不到模型”的问题会用到它。接着发送一个最简单的对话请求curl https://openrouter.ai/api/v1/chat/completions \ -H Authorization: Bearer $OPENROUTER_API_KEY \ -H Content-Type: application/json \ -d { model: openai/gpt-4o-mini, messages: [ {role: user, content: 用一句话说明 OpenRouter 是什么} ] }预期响应中choices[0].message.content是模型返回的文本usage字段会给出prompt_tokens、completion_tokens和total_tokens。这个usage就是后续统计成本的关键数据。4.3 使用 Python 调用OpenRouter 与 OpenAI SDK 兼容所以用 Python 调用非常简洁。# 文件路径openrouter_demo.py import os from openai import OpenAI client OpenAI( api_keyos.getenv(OPENROUTER_API_KEY), base_urlhttps://openrouter.ai/api/v1, ) response client.chat.completions.create( modelopenai/gpt-4o-mini, messages[ {role: system, content: 你是一个简洁的技术助手。}, {role: user, content: 请介绍 token 和 Credits 的区别。}, ], ) print(response.choices[0].message.content) print(response.usage)运行前安装依赖并配置环境变量pip install openai export OPENROUTER_API_KEYsk-or-v1-你的key python openrouter_demo.py这里有几个需要注意的点model字段必须填 OpenRouter 模型列表里的完整模型 ID。不同模型对参数的支持程度不同。OpenAI 风格参数并不保证所有模型都完全支持。联调阶段务必打印response.usage方便核对实际 token 消耗。4.4 使用流式输出对话和 Agent 场景更适合使用流式输出避免用户等待完整回复结束。# 文件路径openrouter_stream_demo.py import os from openai import OpenAI client OpenAI( api_keyos.getenv(OPENROUTER_API_KEY), base_urlhttps://openrouter.ai/api/v1, ) stream client.chat.completions.create( modelopenai/gpt-4o-mini, messages[ {role: user, content: 写一个 100 字的 OpenRouter 介绍}, ], streamTrue, ) for chunk in stream: delta chunk.choices[0].delta if delta and delta.content: print(delta.content, end, flushTrue)streamTrue让接口以 SSE 方式返回内容。第一个 token 到达后就能开始渲染用户体感会明显更好。需要注意的是流式响应的usage字段不一定在每个 chunk 里都出现部分实现会在最后一个 chunk 或该处额外返回具体以响应结构为准。4.5 多模型配置管理正式项目里不建议把模型 ID 硬编码在业务代码里。可以把模型配置拆到一个 YAML 或 properties 文件中。# 文件路径config/models.yaml default_model: openai/gpt-4o-mini fallback_models: - google/gemini-flash-1.5 - meta-llama/llama-3.3-70b-instruct max_retries: 2代码读取配置后按顺序尝试请求。主模型失败时切换 fallback 模型。这样做的好处是当你需要更换主模型时只需要修改配置不需要发布新代码。5. 把 OpenRouter 接到 Claude Code 等 AI 工具5.1 为什么要把工具接到 OpenRouter很多开发者喜欢用 Claude Code 这类 AI 编程工具但并不是每个人都有官方模型的稳定额度。也有人希望在同一工具内体验开源模型或非官方模型。这时把工具的自定义 API 地址指向 OpenRouter 就成了常见选择。接入的难点不在于找到“一个 Key”而在于协议和模型 ID 是否匹配。5.2 通用配置思路针对 Claude Code 这类工具一般情况下可以通过环境变量控制 API 地址和认证信息。配置思路如下export ANTHROPIC_BASE_URLhttps://openrouter.ai/api/v1 export ANTHROPIC_AUTH_TOKENsk-or-v1-你的openrouter_key export ANTHROPIC_MODELanthropic/claude-3.5-sonnet然后启动 Claude Code 命令。这里需要明确一点OpenRouter 的接口主要是 OpenAI 风格Claude Code 原生使用的是 Anthropic 风格。两者能否直接对接取决于当前版本的 Claude Code 是否支持自定义 base URL 和协议转换。如果工具内部只实现了 Anthropic 协议而你直接指向一个 OpenAI 风格 endpoint就可能出现登录失败或者 token exchange failed。遇到这类问题正确的排查顺序是阅读工具官方文档关于第三方 API 的说明。确认工具期望的是 Anthropic 协议还是 OpenAI 兼容协议。如果协议不一致需要额外使用一层兼容中间件或者使用工具自带的 OpenAI 兼容配置。不要以为“只要填了 base_url 就能通”协议层不兼容是最容易被忽略的问题。5.3 找不到目标模型怎么办有朋友问过“为什么我在 OpenRouter 里配置后找不到 stealth/ox-alpha 这个模型”这类问题通常不是配置复杂而是模型 ID 不存在或已改名。排查方法很简单先查模型列表curl -s https://openrouter.ai/api/v1/models \ -H Authorization: Bearer $OPENROUTER_API_KEY \ | grep -i ox-alpha如果返回结果为空说明这个模型 ID 在当前列表中不存在。OpenRouter 的模型列表会动态变化模型可能被下架、改名或者名称不完整。不要凭记忆填模型 ID一切以/api/v1/models接口返回的值为准。6. 高频报错与排查思路6.1 登录失败token exchange failed 403一个很典型的报错是sign-in could not be completed token exchange failed: token endpoint returned status 403 forbidden: country, region, or territory not supported这个错误通常不是 API 调用失败而是登录流程中 OAuth/OIDC 的 token 交换阶段被服务端拒绝。403 和 “country, region, or territory not supported” 都说明当前请求所在的地理区域不被服务支持。排查步骤确认当前网络出口所在地区是否在平台支持列表内。如果是自建服务器上的服务检查服务器区域是否被允许。查看官方文档中关于支持区域和登录方式的说明。不要尝试绕过区域限制。这类限制通常是平台合规策略的一部分绕过既不稳定也可能带来账号和合规风险。如果业务依赖该服务应提前评估服务区域变更带来的影响并准备好备选方案。6.2 调用时报 401 Unauthorizedinvalid token另一个常见报错是unexpected status 401 unauthorized: invalid token可能的原因包括API Key 复制错误或包含多余空格。Authorization 请求头格式错误缺少Bearer前缀。API Key 被删除、重置或过期。账户状态异常例如余额不足或账号被限制。排查步骤重新从后台复制 Key检查是否前后有空格。确认请求头是Authorization: Bearer sk-or-v1-...。在 API Keys 页面确认 Key 仍然有效。检查账户 Credits 余额。使用官方文档的最小 curl 示例测试排除代码问题。6.3 找不到模型或模型不可用现象调用时提示model not found。常见原因模型 ID 拼写错误。模型已下架或改名。模型 ID 是页面展示名而不是 API 调用 ID。部分模型可能对特定地区或账户类型有限制。排查顺序访问/api/v1/models查看完整列表。在列表中搜索目标模型的准确 ID。用最简请求测试不要带额外参数。查看模型详情页是否标注了限制条件。6.4 常见报错速查表问题现象常见原因解决思路登录时 token exchange failed 403区域不支持 / OAuth 配置异常确认支持区域检查服务端出口登录时 token exchange failed error sending request网络连接失败检查网络连通性和证书配置请求返回 401 invalid tokenKey 错误或过期重新复制并检查 Authorization 头请求返回 403区域限制或权限不足查看官方区域说明确认账户权限返回 model not found模型 ID 错误通过模型列表接口查询准确 ID返回 429 Too Many Requests限流降低请求频率设置退避重试Credits 快速耗尽模型选择过大 / token 超量限制 max_tokens优化提示词7. Token 成本控制与工程最佳实践OpenRouter 这类网关虽然方便但如果控制不当成本也会快速膨胀。token 消耗和优化是需要长期关注的工程问题。7.1 降低 token 消耗的方法设置max_tokens。不限制最大输出长度便宜的模型也可能返回超长文本导致成本不可控。精简 system prompt。把不相关的背景说明全部去掉只保留任务必须的信息。限制多轮对话历史。不要无限拼接历史消息可以按时间窗口或 token 数做截断。善用摘要。长对话场景中把早期历史压缩成摘要再作为上下文传入。使用轻量模型处理简单任务。意图识别、文本分类、标题生成等任务不需要使用最强的模型。控制 temperature。部分场景降低随机性可以减少无效内容和人工重试。复用缓存。适合固定前缀 动态内容的请求结构能减少重复计算成本。批量合并请求。能一次处理的请求不要拆成多次调用。7.2 工程侧最佳实践API Key 管理使用环境变量或密钥管理服务不要把 Key 写死在代码或前端。日志记录model、input_tokens、output_tokens、response_time、error_code。不要记录完整请求正文和用户隐私数据。超时与重试为请求设置合理 timeout。对 429、5xx 使用指数退避重试不要无限重试。fallback 模型核心流程配置备用模型避免单一模型故障影响业务。配置隔离开发、测试、生产环境使用不同的 Key 和模型配置避免误操作消耗生产额度。安全审计如果业务涉及用户敏感数据要评估数据是否允许发送到第三方模型网关并在必要场景脱敏。7.3 生产环境特别关注生产环境接入 OpenRouter 时我会额外关注几个点余额告警监控 Credits 余额设定低余额告警避免余额耗尽导致业务中断。限流策略提前压测确认你在 OpenRouter 上的请求频率在限流范围内。模型变更OpenRouter 模型列表会动态变化核心模型要定期查看状态。数据合规企业数据是否允许经由第三方网关要提前和安全团队确认。8. 后续怎么继续深入如果你看完这篇文章准备在实际项目里使用 OpenRouter我建议下一步按这个顺序练习先创建 API Key用 curl 完成一次模型列表查询和一次对话请求确认账户可用。再写一个 Python 脚本接入 OpenAI SDK完成流式输出和 usage 统计。然后把模型配置抽成 YAML 或配置文件加入 fallback 机制。最后接入 AI 工具验证工具与 OpenRouter 的协议兼容性。OpenRouter 的文档更新速度不慢模型 ID、价格、支持区域都可能变化。判断问题的最有效方法不是搜索“别人怎么说”而是通过/api/v1/models接口和官方后台确认真实状态。如果你现在没有把 OpenRouter 当成必选依赖而是当成一个“随时可以试新模型、可切换供应商”的工具箱使用体验会舒服很多。模型世界变化很快与其死记某个 API 细节不如掌握一套“查文档、看模型列表、小流量试点、逐步扩大”的方法。这套方法后续接入任何新模型或新平台时都会反复用到。