Jev 是什么，为什么它的调用方式和普通大模型不一样

Jev 不生成文本，只返回结构化的"类型化决策"。官方文档把它的输出归纳为三种"原语"（primitives）：Choice（在给定选项里选一个）、Score（打分或和阈值比较）、Noul（回答是非题并返回概率）。这个设计思路借用了心理学家 Daniel Kahneman《思考，快与慢》里的"系统一"概念——快速、直觉式判断，不做长链推理。

正因为它不走"生成一段文字再解析"的老路，请求体和普通 Chat Completions 接口的字段结构不一样,这也是它比一般模型更容易在早期接入阶段报错的原因之一：字段名或类型稍有偏差，返回的不是 401，而是 422。

Jev 的官方认证格式：一个 Header，一个 Key

官方文档给出的调用方式很简单：

几个关键点：

• API Key 从控制台的 Keys 页面获取，官方文档原文写的是"Get your API key from the dashboard"；
• 请求头固定是 Authorization: Bearer <API_KEY>，和 OpenAI 系接口的写法一致；
• 官方 Python/JavaScript SDK 默认从环境变量 TYPESAFE_API_KEY 读取密钥，不需要在代码里硬编码；
• 不传模型字段时，SDK 默认调用 jev-latest。

官方错误码表：401 只是四种报错之一

TypeSafe 官方文档给出的错误码说明是这四条，原文照录：

需要说明的是：官方文档的错误码表只给出了状态码和文字说明，没有公开具体的 JSON 错误响应体格式，也没有列出 api_key_required、invalid_api_key 这类具体的 error type 字段名。开发者在排查帖里提到的 api_key_required、“incorrect api key provided” 更像是社区总结出来的报错关键词或第三方转发层自己拼装的提示文本，不是 TypeSafe 官方 API 直接返回的字段。写代码时如果要按 error type 做分支处理，建议先直接打一次请求看真实返回体，而不要假设一个尚未在官方文档中确认的字段名。

401 报错的真实成因：不只是"Key 填错了"

结合官方错误码说明和开发者社区的实测排查记录，401 报错通常来自以下几种情况，按出现频率排列：

1. 环境变量没有真正注入进程：本地能读到 TYPESAFE_API_KEY，但启动服务的进程（Docker 容器、CI 环境、Agent 沙箱）里这个变量是空的，SDK 静默传了空字符串。
2. Authorization 头拼写或格式错误：漏了 Bearer 前缀、多写了一个空格，或者把 Key 直接当作裸值传给了自定义网关。
3. Key 已过期或被在控制台吊销：控制台支持随时吊销 Key，吊销后旧 Key 会立即返回 401，而不是延迟生效。
4. 调用地址不是官方 Base URL：接入第三方转发或聚合服务时，如果对方的鉴权方式和官方不同，会在请求还没真正到达 TypeSafe 服务端之前就先被网关拒绝并包装成 401。
5. 多个提供方 Key 混用：项目里同时接了 Jev 和其他模型提供方，环境变量命名相近，容易把别家的 Key 传给了 Jev 的请求头。

排查步骤：从最小可复现请求开始

先用最小 curl 命令直连官方地址，不经过任何自己封装的 SDK 或中间层：

如果这条命令本身就返回 401，说明问题在 Key 或网络层，不在业务代码。

打印环境变量确认它真的被读到：在实际运行环境（不是本地终端）里执行 echo $TYPESAFE_API_KEY，确认长度和前缀符合控制台展示的格式，而不是空值或残留的旧值。

去控制台核对 Key 状态：确认这个 Key 没有被吊销，且属于当前登录的账号——多账号、多项目场景下容易把测试账号的 Key 用到了生产环境。

检查请求头大小写和空格：Authorization 首字母大写，Bearer 后面必须有且只有一个空格，很多网络库不会自动纠正这类细节。

确认没有经过额外的转发层：如果项目里用了自建网关或第三方封装接口转发 Jev 请求，先绕过这层直连官方地址测试，排除转发层鉴权规则不一致导致的问题。

区分 401 和 422：如果直连测试返回的不是 401 而是 422，说明 Key 本身没问题，是请求体里 state 或 questions 字段结构不对——官方文档明确 questions 必须是数组，且每个 question 的 type 只接受小写的 choice、score、noul。

常见问题

Q：401 报错里的 api_key_required 是官方标准错误类型吗？

不完全是。TypeSafe 官方文档给出的 401 说明是"Missing or invalid API key"这句文字描述，并未公开一个固定的错误类型字段名。api_key_required 更多是开发者在排查帖和第三方文章里对这类报错的统称，实际返回体的字段结构建议以自己实测请求得到的原始响应为准。

Q：429 和 401 有什么区别，处理方式一样吗？

不一样。401 是身份没通过验证，需要检查 Key 本身；429 是身份验证通过了，但请求频率超出限制，官方文档建议的处理方式是"指数退避后重试"而不是立即重试，重试太快只会持续触发限流。

Q：项目里同时接了好几个模型提供方，Key 管理容易出错怎么办？

多提供方场景下，环境变量命名混淆是 401 报错里比较常见的一类原因。如果业务本身需要横向调用多款主流大模型，统一 Key 管理能减少这类混用风险——例如七牛云 AI 大模型服务提供的 Token Plan 支持用同一个 Key 调用多款主流大模型，切换模型时只改请求里的模型字段，不需要为每个提供方单独维护一套密钥和环境变量。

Q：Jev 报 422 是不是也和认证有关？

不是。422 属于请求体校验失败，和 Key 是否有效无关，常见原因是 questions 字段类型不对或 question 的 type 值拼写、大小写有误。先解决 401（连通性和身份），再排查 422（请求体格式），是官方错误码表隐含的处理顺序。

结语

Jev 的 401 报错本质上是身份验证链路上的问题，官方文档把它归纳为一句话"Key 缺失或无效"，但真正的成因往往藏在环境变量注入、请求头格式、Key 状态、转发层鉴权这几个环节里。排查时从最小可复现的 curl 直连请求开始，能最快把问题范围从"业务代码"收窄到"网络和鉴权配置"。本文内容以 TypeSafe AI 官方文档（docs.typesafe.ai）2026 年 9 月的公开信息为准，具体错误响应格式请以实际调用返回的原始内容为准。