跳转到主要内容
POST
Jev

简介

Jev 是 TypeSafe 推出的 System One 决策模型。它和对话模型不同,不生成文字,而是对你给出的内容(state)回答一组限定了答案范围的问题(questions),直接返回程序可以使用的结构化结果:
  • 单选(choice):从你定义的选项里选一个,如「这张工单该分给哪个部门」。
  • 打分(score):按你定义的档位打分,如「用户情绪有多激动:0 平静 / 1 不满 / 2 愤怒」。
  • 是非(noul):返回「是」的概率,如「用户是否在要求退款」。
  • 框选(box):在图片里找到描述的目标,返回它的上下左右四条边,如「找出车身上的划痕」。
一次请求可以同时问多个问题,内容只读一遍,每个问题独立作答。单选、打分和框选答案带置信度,是非答案返回概率,适合用来做工单分流、内容审核、情绪打分、意图识别、Agent 工具调用把关、模型路由等「快速判断」场景。
请求结构与成功响应的业务字段遵循 TypeSafe 官方 System One API。错误响应可能由平台封装,详见 错误处理。
Jev 不支持 OpenAI 的 /v1/chat/completions、/v1/responses 等对话接口,只能通过下文的 /v1/systemone 调用。它不会写回复、写代码或解释推理过程。

认证

string
必填
Bearer Token,如 Bearer sk-xxxxxxxxxx
string
必填
application/json;用 multipart 上传图片时为 multipart/form-data,见 multipart 上传图片
string
固定为 true。按官方规范,请求里带图片(assets)或框选题(box)时必须传。
string
固定为 true。打开长上下文模式,上下文上限从 64k 提到 262k,详见 上下文长度。
API Key 在平台的 API 密钥页面创建。请勿将 API Key 写入前端代码、公开仓库或客户端安装包。

模型信息

  • jev-latest、jev-preview 是别名,官方发布新版本后会自动指向新版本,答案可能随之变化。响应里的 model 字段是实际作答的版本号。
  • 如果你已经按某个版本调好了置信度阈值,建议直接用固定版本号,确认新版本效果后再切换。

接口地址

请求参数

Jev 没有 temperature、max_tokens 这类采样参数,也不需要设置输出长度。

state

需要判断的内容,三种写法任选:
  • 字符串:一段文本,如用户消息、工单内容、合同全文。
  • 对象:结构化数据,如 {"subject": "重复扣款", "message": "请帮我处理"},适合把用户消息、订单记录、处理规则一起交给模型。
  • 数组:多段文本,如一组聊天记录。

questions

问题集合。键是你自定义的问题名,响应的 answers 用同样的名字返回答案;值是问题定义:
  • 问题之间相互独立,每个问题都单独针对 state 作答,不会看到其他问题的答案。
  • 选项说明和档位说明写得越具体,判断越稳定;选项之间尽量不要重叠。

assets

图片集合。键是你自定义的占位符(建议每张图用一个 UUID),值是图片定义。占位符出现在 state、问题的 instructions 或 criteria 里的任何字符串中时,会被替换成对应的图片。 下面示例使用一张 280 × 280 的白底红色矩形 PNG,可用于后面的图片判断和框选示例。请勿替换为低于最小尺寸的占位图片。
按官方规范,请求里带 assets 时必须同时带请求头 TypeSafe-Danger-Zone-Images: true。图片输入和框选题是官方标注的早期功能,请求格式、答案和限制可能随版本变化。

图片限制

图片需同时满足以下 官方限制,不符合尺寸要求时不会自动缩放,而是整次请求失败: 每个 asset 都必须在 state、instructions 或 criteria 中被引用。图片过小、格式无效、未被引用等问题通常返回 400;超出文件、尺寸或请求大小上限可能返回 413。

multipart 上传图片

图片较大或较多时,可以用 multipart/form-data 上传原始图片,不用转 Base64:
  • 第一段名为 request,内容是 JSON 请求体(Content-Type: application/json)。
  • 之后每张图片单独一段,段名唯一、不能为空,并且必须被某个 asset 的 part 引用。

上下文长度

每个请求要同时满足两个上限:
  • 超出上限时上游返回 400,错误信息为 max_tokens_exceeded。
  • 需要处理长合同、长对话记录时,在请求头带 TypeSafe-Danger-Zone-Long-Context: true。长上下文单价不变,但速度更慢、准确率略低,只在确实需要时打开。

调用示例

成功返回

框选题的答案

返回字段

怎么用置信度:概率和置信度是校准过的,适合设阈值做自动决策。例如 noul ≥ 0.8 自动处理、0.2 ~ 0.8 转人工复核、< 0.2 直接放行。阈值建议用一批人工标注过的样本调出来。

计费说明

计费公式:单次费用 = usage.input_tokens / 1,000,000 × 输入单价
  • 以上为官方基础价,实际扣费再乘以令牌所在分组的倍率,以模型广场展示的价格为准。
  • 输入 token 包含 state、全部问题说明、选项和档位说明;带图片时也包含图片对应的 token。
  • 响应里的 output_tokens 只做展示,当前不计费。
  • 开启长上下文不改变单价,只是允许更长的输入。
示例:上面「多题一起问」的请求返回 input_tokens: 443,费用为 443 / 1,000,000 × 0.042 ≈ 0.0000186 美元,也就是每 1 万次这样的请求约 0.19 美元。

错误处理

请求失败时返回 JSON 错误对象。平台可能封装上游错误,message 有时包含具体原因,有时仅为 openai_error,不能仅凭该字段判断失败原因。以下为错误格式示例:
官方接口的参数校验失败可能返回 422,而网关可能返回 400 并使用 error 对象封装。应先检查 HTTP 状态码,再读取响应中的错误字段;不要假设所有网关都原样返回官方的 detail 结构或具体错误信息。
常见问题:

官方参考