Jev 是 TypeSafe 的 System One 决策模型，全部能力走一个接口：POST https://api.typesafe.ai/v1/systemone。请求带 state、model、questions 三样东西，返回结构化判断加概率，不做文字生成。本文把调用流程、字段写法、题型返回、置信度阈值和报错排查一次讲完，参数均取自官方文档。
Jev API 的调用地址与凭证准备
要调通这个接口，你只需要两个东西：一个地址和一把 Key。地址是固定的，Key 得自己去控制台拿。
- 接口地址：https://api.typesafe.ai/v1/systemone。这是接口域名，不是网页，浏览器打开只会拿到 404。
- 文档站：docs.typesafe.ai。字段定义、SDK 用法、置信度算法、二十多个 cookbook 都在这儿，写代码时以它为准。
Key 的获取路径是控制台左侧的 API Keys，点 Create key，起个方便辨认的名字（例如 jev-demo）后确认。完整 Key 只显示一次，弹窗里先点 Copy 存好，再点 Done；丢了只能删除重建。另外提醒一句，登录控制台用的是 Google 授权或邮箱验证码，官方没有密码这一环。
拿到 Key 之后别写死在代码里，官方示例统一用环境变量 TYPESAFE_API_KEY。Python SDK 会自动读这个变量，不需要手动传参。
Jev API 的完整调用流程
五步能跑通，前四步都在控制台完成，第五步才轮到写代码。
- 打开 console.typesafe.ai，用 Google 账号或邮箱验证码登录。
- 进 Playground 先试一次。粘一段文本当 state，加一个问题，看返回长什么样。这是官方唯一的零代码入口，也是理解"它不做对话"最快的方式。
- 立即保存完整 Key。它只显示一次，先 Copy 再 Done，顺序别反。
- 把 Key 写进环境变量 TYPESAFE_API_KEY，发第一次请求。
请求体的三个字段
接口只认三样东西，多写的字段不会生效：
| | |
|---|
| | 要判断的材料。可以是一段文本，也可以是聊天记录、业务记录这类结构化数据。没写进去的内容它不会知道，也不会自己上网补上下文。 |
| | 填 jev-latest，或锁定版本号 jev-1.13.0。 |
| | 你出的题。键名自己定，答案会按同样的键返回。键名不参与推理，完整问句必须写进 instructions。 |
请求头两行：Authorization: Bearer 加完整 Key，以及 Content-Type: application/json。最小的可用请求长这样：
三种题型的写法与返回结构
题型只有三种，选哪种取决于你要什么形状的答案。三者可以混在同一次请求里。
| | | |
|---|
| | | criteria 可选，用来说明"是"和"否"各指什么 |
| | choice、probabilities、confidence | |
| | score、legend、probabilities、confidence | |
三个判断打包进一次调用，是官方推荐的写法。state 只传一次，问题并行评估，彼此之间不会互相污染。下面这段同时问出"该转给哪个部门""语气有多激动""是否紧急"：
返回里每个答案都带 type，和你的问题一一对应。Score 会额外给一个 legend，把档位编号映射回你写的描述，省得自己在代码里维护一张对照表。usage 字段记录本次的输入与输出 token 数，对账时用得上。
遇到复杂判断，instructions 和 criteria 可以不写字符串而写成 JSON。官方给了一个典型用法：把待核对的数据放在一个键下，再在问题里用反引号引用它。比如检查两份简历是否同一个人，可以把姓名、地点、上一家公司放进 potential_duplicate，然后问"这份简历和 potential_duplicate 是同一个人吗"。分类层级很深时也有对应的走法——每层问一次 Choice，把子节点当选项，在代码里一层层走树。
置信度阈值怎么设
Choice 和 Score 的返回里都有 confidence，取值 0 到 1。它不是一个独立判断，而是把 probabilities 那个概率分布压成一个数：所有概率都堆在同一个选项上，confidence 就接近 1；几个选项平分，confidence 就掉下来。
官方推荐的起点是把 confidence 划成三段：高置信度直接执行，中等置信度先确认或抓去复核，低置信度不执行、转人工。官方文档里两个示例页用的具体数值略有差别，一处写的分界是 0.5，另一处的语音银行例子用的是 0.6 保底、0.85 以上才允许放行转账。差别在于场景风险不同——查余额错了顶多重听一遍，转账错了不可逆。
照抄某一组数字没有意义。官方的说法是先用保守阈值，再拿自己的真实数据测一遍调。同一条阈值线不应该管所有动作：只读操作和写操作的风险不同，阈值就该不同。
Jev API 的模型规格与价格
官方目前只提供一个模型，所有请求走同一个端点，靠 model 字段选版本。下表整理自官方 Models 页：
| |
|---|
| |
| jev-latest 指向最新稳定版，也是官方 SDK 的默认值；jev-preview 指向最新发布，官方注明它目前与 jev-latest 指向同一个模型 |
| 单次请求 64k tokens；其中 state 与最长的那一个问题合计不超过 32k |
| 仅文本，可为字符串、JSON 对象或文本数组；不支持图片、音频、视频 |
| 英文。CJK 文本可以处理，官方明确说准确率不等同于英文 |
| 端到端 70 到 500 毫秒；官方称多数查询在 100 毫秒左右 |
价格只有两行，因为只收一侧的钱：
| | |
|---|
| $0.042 / 百万 tokens（即 $42 / 十亿 tokens） | 按 state 与 questions 的输入总量计 |
| | 官方原文为 too cheap to meter，Jev 不产生成段文字 |
官网首页那句"快 193.6 倍、便宜 444.6 倍"值得单独说一句。按官方博客自己的说明，这组数字来自 TypeSafe 设计的 workflow 评测里的最大差距，参考答案取 GPT-6 Astra 与 Fable 5.1 的平均值，官方同时写明评测任务由自家能力团队设计、"可能存在偏差"，并认为它处在真实收益区间的高位。这属于厂商自评口径，第三方复现未必一样，当量级参考比当结论稳妥。
至于别名要不要固定，官方给的建议是：如果你已经针对某个版本调好了置信度阈值，就写死版本号，等自己准备好再升级；用别名的话，新版本发布后答案口径可能在你没改代码的情况下变化。model 字段会回传实际作答的版本号，方便你记录每个结果出自哪一版。
Jev API 的调用限制与计费规则
限流的有两个维度，任一超线都会返回 429：每秒 250,000 tokens，以及每分钟 1,200 个请求。官方在 Models 页挂了一条提醒，说限额正在动态调整——原话是官方目前服务的需求量非常大，数字可能在不通知的情况下变化，等算力落地、放开更多用户后再给更稳定的限额。需要更高配额走 sales@typesafe.ai。
计费只算输入。因为输出那一侧几乎不产生内容，官方干脆标成免费，这带来一个反直觉的省钱办法：能一次问完的，就别分两次。state 只传一次、只算一次钱，而问题并行评估，加问题对响应时间几乎没有影响。官方给过一个实测数字，把 13 个问题打包进一次调用，比拆成 13 次顺序调用便宜 12.2 倍、快 10 倍，答案完全一样。
顺着这个逻辑，官方还在文档里专门写了一个模式：推测性提问。分类、严重程度、是否需要退款这些判断，即便其中几个只有在特定分支下才有用，也全部塞进同一次请求，拿到结果后由代码决定忽略哪些。多问的那个问题几乎不花钱，省下的是一次多余的往返。
账户余额、充值入口和自动充值开关都在控制台的账单页。另外提醒一点：网上流传"注册就送 X 美元额度"的说法，截至本文核查时间，官方文档与 Models 页都没有公示具体数额，也没有给出赠送政策的书面说明，实际以控制台账单页显示为准。
Jev API 常见报错与排查
HTTP 层一共四个状态码，官方给的定义很直接：
| | |
|---|
| | 检查请求头是否带了 Bearer 加完整 Key，环境变量有没有读到 |
| 请求体校验失败，例如缺必填字段、question 结构写错 | |
| | |
| | |
调用方式上的坑，官方在 Agent skill 文档里也列了几条：
- 用编程 Agent 时 skill 没被调用。Claude Code 里可以直接调 /typesafe:typesafe-ai；其他 Agent 明确说一句"use the TypeSafe skill"。仍不生效就确认安装时选对了 Agent，然后重启。
- Agent 编造请求或响应字段。多半是本地 skill 版本过旧，按原安装方式更新后重试。
- 到处都在设置信度阈值。如果只是要挑最优项，取概率最高那个就行；真需要统计判断时应该用 probabilities 而不是 confidence。
- 路由结果不对。先查问题和阈值，阈值高会漏判、低会误判，问题写得太宽也会。
- 代码不好审。把问题定义和阈值常量集中在一个文件里，审这一个就够。
Jev API 调用的注意事项与已知短板
官方单独写了一页 "Jev isn't perfect"，把 1.13 版已知的失败模式逐条列出，页面标注最后复核时间为 2026 年 9 月 17 日。动手接之前建议读完，它比大多数教程都诚实。
- 别让它做算术和计数。官方原文写明 Jev 不是计算器、数数并不可靠，数一个词里有几个字母、一段话里出现几次某个词都会出错，错误随被计数对象变大而上升。这类逻辑放代码里。
- 日期要拆开处理。Jev 把日期当文本读，不当作有序数值，比较先后、算间隔、判断是否落在区间都不可靠。提取交给它，排序和加减留在代码里。
- state 里别塞无关内容。无关细节会变成干扰项，官方明说 Jev 存在上下文退化（context rot），state 越大越容易答错，只传这次判断真正需要的字段。
- 一个问题只问一个判断。"分析这段内容并给出最佳方案"这类问法超出它的范围，要拆成多个小问题，再在代码里加权合并。
- 别写双重否定和多重嵌套。需要绕两层才读懂的问法，准确率明显下滑。
- instructions 和 criteria 要一致。如果 Noul 里把 true 对应成"否"、false 对应成"是"，表现会变差。
- 别指望跨问题的算术恒等式。同一个意思用 Noul 和 Choice 问，答案不一定对得上；官方实测里两个互补问题各自的概率可以加总到 1.19，两者不能互相换算，也不要套用同一套阈值。
- 不返回 confidence 的题型别硬凑。Noul 只给一个 0 到 1 的概率，没有 confidence 字段。它的 0.5 表示是、否各占一半，不表示"程度中等"。
- 别把输出直接发给用户。Jev 吐的是结构化字段，不是给人看的文案。告诉你是"退款类"之后，安抚信还得由模板或通用大模型来写。
- 官方说"零幻觉"指的是不越界，不是判断一定对。输出被约束在你给的选项里，不会冒出范围外的值，但选错仍然可能发生。
Jev API 调用常见问题解答
Q：Jev API 的接口地址和请求方式是什么？
A：POST https://api.typesafe.ai/v1/systemone，请求头带 Bearer 鉴权，body 传 JSON。这是接口地址，不是网页。
Q：调用前需要准备什么？
A：一个控制台账号（Google 授权或邮箱验证码登录）和一把 API Key。Key 在 console.typesafe.ai 的 API Keys 页面创建，只显示一次。
Q：一次请求最多能带多少个问题？
A：官方没有给出问题数量的硬上限，问题并行评估、彼此隔离。真正的约束在别处：单个请求的上下文共 64k tokens，其中 state 加最长的一个问题不得超过 32k；Choice 单个最多 255 个选项，Score 最多 10 档。
Q：confidence 和 probabilities 有什么区别？
A：probabilities 是完整的概率分布，每个选项或档位各占多少；confidence 是官方把这个分布压成的一个 0 到 1 的数，方便你直接拿阈值判断。官方也说明这个统计算法不是唯一正确答案，需要精细处理时应该用完整的 probabilities 自己算。
Q：为什么 Noul 题型没有 confidence？
A：官方设计如此。Noul 返回的本来就是"是"的概率，本身就是你要的那个数；Choice 和 Score 才需要额外压一个 confidence 出来。
Q：Jev API 支持中文输入吗？
A：支持。但英文是主训练语言，官方明确说 CJK 等语言准确率不等同于英文，中文业务建议先抽几十条真实样本测一遍再依赖它做判断。
Q：Jev API 免费吗？怎么计费？
A：输出免费，输入按 $0.042 每百万 tokens 计费，纯按量、没有订阅套餐。是否有新账号赠送额度，以控制台账单页显示为准。
Q：怎么决定哪类结果可以自动执行？
A：用 confidence 分级。低置信度转人工，中等置信度先确认，高置信度才自动放行；不可逆的操作（删除、转账）要把线划得比只读操作高得多。具体数值要拿自己的数据测出来。
Q：出问题或者想反馈，联系官方哪个渠道？
A：配额与商务问题走 sales@typesafe.ai，数据与隐私相关走 privacy@typesafe.ai，通用邮箱是 hello@typesafe.ai，官方也运营着 Discord 社区，文档里那几个失败模式页面就在征集反馈。
把这套调用跑起来不难，难的是置信度那条线——官方唯一没有替你决定的东西就是阈值，它必须由你自己的数据画出来。Jev 的版本号、单价和限流都在随官方调整，正式接入前记得回文档站确认当期口径。后续 Jev 若有新的题型或接口变更，本站 AI 工具栏目会同步更新。
AI 速览
