Jev API 接入路线：官方端点、OpenCode Zen 与 OpenRouter 三条路怎么选

2026 年 11 月，能把 Jev API 接进代码的路线一共三条：TypeSafe 自己的 api.typesafe.ai；OpenCode 的 Zen 网关，它同时挂了 Jev 1.13 的付费版和免费版；以及 OpenRouter。这篇是路线说明书——每条路实际提供什么、不带 key 去探会返回什么、按「每千次请求」折算要花多少钱。

之所以单独写这一篇，是因为三条路的坑不在 prompt 上，而在接入本身：控制台不给你发 key、某个地区直接回 451、同一个 model 名在一个网关能解析、在另一个网关的目录列表里压根不在。这些没有一个是改请求体能解决的。

本篇事实来源： 所有价格、限额、报错字符串，都出自 TypeSafe 官方文档、OpenCode Zen 文档，或 2026-11-07（CST）当天跑的 curl 探针——每条结论后面都跟着当时的 HTTP 状态码。核不实的地方（比如免费版 Zen 是否免绑卡就能用）文中直接写明「未确认」，不猜。

三条路的对照

这几行不是同一类产品，这正是要点所在。TypeSafe 是第一方服务；OpenCode Zen 是转售方，请求体一样但 host 不同；OpenRouter 是市场，它上面 TypeSafe 这一条是个 router，不是一个钉死的型号。选哪条，取决于你的组织实际能付账、能连通的是哪一种形态。

路线 A：官方端点

TypeSafe 所有型号都走同一条路径：POST /v1/systemone，model 字段填 jev-1.14.0、jev-1.13.0 或别名 jev-latest。价格文档只有一行：输入 $42 每十亿 token（$0.042 每百万），输出 token 免费。上下文有两道限制——整条请求 64k、单个问题 32k——发 TypeSafe-Danger-Zone-Long-Context: true 头之后两道都升到 262k，这个头在 1.14 和 1.13 上都生效。

请求规则的严格程度会让把它当 chat API 用的人翻车。body 必须是 UTF-8 JSON 且不能带 BOM，最大 32 MiB；state、instructions、criteria 里每处嵌套最多 64 层；数字必须是有限值，NaN、Infinity 和 1e400 这种溢出值会被拒，大整数/长 ID 要当字符串发。支持 Content-Encoding: gzip 或 zstd 压缩，只能压一层，zstd 窗口最大 8 MiB。

错误码就是这条路最好认的指纹：

• 400 —— 违反了请求规则（UTF-8 非法、嵌套过深、非有限数字、压缩体损坏），或者 max_tokens_exceeded，即请求超出上下文长度
• 401 —— key 缺失或无效，检查 Authorization 头
• 413 —— body 超过 32 MiB
• 415 —— Content-Encoding 不支持，或压了不止一层
• 422 —— body 校验失败，比如问题结构不合法，响应体会指出是哪个字段
• 429 / 529 —— 限流，或 TypeSafe 临时过载，两者都是退避重试；官方 SDK 默认就帮你重试

这条路真正的接入障碍是计费，不是代码。 控制台把「建 key」这个动作卡在余额为正上。TypeSafe 官方 X 账号在 2026 年 9 月底明确说过新注册不再送免费额度；余额为 0 的组织在创建 key 这一步就被拒，而不是等到第一次请求。如果你正对着一个提交不动的表单，缺的那一步是 Billing 里的充值，重新注册多少次都改变不了。

第二个障碍是地区。 2026-11-07 从广东移动网络请求 GET https://api.typesafe.ai/v1/models，返回：

HTTP/2 451
{"title":"Typesafe is not available in your region.","status":451}

POST /v1/systemone 同样是 451，响应头里带着 Cloudflare 的 cf-ray，说明这是 CDN 上的应用级地区决策，不是 socket 被墙。451 Unavailable For Legal Reasons 对重试、换 key、换 HTTP 客户端都免疫——只要同一个网络出口在它不服务的区域内，官方这条路对你是关闭的，跟余额多少无关。这种情况下的实际答案就是路线 B 或 C。

路线 B：OpenCode Zen，以及那个免费版

OpenCode 的 Zen 文档在型号表里只列了两条 Jev：

路径是 /zen/v1/systemone，不是 /v1/systemone；请求体就是 TypeSafe 那一套——model、state、questions，type 填 noul、choice 或 score。Zen 文档自己的示例发的就是 "model": "jev-1.13" 加一个判断紧急度的 noul 问题，然后注明：把 jev-1.13 换成 jev-1.13-free 就能用限时免费版。在 OpenCode 客户端里，配置中的 model id 要带前缀，写成 opencode/jev-1.13。

两个坑，都是探出来的不是猜的：

1. 端点活的，但目录列表和文档对不上。 用故意无效的凭证打 POST https://opencode.ai/zen/v1/systemone，回来 401 {"error":{"type":"authentication_error","message":"Invalid credential"}}——说明路由存在且做鉴权。但 GET https://opencode.ai/zen/v1/models 返回 81 个模型，里面一个 jev-* 都没有，尽管文档表格里明明白白列了两个。结论：models 端点只对 chat 模型可信，Jev 的 id 以文档页为准。
2. 「限时」不是日期。 文档只写限时提供、不给结束日。任何建在 jev-1.13-free 上的东西，第一天就要配好付费兜底；而且 Zen 的接入流程是先要你填计费信息再给 key，这正是「随时会没的免费层」的标准做法。

结构性短板是版本落后：Zen 只有 1.13。Box 问题是 1.14 独占，免费层找不到它。

路线 C：OpenRouter

OpenRouter 是本站写得最多的一条路，但它的目录行为值得单独讲清楚，因为很多人自查集成时会被它搞糊涂。2026-11-07 拉全量目录返回 460 个模型，带 typesafe 前缀的只有 typesafe/jev-router 一条，context_length 标 1000000，prompt 和 completion 定价都是 -1。再查它的端点：

GET /api/v1/models/typesafe/jev-router/endpoints  →  200
{"data":{...,"pricing":{"prompt":"-1","completion":"-1"}, "endpoints":[]}}

钉死版本号的条目讲的是另一个故事。GET /api/v1/models/typesafe/jev-1.14/endpoints 返回 200，里面有一个端点对象：上游名 typesafe/jev-1.14-20261014，context_length 262144，max_completion_tokens 235929，prompt 价 0.000000042、completion 价 0，近 30 分钟与近 24 小时 uptime 都是 100。把它乘出来：0.000000042 每 token 恰好等于文档里的 $0.042 每百万——这条正好可以拿来交叉验证，说明市场里的挂牌价是第一方价格的原样透传，没有加价。

两条放一起读：router 对外宣传但没有价格、没有实时端点；钉版本的 1.14 条目有价也有服务。 -1 不等于免费——OpenRouter 的错误文档写得很清楚 402 是余额不足；一个任何 provider 都能接、但解析不出价格的请求，应该当成路由请求看待，不是购买行为。你要账单可对，就钉版本别用 router。

OpenRouter 的错误词汇表也和 TypeSafe 不同，这就是路线选择会影响集成层的原因：402 是额度不足（先看 error.metadata.limit_source：openrouter_in_flight_budget 表示等 Retry-After 再重试，openrouter_key_limit 表示这把 key 的上限花完了），403 是预算或护栏拦截，429 限流，502 是选中的模型挂了，503 是没有满足你路由要求的 provider。GET /api/v1/key 会返回 limit_remaining，批量任务之前先打一次是最便宜的前置检查。

用「请求数」而不是「token」来算钱

按 token 计价很难有体感。同样一个价，换成每千次请求：按文档价 $0.042 每百万输入 token，并假设整个请求都是输入（输出免费，所以这个假设偏保守）：

332 那一行不是编的——它来自 TypeSafe 文档里那条「一段短客服消息 + 一个 Score 问题」的示例响应中的 usage.input_tokens。结论是：Jev 的成本曲线对问题数量极不敏感，对 state 体积极敏感。五个短问题打在短 state 上，仍然是千次不到一分钱的量级；一个问题打在一份 64k 合同上，贵两个数量级。要预算，就取真实样本量出 input_tokens 再乘，别从「问了几句」推。

上线前的四步连通性核验

在生产代码实际使用的那个网络里跑，因为有意思的失败都发生在网络层。四个探针，都不需要真 key：

# 1. 第一方域名愿不愿意跟这个网络说话
curl -s -o /dev/null -w 'typesafe models: %{http_code}\n' \
  https://api.typesafe.ai/v1/models

# 2. Zen 的 systemone 路由是否存在、是否做鉴权
curl -s -o /dev/null -w 'zen systemone: %{http_code}\n' \
  -X POST https://opencode.ai/zen/v1/systemone \
  -H 'Authorization: Bearer invalid' -H 'Content-Type: application/json' \
  -d '{"model":"jev-1.13","state":"hi","questions":{"q":{"type":"noul","instructions":"Is this a greeting?"}}}'

# 3. OpenRouter 上有没有带价的 Jev 1.14 端点
curl -s https://openrouter.ai/api/v1/models/typesafe/jev-1.14/endpoints \
  | python3 -c "import json,sys;d=json.load(sys.stdin)['data'];[print(e['name'],e['context_length'],e['pricing']) for e in d['endpoints']]"

# 4. router 今天有没有挂实时端点
curl -s https://openrouter.ai/api/v1/models/typesafe/jev-router/endpoints \
  | python3 -c "import json,sys;d=json.load(sys.stdin)['data'];print('pricing',d['pricing'],'endpoints',len(d['endpoints']))"

一个正常网络的读数是：第 1 步 200，或者你所在地区被拒时的 451；第 2 步 401——401 说明路由在，404 说明路径变了；第 3 步打出一行端点信息；第 4 步打出 pricing {'prompt': '-1', ...} endpoints 0，这是 router 当前的真实状态，不是你这边出了故障。

其他任何结果——超时、TLS reset、Cloudflare 挑战页——都是关于你出口网络的网络事实，改应用代码改不好。在开迁移会之前花十分钟把这条界线量清楚，很值。

怎么选

• 要最新模型、图片、Box 问题或长上下文头 → 官方端点，或 OpenRouter 上钉死的 typesafe/jev-1.14。Box 问题仅 1.14 支持；图片与 Box 两块在官方文档里都标着 Dreamer-ready，所以版本要钉住，也要预期形状会变。
• 在做原型、一分钱不想花 → OpenCode Zen 的 jev-1.13-free，但从第一天就把付费兜底接好，因为这个优惠没有公布结束日。
• 你的网络到不了 api.typesafe.ai → 走 B 或 C。451 不谈条件。
• 你需要一个能跟发票对得上的挂牌价 → OpenRouter 的钉版本端点，它的 0.000000042 和 TypeSafe 公布的 $0.042 每百万完全一致。
• 你想让市场替你挑模型 → router，但要接受它现在报的是 -1 定价、端点数组为空，并且在它和线上之间放一道硬预算护栏。

不管选哪条，把这个选择关进一个 client 函数里。三条路收的都是同一个 state 加类型化 questions 的体、吐的都是同样的答案形状，所以迁移成本就是一个 base URL、一把 key、一个 model id——前提是你别让 model id 漏散在十个文件里。渠道对比与迁移 runbook那篇把适配器写全了，官方 SDK 指南讲的是原生说路线 A 的那个客户端。