Box

Box 把图片里的目标位置变成程序可以直接使用的矩形。例如定位快递标签、货架商品或表单签名。它是象信 3.0 正式支持的第四种问题类型，可以与 Noul、Choice、Score 放在同一个请求中。

定义问题

Box 只需要 type: "box" 和 instructions，不接受 criteria。instructions 写清目标和要搜索的图片路径；同图多个相似物体时，用位置、颜色或其他特征区分。

{
  "mug": {"type": "box", "instructions": "`photo` 中最靠近水槽的白色杯子"}
}

请求必须提供至少一张图片，使用 model: "xiangxin-3.0" 或 xiangxin-3.0.0。上传方式、base64 代码和完整 curl 示例见图片。不需要额外的开关请求头。Playground 提供图片上传、Box 模板及结果叠加预览。

参考目标本身也可以是一张图片：在 instructions 中直接写入该参考图的 asset 引用，再说明搜索哪张场景图。

返回坐标

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

四个数是相对于图片宽高的比例，原点在左上角。left、right 对应横向位置，top、bottom 对应纵向位置，范围均为 0–1，且 left < right、top < bottom。例如宽 1000、高 800 的图，上例对应左上角 (440, 200)、右下角 (840, 656)。

confidence 也是 0–1，代表模型对定位的把握。根据你自己的样本决定阈值，不要直接套用 Choice 或 Score 的概率分布公式。

转成像素与裁剪

from PIL import Image

image = Image.open("kitchen.jpg")
answer = response.json()["answers"]["mug"]
edges = answer["box"]
width, height = image.size
image.crop((
    round(edges["left"] * width),
    round(edges["top"] * height),
    round(edges["right"] * width),
    round(edges["bottom"] * height),
)).save("mug-crop.jpg")

绘制矩形时，宽为 (right-left) × 图片宽度，高为 (bottom-top) × 图片高度。先把原图方向处理好再上传，以免显示与坐标方向不一致。

先确认存在，再使用位置

Box 始终返回一个框，没有 null 或“未找到”这一分支。目标不存在时仍会返回坐标，所以业务上应搭配一题 Noul：

{
  "visible": {"type": "noul", "instructions": "`photo` 中有白色杯子吗？"},
  "mug": {"type": "box", "instructions": "`photo` 中的白色杯子"}
}

代码只有在 visible.noul 达到你设定的存在性阈值时才采用 mug.box。两题在一次请求中独立求值，无须先后调用。

定位建议

• 一题定位一个目标。要找签名和印章，就各写一题 Box。
• 同类物体有多个时明确描述目标，例如“最左边的杯子”。还可以并行用 Choice 区分“没有 / 一个 / 多个”，让代码选择下一步。
• 小目标先定位大区域，再裁剪到区域内继续查询；新框的坐标相对于裁剪图，合并时要换算回原图。
• 对裁剪完整性敏感的业务可以把四边向外留出余量，并限制在 0–1 内。
• 检查是否切断目标时，对裁剪图分别询问上、下、左、右四边是否还有目标延伸；必要时扩大对应边界再检查。

多图请求中，要在 instructions 写明目标所在的图片路径。参考图用于说明“找什么”，场景图用于说明“在哪里找”。图片复用和嵌套引用见图片放在哪里，判断阈值的应用方式见置信度。