Jev API Key 获取与环境配置教程

发出第一个判断题之前，你得先拿到 API Key，并把它放在一个安全的环境里。最快的路径走 OpenRouter——Jev 的主演示渠道：它通过 OpenAI 兼容端点暴露 Jev，你拿到 Key 之后用的就是熟悉的请求结构。这篇教程覆盖拿 Key、接入环境变量、设置额度，以及避免”昂贵事故”的安全习惯。

TL;DR： 在 OpenRouter 注册、充值、创建 API Key；把 Key 存进环境变量（OPENROUTER_API_KEY），绝不写进代码。第三方列表显示 Jev 约 $0.0462 / 1M input tokens——实时价格以 OpenRouter 模型页为准。官方 TypeSafe AI 渠道及其端点，请以 typesafe.ai 官方文档为准，不要凭空猜端点。

开始前：账号、组织与 Key 的作用域

在点”创建 Key”之前，有几个概念值得先搞清楚，省得后来返工。

OpenRouter 的访问控制以账号为单位，账号可以归属于一个或多个组织（Organization）。如果只有你一个人用，个人账号就够。如果团队共享同一个额度池，先建组织——组织下签发的 Key 扣的是组织余额，不是你个人的钱包。

项目这个概念在 OpenRouter 里没有正式对应物，但实际操作上，“一个逻辑应用对应一个 Key”就是你的项目划分方式：生产环境打分管线用一个 Key，测试环境用一个，本地实验再用一个。这样做的好处是：当某个 Key 的用量突然飙升，你一眼就知道是哪条管线出了问题，而不是全账号流量混在一起猜。

Key 的作用域：OpenRouter 目前不提供读/写/管理这样的细粒度权限，你能控制的是消费上限——把这个当作你的权限替代品：低频查询的 Key 给个低上限，生产 Key 给一个比预期月消费高 20% 的上限。最小权限原则，落到钱上。

如果需要审计日志、正式访问控制或 SLA 保障，官方 TypeSafe AI 渠道提供独立的直连端点和企业条款，与 OpenRouter 是两条不同的路。两条路的取舍见 API 渠道怎么选。

逐步获取 Jev API Key

第一步：注册 OpenRouter 账号

打开 OpenRouter 注册。支持邮箱密码和 OAuth（GitHub、Google）。登录后如有提示，先验证邮箱——部分充值路径需要已验证的账号。

第二步：进入 Keys 页面

控制台的 Keys 页面路径是 openrouter.ai/settings/keys。点 Create Key，会看到两个字段：

• 名称（Name）：用一套六个月后你还能看懂的命名规范。prod-scoring-01、staging-jev-01、local-dev-blue 这类名字远比”my key”有用。名称会出现在用量报告里，凌晨两点紧急撤销的时候，名字就是你找对 Key 的唯一线索。
• 消费上限（Credit limit）：现在设，不要等以后。第一个测试 Key 给 $5 足够跑很多次调用了。生产 Key 按预期月用量算完加 20% 缓冲再填——具体怎么算见 成本与延迟指南。

第三步：立即保存 Key

Key 只显示一次。对话框关掉之后，sk-or-v1-... 这串字符就消失了，控制台只会保留一个脱敏版本供识别。关对话框之前，先把完整 Key 存进密码管理器或安全备注。丢了就只能新建一个并撤销旧的，没有找回流程。

第四步：确认 Jev 的模型 slug

在 OpenRouter 的模型列表里搜索 Jev。写作本文时，模型标识符是 typesafe/jev-1.13，这个 slug 要填进 API 请求的 model 字段。版本号会随发布更新，不要直接从旧教程复制——去 OpenRouter 模型页确认确切的 slug，同时看一下定价标签里的 token 单价和上下文长度限制。

环境变量与安全实践

.env 文件写法

在项目根目录创建 .env 文件：

# .env — 这个文件绝对不能提交
OPENROUTER_API_KEY=sk-or-v1-your-key-here
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1

第一天就把 .env 写进 .gitignore，不要等”以后”：

echo ".env" >> .gitignore
echo ".env.local" >> .gitignore

这件事比大多数人以为的重要得多。一个推到公开 GitHub 仓库的 Key，通常几分钟内就会被自动扫描工具收走。OpenRouter 有滥用检测，可能会先锁你的账号，但不能指望它。

CI/CD 中的 secrets 注入

以 GitHub Actions 为例，把 Key 加为仓库 Secret（Settings → Secrets and variables → Actions → New repository secret），再在工作流文件里引用：

env:
  OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}

GitLab CI（CI/CD Variables）、Vercel（Environment Variables）等平台都是同样的思路：Key 不碰源码，在运行时注入。

本地自动化工具（比如 n8n）请用工具自带的凭据存储，不要把 Key 粘进工作流节点。n8n 工作流指南里有具体接法。

轮换周期：90 天

把 Key 当密码一样定期换。基准是每 90 天轮换一次，团队规模大或 Key 访问范围广就缩短。轮换步骤：

1. 用相同命名模式新建一个 Key（比如 prod-scoring-02）。
2. 在 secrets 管理器 / CI 环境里更新 Key 的值。
3. 部署并验证新 Key 能正常工作。
4. 撤销旧 Key。

顺序不能反——先撤销会导致服务中断。新建、验证、撤销。

泄露应急处理

如果 Key 出现在日志、截图、PR diff 或者 Slack 消息里，处理顺序：

1. 立刻撤销。不要先调查再撤，几分钟的服务中断比未知的额度损耗划算得多。
2. 查用量。在 OpenRouter 控制台按 Key 查最近 24 小时的调用量。有你不认识的流量就说明 Key 已经被人用了。
3. 轮换相关的所有 secrets。如果泄露的 .env 文件里还有其他值，一并换掉。
4. 补上检测。在仓库里加 secret 扫描器（truffleHog、git-secrets 或 GitHub 自带的 secret scanning），堵住同样的泄露路径。

第一次调用

curl 示例

先在 OpenRouter 模型页确认模型 slug，然后：

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "typesafe/jev-1.13",
    "messages": [{"role": "user", "content": "Judgment question: is the sky blue?"}]
  }'

返回 200 且 message content 里有结构化答案，说明 Key、余额、模型 slug 三者都对了。

Python requests 示例

import os
import requests

api_key = os.environ["OPENROUTER_API_KEY"]  # 缺失时抛 KeyError——这是有意为之

response = requests.post(
    "https://openrouter.ai/api/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "model": "typesafe/jev-1.13",
        "messages": [{"role": "user", "content": "Judgment question: is the sky blue?"}],
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()
print(data["choices"][0]["message"]["content"])

解析后的答案——示例数据（example fixture），正式字段名以官方文档为准：

{
  "answer": "yes",
  "confidence": 0.99,
  "rationale": "Visible-sky blue coloration is the expected answer to this common-knowledge question."
}

常见报错对照表

每种错误的详细排查步骤见 Jev 常见报错排查。

配额、限流与计费

免费额度与充值

OpenRouter 对大多数模型没有永久免费层。注册时会有一笔小额赠送额度（金额不固定，看控制台），用完之后就是预充值模式。以 Jev 约 $0.0462 / 1M input tokens 的列表价估算：

• 1,000 次短判断调用（~100 token 每次）≈ $0.005，测试阶段基本可忽略
• 100,000 次调用，每次 200 token 的 prompt ≈ $0.92
• 每天 100 万次调用，均 150 token ≈ $6.93/天

上面都是 input token 估算。判断类响应的 output 通常很短，实际成本接近这个数字。自己的业务量怎么算，见 Jev 成本与延迟里的工作表。

限流响应头

OpenRouter 每次响应都会带这几个头：

批处理任务里把这些头记进日志。如果 X-RateLimit-Remaining 掉到个位数，在下一批之前加个小延迟。一个简单的令牌桶（token bucket）实现大约 15 行 Python，能消灭批量场景里 90% 的 429。

消费上限是最有效的保护

在 Keys 设置里给每个 Key 配一个消费上限。这是应对 bug 或 Key 泄露导致异常费用最直接的手段。测试 Key 设 $20 上限，意味着任何错误的最坏结果是 $20，而不是 $2000。管线在生产环境验证稳定之后再酌情提高上限。

常见问题

一个 OpenRouter Key 可以同时调用 Jev 和其他模型吗？

可以。OpenRouter 的 Key 不绑定特定模型，同一个 Key 能调用平台上任何可用的模型。消费上限是全模型通用的，如果你混用多个模型，预算时把这个算进去。

设了消费上限但 OpenRouter 还是多扣了怎么回事？

消费上限是尽力而为（best-effort），不是硬截断。上限生效前的一批请求如果同时处理完，可能会略微超额。把上限理解成预警信号而不是保证的硬上限。

OpenRouter 的速率限制和模型本身的吞吐上限有什么区别？

OpenRouter 按套餐执行自己的速率限制。底层模型可能还有独立的容量约束。需要有 SLA 保障的固定吞吐量，可以看 TypeSafe AI 直连渠道，API 渠道怎么选里有对比。

安全习惯清单

• 一个项目一个 Key。 用量异常时你知道查谁，撤销时也是精确打击。
• 每个 Key 设消费上限。 没有上限的泄漏 Key 就是一张敞开的账单。
• 每 90 天轮换一次。 现在就把提醒加到日历里。轮换五分钟，避免的是那种”大概没泄露”的 Key 悄悄扣钱几个月的情况。
• 绝不提交 .env 文件。 第一天就写进 .gitignore。
• 有疑点先撤销，再调查。 拿不准 Key 有没有泄露？先撤。Key 缺失导致的服务中断是分钟级的。活着的泄露 Key 带来的损失是没有上限的。
• 把 Key 当密码对待——它就是密码，背后还挂着你的信用卡。

Key 验证通过后，接着看 Jev API 教程：第一次调用 了解完整的请求解读，或看 ticket triage 案例 了解 Key 在真实工作流里怎么用。

Key 泄露后的处置顺序与轮换

Key 一旦出现在公开渠道——GitHub 提交记录、Slack 消息、任何 paste 链接——就假设它在几分钟内已经被扫走。针对 GitHub 和常见 paste 网站持续运行的自动扫描器有很多，部分来自安全研究人员，更多来自专门抓凭证的 bot，这些 bot 发现 sk-or-v1- 之类的特征字符串后会在几秒内向 OpenRouter 发出测试请求。你的反应窗口不是几小时，是几分钟。

处置顺序比事后调查更重要。第一步：立刻去 OpenRouter 的 Keys 页面吊销这个 Key，不要等着确认是否被人用过。误报的代价是新建一个 Key 并更新一个变量。第二步：创建新 Key，取一个新名字，重新设置消费上限，把每个用过旧 Key 的环境都更新一遍。第三步：在 OpenRouter 的用量日志里查找你没有发出的请求，重点看泄露时间窗口前后的模型 slug 和请求量，和正常用量模式比对。新 Key 上线并验证通过之后，再做溯源。

.gitignore 的自动检查有帮助，但替代不了根本不提交 secrets 这件事。git-secrets 或 GitHub 原生的 secret scanning 能拦截正在推送的内容，但只对触发扫描的那次 push 起作用。如果在配置扫描之前就提交过含 Key 的文件，历史记录里可能已经有了。怀疑有历史泄露时，用 git log -S 'sk-or-v1-' --all --source 搜索全部提交历史，而不只是当前工作区，有命中就按已确认泄露处理，不管最新版本里这个 Key 是否还在。

用最小请求验证 Key 是否生效

验证新 Key 不需要跑真实业务请求。最小的有效 Jev AI 调用是一条很短的 prompt 加一个压低了的 max_tokens。比如 "Classify: positive or negative? Text: great." 配上 max_tokens: 5，会触发一次真实的 Jev AI 判断，消耗大约 20 个 input tokens 和 3 到 5 个 output tokens，按现行列表价不到 $0.000001。用这种最小请求做连通性确认，不要直接拿生产 prompt 去测——万一 Key 配置有问题，跑一轮真实测试集的代价就白费了。

Key “有效但不工作”的失败模式有两种，容易混淆。429 Too Many Requests 说明 Key 认证通过了，只是触了速率或额度上限，这是计费问题不是 Key 问题。402 Payment Required 说明账户没有余额，或者消费上限被设成了 0。这两种都跟 401 Unauthorized 不同——401 才是 Key 本身有问题或已被吊销。每个错误对应不同的修法，把它们混一起处理只会拖长排查时间。看响应体里的 error.message 字段，OpenRouter 通常会附上一段可读的说明。

返回第一次测试请求的原始响应体，不要只看 content 字段。响应里的 usage 对象包含 prompt_tokens 和 completion_tokens，确认这两个值都非零，且和输入长度相符。如果 content 字段是 null，但 finish_reason 是 content_filter，那是内容策略拦截，不是 Key 问题——Key 本身是好的。每种 finish reason 的详细排查步骤见 Jev 常见报错排查。

多环境 Key 管理：本地、CI 与生产

三个环境的威胁模型不同，存放方式也不同。本地开发用项目根目录的 .env 文件，配合 dotenv 或等效库加载。这个文件必须写进 .gitignore，绝对不能提交。操作纪律只有一条：先把 .env 加进 .gitignore，再创建这个文件。顺序反了哪怕一次，文件就可能在 gitignore 条目还没生效时溜进某次提交。可以提交一个 .env.example 占位版本，里面放变量名和假值，供新成员了解需要配置哪些变量，不涉及真实值。

CI/CD 环境（GitHub Actions、GitLab CI、CircleCI）都有专用的 secrets 存储，直接用就行。在 GitHub Actions 里，名为 OPENROUTER_API_KEY 的 secret 在 workflow YAML 里以 ${{ secrets.OPENROUTER_API_KEY }} 形式注入，日志里会自动打码，就算某个 step 打印所有环境变量也不会暴露真值。不要在 env: 块里直接写字符串值，也不要通过 Docker build 的 --build-arg 传 Key——build argument 会记录进镜像 metadata，用 docker history 就能看到，泄露路径隐蔽但真实存在。

生产环境因平台而异，但原则相同：用平台原生的 secret 注入机制（AWS Secrets Manager、GCP Secret Manager、Heroku Config Vars、Render 环境变量），不要把 Key 烧进镜像或配置文件。Next.js 的 NEXT_PUBLIC_ 前缀值得单独说一下：任何带这个前缀的变量都会被打包进客户端 bundle，随网页下发到每一台浏览器。把 Jev API key 放进 NEXT_PUBLIC_ 变量，等于把 Key 公开。对 Jev API 的调用必须走服务端路由——Next.js API route、Edge Function 或独立后端，不能从浏览器直接发出。

本文适用版本 Jev 1.13。