Jev 图像输入与 Box 题:怎么传图、怎么读边界框

更新于 适用版本 Jev 1.14

这个站之前的每一篇教程,都把 Jev 当成纯文本引擎写:往 state 里塞文本,问 Choice、Score、Noul 三种题,拿回结构化答案。就那三种原语而言,这个描述是准确的,几乎所有教程也都是这么重复的。但它并不完整。

Jev 能读图。1.13 就能读,不只有 1.14;一张图能放在请求里的三个不同位置;从 1.14 起还多了第四种题型 Box,专门回答「东西在图里的哪儿」。这一页补的就是缺的那一章:你到底发出去什么、拿回来什么、硬限制在哪、以及官方公布的实测数据到底说明这套东西现在能不能用。

本文没有一个数字是推的。全部来自 2026-11-11 当天读的 TypeSafe 官方文档,加一次对 OpenRouter 模型目录的实时读取。凡是文档和目录对同一件事说法不同的地方,两边原文都列出来。

一句话版本

一个带图的请求,就是普通 System One 请求加两样东西:一个顶层 assets 映射存放图像,以及写在图像该出现位置的引用字符串。再加请求头 TypeSafe-Danger-Zone-Images: true,漏了就 400。Box 题只吃 type 和 instructions 两个字段,返回 {top, bottom, left, right} 四个比例值加一个 confidence,而且永远返回框——目标不在也返回,所以官方文档要求你配一道 Noul 兜住。

1.13 也能读图

这一点最容易先搞错,因为 1.14 的发布说明把图像和 Box 写在同一段里。官方 changelog 是分开列的:

图像那一页也重复了一遍:「Jev 1.13 and Jev 1.14 both accept images. Box questions need Jev 1.14.」models 表格是一致的——两行的输入都是「Text, images」,题型行才是 1.14 有 Box、1.13 没有。

实际后果:如果你的项目钉在 1.13,只需要传图,那你根本不用升版本。你需要的是那个请求头,以及接受自己没有任何办法问「位置」。

版本门槛之上还有第三道门:图像和 Box 默认关闭,每个带图像或 Box 的请求都要带那个头。错误表把漏头写成一条独立的 400——「Images are not turned on: the request has an image or a Box question but no TypeSafe-Danger-Zone-Images: true header.」

assets 映射与引用规则

你永远不会把图内联成 data URL 塞进提示词字符串。做法是:每张图在顶层 assets 对象里登记一次,键是你自己起的引用字符串;然后在图像该出现的地方写同一个字符串。

{
  "model": "jev-latest",
  "state": { "photo": "a3f1c2e8-found" },
  "assets": {
    "a3f1c2e8-found": { "type": "image", "format": "jpg", "data_base64": "/9j/4AAQSkZJRg..." },
    "77b0d4a1-poster": { "type": "image", "format": "jpg", "data_base64": "/9j/4AAQSkZJRg..." }
  },
  "questions": {
    "same_dog": {
      "type": "noul",
      "instructions": "Is the dog in `photo` the same dog as in this picture: 77b0d4a1-poster?"
    }
  }
}

上面这个例子是官方「三个位置」示意图的简化版。引用 a3f1c2e8-found 作为 state.photo 的整个值出现;77b0d4a1-poster 则嵌在一道 Noul 的 instructions 句子中间。第三个位置——Choice 选项的 description——下面再讲。

一个 asset 条目最多四个字段。type 可选,写了就必须是 "image"。part 是 multipart 请求里的文件分部名。data_base64 是文件本体,标准 base64 字母表、= 补齐、不带任何空白、不带 data: 前缀。format 是 "png"、"jpg" 或 "jpeg",小写,配 data_base64 时必填,配 part 时可选。若某个 asset 同时带了 part 和 data_base64,API 用 part。

引用规则是请求翻车的地方,官方把每一条都写明:

第四条是最费钱的一条。一张处理后 10 MiB 的图,被引用四次,展开后就是 40 MiB,还没发出去就已经超过 32 MiB 上限。

图像能放的三处,区别很实在

放在 state

state 里的图像就是 state 的一部分,和字符串、JSON 字段没有区别。请求里的每一道题都会拿它当上下文,所以多道题共用一张图时,这里是最便宜的位置。state 可以图文混排,也可以放多张图,带标签或嵌套——官方例子是一小段摄像头帧历史:

{
  "state": {
    "frames": [
      { "seconds_ago": 2, "frame": "5c0e9a12-f1" },
      { "seconds_ago": 1, "frame": "1d7be0c4-f2" },
      { "seconds_ago": 0, "frame": "e48a6f30-f3" }
    ]
  }
}

题可以问整个数组(「Did the door in frames open during these frames?」),也可以用路径点名其中一帧,比如 `frames[2].frame`。

放在 instructions

某道题的 instructions 里的图,属于这道题,只随这道题发送。官方用例是对比——图在 state 一张,参照图在题里一张:

Is the person in door the same person as in this badge photo: 9a21c7d3-badge?

成本提醒是明写的:instructions 里的图,会被包含它的每一道题各发一次。多道题要用同一张图时,把它放进 state 一次、各题按路径引用——token 更少,体积预算也更省。

放在 criteria

Choice 的选项、Score 的等级、Noul 的 true/false 定义都能带图。这就是「用范例定义选项」的模式,也是 Jev 用图最有意思的一处——模型不是被要求描述图片,而是被要求判断输入和你给的哪张范例图匹配。

{
  "model": "jev-latest",
  "state": { "camera": "e48a6f30-cam" },
  "questions": {
    "gesture": {
      "type": "choice",
      "instructions": "Which gesture is the hand in `camera` making?",
      "criteria": {
        "thumbs_up": "0b6c51aa-thumb",
        "open_palm": {
          "description": "A hand held up with the palm facing the camera.",
          "examples": ["4fd2e7b9-palm1", "c83a0e15-palm2"]
        },
        "fist": "a7e94d02-fist",
        "none": "No hand, or a hand that matches none of the examples."
      }
    }
  }
}

一个选项可以是单独一张图,可以是「一段描述 + 一到多张范例图」,也可以纯文本。注意 description 和 examples 是这个示例里自己起的字段名,不是必填字段——criteria 接受任意结构。Score 每个等级可以带一张范例图;Noul 可以用图定义 true 和 false:{"true": {"description": "Correctly assembled", "examples": ["<reference>"]}, "false": "Parts missing or in the wrong place."}。

官方把整个设计空间归纳成六种模式。写请求之前先想清楚自己在哪一种:

模式做什么图放哪
与已知图片比对是不是同一个人/同一件商品/同一个地点已知图放 instructions,待测图放 state
用范例定义选项每个 Choice 选项配一张或几张范例图criteria
什么地方变了送上一帧或一小段帧历史,问运动、到达、差异state
需要时再看清一点先在小图上问,只有答案需要细节时才送大图或全分辨率裁剪state
在大图里搜索切成瓦片,用瓦片当选项问 Choice,在选中的瓦片上递归criteria
找它在哪用 Box 题要四条边state,可选把目标样例图放 instructions

Box:第四种题型

Box 题只有两个字段。type 恒为 "box"。instructions 说明找什么、在哪张图里找——而且它不必是个问句,官方示例就是片段「the coffee mug in photo」。Box 不接受 criteria。

curl https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer ***" \
  -H "TypeSafe-Danger-Zone-Images: true" \
  -F 'request={
    "model": "jev-latest",
    "state": {"photo": "6e1d0b7c-kitchen"},
    "assets": {"6e1d0b7c-kitchen": {"type": "image", "part": "kitchen-photo"}},
    "questions": {
      "mug": {"type": "box", "instructions": "the coffee mug in `photo`"}
    }
  };type=application/json' \
  -F 'kitchen-photo=@kitchen.jpg;type=image/jpeg'

返回里有一个 box 对象和一个 confidence:

{
  "model": "jev-1.14.0",
  "answers": {
    "mug": {
      "type": "box",
      "box": { "top": 0.25, "bottom": 0.82, "left": 0.44, "right": 0.84 },
      "confidence": 0.92
    }
  },
  "usage": { "input_tokens": 290, "output_tokens": 21 }
}

left 恒小于 right,top 恒小于 bottom。四个数都是 0 到 1 的比例,从左上角量起——left、right 相对图像宽度,top、bottom 相对高度。这个归一化正是「同一个答案在任何分辨率都成立」的原因:把每条边乘上对应像素尺寸,就得到一个裁剪框。

from PIL import Image

image = Image.open("kitchen.jpg")
width, height = image.size
mug = response["answers"]["mug"]
edges = mug["box"]

box = (
    round(edges["left"] * width),
    round(edges["top"] * height),
    round(edges["right"] * width),
    round(edges["bottom"] * height),
)
image.crop(box).save("mug.jpg")

永远返回一个框,这是坑

Box 答案永远是个框,没有「未找到」。你在一张没有马克杯的照片里问马克杯在哪,照样得到四条边,外加一个置信度。

官方对策是在同一个请求里再问一道 Noul 当闸门:

"questions": {
  "mug_visible": { "type": "noul", "instructions": "Is there a coffee mug in `photo`?" },
  "mug": { "type": "box", "instructions": "the coffee mug in `photo`" }
}

然后 mug_visible 低的时候就把框丢掉。两道题对着同一份 state 在一次请求里算完,所以这个闸门的代价是一道题,不是一次往返。

Box 那一页还有三条值得背下来的规则。一道题一个框——Box 设计上只找一个目标,要找几个就写几道题。图里可能有多个同类时,用语言把目标描述到只剩一个:「the mug nearest the sink in photo」。找小东西之前先裁——几像素宽的目标在超大图里会被漏掉,所以先定位区域(比如用瓦片当选项问一道 Choice),再在那块瓦片上问 Box,最后把边换算回整图比例。

另外,官方没有给出推荐的置信度阈值,明确说要拿你自己的图去调,并给了置信度偏低时的两条出路:换更好的图重新问(更大的一版,或者围绕框做一次高分辨率裁剪再问同一道 Box),以及在裁剪前把框向外扩,免得裁掉目标的一部分。

硬限制

这些是拒绝阈值,不是自动缩放建议。超出范围的图会被拒,API 不会帮你缩小。

限制值
格式仅 PNG 或 JPEG,仅静态图。动图 PNG 会被拒。
单文件大小每张图 16 MiB(base64 解码后的体积)
宽高每条边 280 到 1568 像素,任一边低于 280 即被拒
总像素78,400 到 2,458,624(即 280×280 到 1568×1568 的正方形面积)
请求体32 MiB,含 JSON、base64 文本和 multipart 分帧;请求头不算,压缩也不会放宽
请求内全部图像32 MiB,按处理后的每张不同图像合计
展开后请求32 MiB,指所有引用被替换成图像之后的体积
引用字符串单个 1,024 字节,合计 65,536 字节

所有区间两端都含。请求里任何一张图被拒,整个请求失败,没有部分答案。一次请求能放几张图,取决于上面这些限制和上下文长度,不存在单独的图像配额:图像没有独立限流,和文本共用同一套请求限制。

「处理之后」那一行尤其要看。处理过程会重新编码每张图,可能比你发出去的文件更大,所以一堆看起来不大的上传,合起来仍然可能超预算。

发图之前怎么准备

官方给了六条,每一条都对应一类具体的拒绝:

官方那段 Pillow 代码把前两条一起做了:

from PIL import Image, ImageOps

with Image.open("photo.jpg") as original:
    img = ImageOps.exif_transpose(original)   # 把像素转正
    img.thumbnail((1568, 1568))               # 最长边压到 1568 以内
    # thumbnail 只会缩小:低于下限的图要另外放大或补边
    img.convert("RGB").save("photo-ready.jpg", "JPEG", quality=90)  # baseline JPEG

用 multipart 时,JSON 主体作为第一个分部,名字必须叫 request,content type 为 application/json;每张图各自一个文件分部,asset 的 part 字段要写出那个分部名。分部名必须唯一且非空,request 是保留名,图像分部的 content type 只能是 image/png、image/jpeg、image/jpg、application/octet-stream 或者不写;没有被任何 asset 引用的分部、以及指不到分部的 asset,都返回 400。

到底行不行?看官方实测数据

有两份 cookbook 给了实测结果,这是整份文档里最有参考价值的部分——如果你正在决定要不要基于这套东西开工的话。

OCR 校验那份,对两张手机拍的供应商发票跑三段式流水线:第一段每字段两道题(一道 Box 定位,一道 Noul 判断抽取值是否对得上),第二段放大重定位,第三段每个裁剪区一道 Noul。以下结果来自 jev-1.14.0、2026-10-15,两条校验任一低于 0.25 即转人工:

发票字段抽取值实际印的整页校验裁剪校验
Milkwood发票号AN400074IN4000740.880.18
Siyakhula发票号INV03070INV030790.020.04
Siyakhula日期16/09/202816/09/20260.170.66

这张表要细看,因为有意思的结论不是「Jev 抓到了错」,而是单独任何一种校验都抓不全三个错。整页校验把误读的 AN400074 以 0.88 放过了,裁剪校验以 0.18 抓住它。裁剪校验把错年份以 0.66 放过了,整页校验以 0.17 抓住它。INV03070 两条都抓到了。两张发票上所有正确值都通过了两种校验,其中最低的是 0.35(Milkwood 账号,整页校验)和 0.31(Siyakhula 供应商名,裁剪校验)。

这个结果形态其实很有用:它说明两个角度都查比只查一个角度强,同时也说明 0.31 和 0.35 这两个「正确但偏低」的分数离 0.25 的线并不远,阈值一收紧就会开始误报好数据。所以官方那句「拿你自己的图去调」不是客套。

喂食器摄像头那份,每秒送一帧,每帧五道题——一道 Noul 判有没有鸟、一道 Choice 判没有/一只/多只、一道 Box 定位最显眼那只、两道 Choice 分别判最左和最右的物种。在它那段 101 秒素材上,Jev 对「有没有鸟」在全部 101 帧上都和人工标注一致,在 133 次标注的鸟类出现中判对物种 132 次。

第三份图像 cookbook 讲扫描版疫苗接种记录,是把「Choice 里带 unreadable 选项」用得最干净的示范:与其让 Box 或读数失败,不如把 unreadable 做成一个正式选项,这样被贴纸盖住的日期会作为一等答案返回,而不是靠猜。

走哪个渠道,模型目录怎么说

模型自己声明的能力,是和文档对照的好办法。2026-11-11 实时读 GET https://openrouter.ai/api/v1/models/typesafe/jev-1.14/endpoints,返回:

三个推论。目录独立确认了图像输入,也只确认了图像——没有音频、没有视频。它确认输出模态是 decisions 而不是 text,这正是为什么「用 OpenAI 兼容客户端带一张图发过去」和「一次图片聊天补全」不是同一件事。它还显示 262,144 是长上下文那个数字,不是默认值:models 页写的是每请求 64k、每题 32k,除非你发 TypeSafe-Danger-Zone-Long-Context: true。

计费和文本同轨。按每百万输入 token $0.042 算,官方那个示例的一次请求(一张图加一道 Box,290 输入 token)约 $0.0000122——但文档明说图像 token 估算指引「之后」才发布,所以别拿这个数字去做成本模型。

会坏在哪

诚实的总结就写在官方文档的头部标签上:Dreamer-ready。图像和 Box 还没达到 TypeSafe 敢称生产可用的标准,请求格式、答案形态和限制都可能随版本变,模型更新也会改变准确率。你的工作流受不了这种变动,就留一条纯文本通路。

报错面很小,而且都写了:

状态码原因
400有图像或 Box 题,但没带 TypeSafe-Danger-Zone-Images: true 头
400图像被拒:不是 PNG/JPEG、损坏、不完整、动图、低于最小尺寸,或 asset/format 有问题
400max_tokens_exceeded:图像加文本超出该请求的上下文长度
413撞了某个体积限制:单文件、宽高、总像素、请求体、全部图像、展开后请求,或引用长度

注意最后那条 400 的补救办法,写得具体又容易被忽略:图像把请求顶超上下文时,少发几张、发小一点,或者把图像从 instructions 挪到 state。如果多道题共用那张图,最后这个改动是免费的——和前面 token 提示说的是同一件事,只是这次是作为报错信息出现。

一个请求同时有多个问题时,报错只报其中一个,所以一次被拒不等于拿到了完整诊断。先对着限制表和准备步骤自查,再怀疑模型拒了你。

什么情况下别用 Box

三种用 Box 就错了的场景:

还有一种情况是「压根不该用图像」:有文字层的扫描件。文本抽取更便宜、更确定、可测试。官方动用图像的场合是信息本来就是视觉的——一个手势、一张工牌照片、喂食器上的一只鸟、一个必须在印刷位置上核对的值。

这一页和站内其他页的关系

本站的三原语那一页讲 Choice、Score、Noul 三种题型;Box 是第四种,也是唯一必须 1.14 的那种。请求模式那一页讲批量组合——投机扇出、Noul 预筛、按置信度路由——Box 和它们全部可以组合:Box 前面架一道 Noul 预筛,就是官方对付「永远返回框」的标准办法;把多道 Box 扇进一个请求,就是一次定位多个目标的做法。

如果还没发过第一个请求,从第一次 API 调用和 state 与提问两篇看起——图像只是给你已经会写的请求多加了两个字段,不是换了一种请求形态。

常见问题

+ Jev 能读图吗?

能。Jev 接受 PNG 和 JPEG,可以放在请求里任何能放文本的位置:state 的值、某道题的 instructions、某道题的 criteria。官方 models 页把 1.14 和 1.13 两行的输入都写成「Text, images」,所以传图不是 1.14 专属。音频和视频不支持。

+ 图没问题,为什么请求还是返回 400?

传图默认是关闭的。每个带图像或 Box 题的请求都必须加请求头 TypeSafe-Danger-Zone-Images: true。官方错误表对这一条写得很明确:请求里有图像或 Box 题但没有这个头,返回 400。

+ Box 题在 Jev 1.13 上能用吗?

不能。Box 是 1.14 changelog 里唯一一个必须 1.14 的能力。图像那条和长上下文那条都补了一句「This also works on Jev 1.13」,Box 那条没有。models 页的题型行也是:1.14 是 Choice、Score、Noul、Box,1.13 是 Choice、Score、Noul。

+ Box 题的返回值长什么样?

四条边加一个置信度,全是小数。官方示例返回 {top: 0.25, bottom: 0.82, left: 0.44, right: 0.84},confidence 0.92,usage 是 input_tokens 290、output_tokens 21。left/right 是相对图像宽度的比例,top/bottom 是相对高度的比例,都从左上角量起,所以同一个答案在任何分辨率下都成立。把每条边乘上对应像素尺寸就是裁剪框。

+ 要找的东西根本不在图里,会返回什么?

照样给你一个框。官方文档明说没有「未找到」这种答案,所以目标不存在时 Box 题仍然返回四条边。官方给的对策是在同一个请求里再问一道 Noul,比如「Is there a coffee mug in photo?」,Noul 概率低时就把这个框丢掉。

+ 图像能力现在能上生产吗?

官方文档直接回答了:图像和 Box 被标为 Dreamer-ready,定义是「还没达到我们敢称生产可用的标准」。请求格式、答案形态和限制都可能随版本变化,模型更新也会改变准确率。当原型功能用,任何不能坏的东西都留一条纯文本通路。

+ 图像怎么计费?

按输入 token 计费,走正常输入单价,没有单独的图像费用。官方说响应里的 usage.input_tokens 已经包含请求中每张图的 token,图像 token 也计入上下文长度。Jev 1.14 标价每十亿输入 token $42(即每百万 $0.042),输出免费;2026-11-11 实测 OpenRouter 的 typesafe/jev-1.14 端点,prompt 单价 0.000000042/token,completion 为 0。

继续阅读