简介这是一份可运行的OpenRouter密钥获取源码包面向需要调用OpenRouter平台接口的软件开发者特别适合刚接触密钥管理与接口鉴权的新手以及希望将大模型能力快速集成到自身应用中的个人开发者或小团队。压缩包整体仅5KB共包含3个文件index.html提供完整的操作演示页面.inscode用于云端环境快速运行.gitignore则对项目版本管理进行了基础配置结构紧凑便于下载后直接查看运行。目前已有319人学习。源码以网页形式逐步呈现OpenRouter账号注册与密钥获取流程覆盖使用Google、GitHub、Discord或邮箱完成验证登录后在Keys选项中创建并复制密钥等关键环节同时特别强调密钥生成后无法二次查看、必须立即安全保存的注意事项并给出了配置到本地或云端项目时的通用思路。通过运行和阅读这套示例开发者能够快速理清密钥的创建步骤掌握不同部署版本下配置文件的调整方法避免因密钥泄露、遗忘或配置错误造成使用中断为后续基于OpenRouter的接口调用和模型接入打下基础。1. 为什么说“获取OpenRouter API Key”是所有模型实验的第一步某开发者的模拟项目X同时在对比三个不同厂家的模型单是注册账号、管理各自的 Key 和请求格式就用掉大半天。后来他把 OpenRouter 作为统一入口注册一次、创建一把 OpenRouter API Key同一个请求体里改一个模型字段就能切换目标模型。这个思路特别适合还在早期验证阶段的开发者你需要快速知道哪个模型效果好而不是把时间耗在环境配置上。这篇笔记会把获取 OpenRouter API Key 的完整链路拆开注册、建 Key、跑通第一段可运行源码、调整关键参数再把最容易碰到的几个报错整理成排查清单。新手照着做就能通熟手可以直接跳到参数和避坑部分。2. 注册、创建、充值把 Key 拿到手的关键动作2.1 注册前先想清楚账号与权限怎么选获取 OpenRouter API Key 的第一步不是直接找创建按钮而是先确认你的使用场景。用邮箱注册后控制台里默认还没有任何 Key需要手动创建。这个 Key 的权限和你的账号状态绑定只跑免费模型的话通常可以立刻开工要调用付费模型就得先给账号充值。我的习惯是先用免费模型把流程跑通确认请求格式没问题后再决定要不要充值。这里有个容易被忽略的点OpenRouter 聚合了大量模型不同模型对账号权限的要求不一样。有的免费模型在未充值账号下也能调用有的则要求余额大于零。因此注册后先别急着充钱先去 Keys 页面建一个 Key用第 3 章的脚本拉一次模型列表看你能看到多少模型、哪些标着免费可用。这一步能帮你摸清自己的账号权限边界。注册时尽量用你常用的邮箱因为后续账单和密钥重置通知都会发到那里。不建议用临时邮箱一旦丢号控制台上的 Key 管理权限也会一起丢掉到时只能重建账号。至于要不要绑定支付方式取决于你是不是要跑付费模型。如果只是做原型验证先用免费模型完全够如果团队采购、批量评测再考虑充值。2.2 在 Keys 页面创建你的第一个 API Key注册完成并登录后打开控制台左侧的 Keys 页面这是创建和管理 API Key 的唯一入口。点页面右上角的 Create Key系统会让你填一个名称。名称只是给你自己看的方便区分是哪个项目在用建议写“模拟项目X”或“eval-task”这样的可读标识不要包含空格。创建成功后页面会显示一串完整的 Key。这里必须注意这串 Key 只在创建时出现一次离开页面后任何人都无法再次查看完整内容。如果你忘了复制没有任何管理员能帮你找回唯一的后悔药就是重新创建一个新 Key再把这个 Key 从你的配置里替换掉。所以我拿到 Key 后的第一动作是把它复制到本地.env文件里然后立刻在控制台刷新页面确认已成功创建。控制台通常还会展示创建时间、最后使用时间等元信息。建议每隔一段时间回来看看哪些 Key 已经不用了及时删除降低泄露风险。创建 Key 本身不需要额外审核授权范围是账号级的也就是说一旦 Key 泄露别人会用你的额度调用模型。命名时我习惯带环境后缀比如projectx-prod和projectx-dev这样同一个账号下多个 Key 同时使用出问题时能快速定位到是哪条链路泄露。2.3 给 Key 配好额度与免费模型的选择创建好 Key 后你需要搞清楚账号的额度状态。OpenRouter 官方控制台里额度信息一般放在 Settings 或 Billing 区域。免费模型调用会消耗免费额度付费模型则按 token 计费。不同模型的计费差异很大同样是几千 token 的请求成本可能差出一个数量级。我的建议是先用一张表格把你需要的模型类型列出来。免费模型适合功能验证、跑通代码付费模型适合效果对比、线上生产。表格式的选型逻辑如下模型类别适用场景对 Key 的要求免费模型验证 Key、测试请求结构、跑通demo注册后即可用低单价付费模型批量评测、成本敏感场景账号通常需要预充值高端付费模型效果对比、复杂任务建议先小额充值测试这里的“预充值”金额不需要我写死因为平台活动经常变化以控制台当前页面显示为准。我只提醒一件事不要充多。第一次验证时典型消耗非常小等真正跑批量任务前再评估预算。很多开发者第一次充值后就丢在角落里忘记了隔月一看消耗量才发现模型列表里的免费模型也有每日请求上限。注意Key 的额度消耗和模型本身是否收费是两套逻辑。有的模型标着免费但调用时仍然会计入请求次数或速率限制。换句话说免费不代表无限量接口被限流时同样会返回 429 状态码这一点我们在第 5 章再展开。3. 拿到 Key 后第一个要跑的源码验证 Key 并拉取模型列表3.1 最小可运行源码把 Key 放进环境变量再发请求拿到 Key 后不要急着去填各种请求参数先写一个最小的 Python 脚本验证这个 Key 是否真的有效。这里我选择调用 OpenRouter 的模型列接口它不需要拼接 prompt也不会消耗生成额度却能快速得到鉴权结果。import os import sys import requests API_KEY os.getenv(OPENROUTER_API_KEY, ).strip() if not API_KEY: sys.exit(未检测到 OPENROUTER_API_KEY请先 export OPENROUTER_API_KEY你的Key) headers { Authorization: fBearer {API_KEY}, Content-Type: application/json, } resp requests.get( https://openrouter.ai/api/v1/models, headersheaders, timeout15, ) print(HTTP 状态码:, resp.status_code) if resp.status_code ! 200: print(resp.text) sys.exit(1) data resp.json().get(data, []) print(模型数量:, len(data)) for model in data[:10]: print(model[id])这段代码的核心是三个点。第一Key 从环境变量读取而不是直接硬编码在代码里避免源码提交后 Key 跟着泄露。第二请求头用Authorization: Bearer API_KEY这是 OpenRouter 通用的鉴权方式。第三用只读的模型列表接口做验证它不触发生成计费跑起来没有成本压力。参数说明timeout15表示单次请求最多等 15 秒超过就抛异常.get(data, [])防止接口换结构时直接报错data[:10]只打印前 10 个模型因为完整列表可能很长。这个脚本如果返回 200说明 Key 有效如果返回 401 或 403问题基本出在 Key 本身或账号权限上。为什么不直接用 curlcurl 当然可以作为最小验证但它不适合后面要做的模型清单整理和批量请求。Python 脚本的扩展成本很低把返回值改成写文件、过滤字段都只差几行代码。所以我建议第一次就把它做成脚本后续直接复用。3.2 把模型列表变成可搜索的本地清单上面的脚本只是打印前 10 行真正做模型选型时你还需要看到模型 ID、上下文长度、价格等信息。我一般会把模型列表落盘成 CSV这样后面写代码时可以直接查。import os import csv import requests API_KEY os.getenv(OPENROUTER_API_KEY, ).strip() headers {Authorization: fBearer {API_KEY}} resp requests.get(https://openrouter.ai/api/v1/models, headersheaders, timeout15) data resp.json().get(data, []) with open(openrouter_models.csv, w, newline, encodingutf-8) as f: writer csv.writer(f) writer.writerow([id, context_length, pricing]) for model in data: writer.writerow([ model.get(id, ), model.get(context_length, ), model.get(pricing, {}).get(prompt, ), ]) print(已写入 openrouter_models.csv共, len(data), 个模型)注意不要直接信任控制台页面上的模型名称一切以接口返回的id字段为准。后续调用 Chat 接口时模型名就是这里拿到的id它有固定的格式通常包含厂商名和模型名中间用斜杠分隔。pricing是一个嵌套字典这里只取prompt单价。如果你的 Key 权限不足有些模型的pricing可能为空。这个清单建议每次脚本运行后都重新生成一次因为模型列表更新频率不低你上周看到的模型这周可能就下线了。3.3 这个源码为什么能验证 Key 是否有效模型列表接口看似简单但它能暴露三类问题。第一类是网络问题timeout超时或连接异常说明本地到 OpenRouter 的网络链路有问题第二类是鉴权问题状态码 401 通常表示 Key 不正确或已删除403 表示 Key 没有对应权限第三类是账号问题状态码 429 暗示账号额度不足或请求太频繁。实际使用中很多开发者拿到 Key 后直接去跑 Chat 请求返回 401 时第一反应是“源代码有问题”其实是 Key 没设置正确。先跑一个模型列表脚本能把网络、鉴权、权限这些变量拆开让排查范围变窄。这个习惯能省下大量时间尤其是当你准备把 Key 集成进更大系统时。如果脚本打印的模型数量是 0但状态码是 200那说明账号被限制了可见模型范围常见于只允许访问某个白名单模型的情况。这时候你需要回到控制台检查账号权限而不是继续调代码。模型列表只读接口和生成接口的权限也可能不一致所以这只是一个快速过筛工具不能完全替代一次真实 Chat 请求。4. 让 Key 真正干活Chat 请求的结构与五个必调参数4.1 Chat 请求的完整结构一个可运行的最小示例模型列表演示完接下来要做一次真正的 Chat 请求让 Key 产生价值。OpenRouter 的 Chat 接口路径是/api/v1/chat/completions请求体结构上与 OpenAI 兼容你只需要改一下接口地址和模型 ID 就能复用很多现成代码。import os import requests API_KEY os.getenv(OPENROUTER_API_KEY, ).strip() MODEL os.getenv(OPENROUTER_MODEL, openrouter/auto) headers { Authorization: fBearer {API_KEY}, Content-Type: application/json, } payload { model: MODEL, messages: [ {role: user, content: 用一句话解释什么是 API Key} ], max_tokens: 100, temperature: 0.7, } resp requests.post( https://openrouter.ai/api/v1/chat/completions, headersheaders, jsonpayload, timeout30, ) if resp.status_code ! 200: print(请求失败:, resp.status_code) print(resp.text) exit(1) result resp.json() print(result[choices][0][message][content])这段代码的关键在于payload结构。model指定要用哪个模型messages是一个角色消息列表最后一条通常是user消息max_tokens限制返回长度temperature控制随机性。如果你只是想把 Chat 流程跑通先不用管太多参数保持这样就能得到结果。这里我用了openrouter/auto作为默认模型它是一个兼容性占位并不是所有权限都能调用。第一次运行时如果返回 404回第 3 章的模型列表里复制一个明确的模型 ID比如列表中第一个免费模型的id替换掉MODEL环境变量即可。把模型选择放到环境变量里有一个好处同一个代码仓库可以在不同项目间复用换模型不用改代码。4.2 五个必调参数temperature、top_p、max_tokens、seed、stream这五个参数是你在 Chat 请求里最常调整的也是真正影响“输出质量”和“调用成本”的地方。temperature控制输出的随机性取值范围一般是 0 到 2。数值越小输出越确定数值越大越有创造性。做代码生成、信息抽取这类任务我建议把temperature设在 0.2 以下做文案创意可以先从 0.8 试起。这里不存在绝对正确的值你需要在具体任务上做小样本对比。top_p是核采样参数和temperature互相影响。它控制模型只从概率最高的前 P 部分 token 里采样。我一般先保持默认或设为 1只有当temperature调不准时才动它。不要在调temperature的同时大改top_p否则两个采样策略互相干扰结果会变成玄学。max_tokens是硬约束直接决定一次请求最多生成多少 token。设得太小答案会被截断设得太大费用会上去。比较稳的做法是先设一个略小于实际需求的量比如期望答案 200 字就设 300 token。注意 token 数不等于字数英文和代码场景尤其明显。seed用于期望结果更可复现。OpenRouter 的底层模型厂商不同有的模型支持固定种子有的不支持。如果你运行的评测任务要求对照实验请先在模型列表里确认该模型支持 seed再把它设为固定整数。这个参数用得好能让对比实验的干扰因素少一截。stream决定响应是整体返回还是流式返回。生成内容比较长时streamtrue能大幅缩短首字等待时间把“等待黑匣子”变成逐字看到输出。代价是代码处理逻辑更复杂需要解析多个数据块。4.3 参数速查表为了方便你在调试时快速定位我把这五个参数整理成一张表。参数类型作用建议设置temperaturefloat控制随机性0.7 起步任务要求稳定时降到 0.2top_pfloat核采样阈值先保持默认不要和 temperature 同时乱调max_tokensint最大生成 token 数按输出长度估算宁少勿多seedint随机种子评测场景固定日常可不传streambool是否流式返回长回答用 true短回答用 false这张表不针对特定模型展开因为具体模型的默认值可能不同。你在替换模型时先打开模型对应文档看默认值再按这个表微调会比盲目套用快很多。4.4 流式输出把黑匣子变成逐字打印当你要在终端里实时看到模型输出或者做流式交互应用时需要把stream设为true并逐行解析返回的数据。import os import requests API_KEY os.getenv(OPENROUTER_API_KEY, ).strip() headers { Authorization: fBearer {API_KEY}, Content-Type: application/json, } payload { model: openrouter/auto, messages: [{role: user, content: 写一首四行短诗}], stream: True, } with requests.post( https://openrouter.ai/api/v1/chat/completions, headersheaders, jsonpayload, streamTrue, timeout60, ) as resp: for line in resp.iter_lines(): if not line: continue text line.decode(utf-8) if text.startswith(data:): content text[5:].strip() if content [DONE]: break print(content)注意流式响应的每一行都以data:开头你需要手动去掉前缀再解析 JSON。如果直接打印整行你会看到大量无用元信息。这个逻辑没有统一标准最好对照实际返回逐行调整。用流式还有一个好处一旦请求出错你能更早地从响应流里看到错误片段排查会更直观。5. 获取 OpenRouter API Key 后的踩坑与排查清单5.1 401 UnauthorizedKey 没带上还是环境变量名写错现象脚本请求返回 401响应里提示 Unauthorized。你检查了 Key看起来没问题。原因最常见的是环境变量没设置成功或者代码里取变量时大小写写错了。比如设置了OPENROUTER_API_KEY代码读取时却用了OPENROUTER_KEY。另外Windows 终端和 Linux 终端设置环境变量的语法不同忘记export也会导致子进程里读不到。解决先手动打印API_KEY的前几位但注意不要打印完整 Key。确认它和创建页面一致后再检查请求头里的格式必须是Authorization: Bearer 完整Key中间有空格不要把逗号或引号带进去。我一般会在脚本里加一个if not API_KEY: sys.exit(...)第一时间暴露变量缺失。这一步的血泪经验是不要打开两个终端一个设置了环境变量另一个没设置结果怎么排查都找不到原因。所有测试尽量放在同一个终端会话里或者干脆把环境变量配置写到全局配置文件中。5.2 404 Model Not Found模型 ID 不是人话现象状态码 404报错信息指明模型不存在。你明明记得控制台里有这个词。原因模型 ID 必须与接口返回的id字段完全一致包含大小写和斜杠。很多模型 ID 长得不像人能记住的名字手写很容易漏掉后半段。解决不要从记忆或博客里复制模型名一律用模型列表接口生成的 CSV 来找。如果你要用的模型在 CSV 里找不到先确认是不是模型已下线或者你的账号没有该模型的可见权限。把model字段从环境变量里切换一次就是最稳妥的做法。还有个小细节有些模型名里带小数点或版本号直接作为 JSON 字段值时没有问题但如果你把它拼进 URL 或 shell 命令里可能需要转义。用json传参数时基本不会踩这个坑但用 curl 就会遇到需要特别注意。5.3 429 Too Many Requests余额不足和并发超限是两码事现象请求返回 429响应体里包含 rate limit 或 insufficient credits 之类字样。你以为是网络问题重试几次仍然一样。原因429 通常有两种独立原因。一种是余额耗尽或没有充值请求被计费策略拦截另一种是单位时间请求次数超过限制。两种情况在响应体里会给出不同提示你要看的是具体信息而不是只看状态码。解决如果是余额耗尽去控制台确认额度和账单如果是速率限制抓一次响应头里的Retry-After或限流字段按建议等待时间重试。不要在 429 时暴力重试那样只会把限流窗口拉得更长。更好的做法是在代码里加指数退避第一次等 1 秒第二次等 2 秒最多等 8 秒。我见过一个模拟项目X的批量脚本遇到 429 后会连续重试十几次结果把每分钟的配额全打满越重试越失败。后来改成检查响应体里的错误码再决定是等待还是换模型问题才解决。5.4 浏览器里跑被 CORS 拦Key 不能直接暴露在前端现象前端代码直接在浏览器里调用接口浏览器控制台报 CORS 错误请求根本没发出去。原因OpenRouter 的接口不支持浏览器跨域携带凭证这是安全设计防止 Key 被页面脚本直接使用。此外把 Key 写在前端代码里等于公开给所有访问者别人复制后可以消耗你的额度。解决不要在浏览器端直连换成自己的后端代理。由后端读取环境变量里的 Key再转发到 OpenRouter。前端只请求你自己的代理服务密钥永远不出服务器。这一步做起来很简单但能避免绝大多数 Key 泄露事故。哪怕你的项目只是本地演示也建议走一个本地代理脚本而不是把 Key 塞进 HTML 里。一旦演示时有人在浏览器里打开开发者工具Key 就能被复制走。安全习惯最好从第一天就建立。5.5 Key 被提交到公开仓库撤销并重建是唯一的后悔药现象某开发者把.env文件或代码里的 Key 字符串推到公开仓库几分钟后被爬虫扫描并盗用。控制台里可以看到用量异常。原因环境变量文件没有写进.gitignore或者有人图省事把 Key 硬编码进源码。公开仓库对 API Key 的搜索非常敏感即使你随后删除提交历史记录里仍然能读到。解决第一时间到控制台删除泄露的 Key并创建新 Key。删除旧 Key 会让所有使用它的请求立即失效这是最直接的止损。接下来再清理仓库历史但清理不是重点因为 Key 已经废弃了。我的习惯是每次新建项目都复制一份.env.example里面只写不带值的变量名然后把.env加入.gitignore。不要抱有“这个仓库很冷门应该没人看到”的想法。扫描机器人每天都在爬 GitHub 和代码托管平台它们比人更勤快。只要 Key 带Bearer特征被识别出来只是时间问题。6. 再进一步把 Key 用法固化成自己的工具箱6.1 把验证脚本做成一条命令我习惯把check_openrouter.py固定在一个脚本目录里之后每次拿到新 Key 或怀疑 Key 失效就用OPENROUTER_API_KEY... python check_openrouter.py跑一次。为了不把 Key 留在 shell 历史里我会用密码管理器读取后粘贴到环境变量或者直接用一个.env文件在当前 shell 里set -a后 source。6.2 用 .env 文件管理 Key推荐在项目根目录放一个.env然后用一段不依赖第三方库的小代码读取from pathlib import Path import os for line in Path(.env).read_text().splitlines(): if line.strip() and not line.startswith(#): k, _, v line.partition() os.environ.setdefault(k.strip(), v.strip())这段代码把.env里的键值对注入环境变量之后你的脚本继续用os.getenv(OPENROUTER_API_KEY)取 Key完全不用改业务代码。记得把.env写进.gitignore。6.3 我的习惯被 Key 泄露麻烦过一次之后我现在建任何项目都会先建.env.example里面只写OPENROUTER_API_KEY再把.env加入忽略列表。换模型时只改环境变量不碰代码。这样即使源码公开别人拿到的也只是模板而不是能直接刷额度的密钥。做技术验证时多花一分钟做隔离后面能省出一小时排查异常用量。希望帮到你。本文还有配套的精品资源点击获取