后处理

POST /v1/segment、POST /v1/refine 和批量分割在构建响应之前，会在服务端对每个实例做后处理。后处理免费且结果确定：同一请求在同一图片上得到同样的结果。默认情况下，每个实例带有含洞的简化多边形，坐标为摆正后的原图的像素，不带蒙版。

选项放在哪里

选项	层级	含义
geometry	defaults、提示	["polygon"]（默认）、["mask"]、两者都要，或 []（只要框和分数）
polygon	defaults、提示	tolerance（默认图片对角线的 0.001）或 tolerancePx，holes（默认 true），maxParts（1 至 64）
mask	defaults、提示	encoding：coco（默认）或 webp
filter	defaults、提示	minScore（默认 0.5）、minSize、minArea；仅用于搜索提示
cleanup	defaults、提示	dropFragments 和 fillHoles，默认均为图片面积的 0.0001
merge	defaults、提示	true 把同一 group 的实例合并为一个
group	提示	把多个提示关联起来的名称，用于 nms 和 merge
maxInstances	请求	返回的搜索实例数，1 至 300，默认 100
nms	请求	重叠去除：iou（0.7）、metric（mask 或 box）、scope（group 或 all）
maskSize	请求	蒙版网格的长边，64 至 4096，默认 2048
report	请求	droppedBoxes 返回 dropped；lowScoreFloor 限定低分的计数和列出范围

options.defaults 作用于所有提示，prompts[].options 为单个提示覆盖它。每个字段依次取内置默认值、options.defaults、提示自己的 options。对象（polygon、mask、filter、cleanup）按字段合并，因此设置 polygon.tolerance 不影响 polygon.holes。数组（geometry）和阈值对象（minSize、minArea、dropFragments、fillHoles）整体替换，null 关闭阈值。tolerance 和 tolerancePx 是同一项设置：在同一对象中同时给出返回 400 invalid_request，更具体的一层优先。

提示分为搜索提示（sam3 文本提示，或没有文本提示时的样例框）和物体提示（sam3 点，sam-lite 框和点）。filter 和 nms 只作用于搜索提示，在物体提示上设置 filter 返回 400 invalid_request。物体提示的实例总是返回，不计入 maxInstances。与文本提示一起使用的样例框不带 group 和 options。

合并。 提示的 merge 为 true 的实例按 group 合并为一个实例：蒙版取并集，score 取最高值，prompt 取最小值（其 label 和输出选项生效），bbox 和 area 为并集的值，merged 为合并的实例数。组内只有一个此类实例时，原样返回。

处理顺序

每一步只处理上一步保留下来的内容。括号中是该步骤丢弃的内容在 dropStats 中对应的计数器。

1. 分数：低于 filter.minScore 的搜索候选被丢弃（lowScore）。每个请求最多 300 个候选按分数顺序继续（limit）。
2. 清理每个实例的碎片和小洞（cleanup）。
3. 尺寸：先 filter.minSize（tooSmall），再 filter.minArea（tooSmallArea），均针对清理后的实例。
4. 重叠：nms（overlap）。
5. 在每个 group 内合并。
6. 数量：保留分数顺序中前 maxInstances 个搜索实例（limit）。
7. 几何输出，然后应用下文的响应限制。

每一步和 instances 使用的分数顺序为：score 降序，然后 prompt 升序，然后模型候选的顺序。

尺寸过滤与贴边模式

minSize 针对清理后实例的紧致框：ratio（图片短边的比例）和 px 二选一。框的某一边短于阈值 s 即为过小。minArea 是 area 的阈值：ratio（图片面积的比例）和 px 二选一。

被图片边界截断的物体看起来会比实际小。框的边缘与图片边界的距离在 edgeTolerancePx（默认 1）以内时视为贴边，border 决定如何判断这样的框。w 和 h 为框的宽和高，表中条件成立即为过小。

border	不贴边	仅水平贴边	仅垂直贴边	两者都贴
strict（默认）	min(w, h) < s	min(w, h) < s	min(w, h) < s	min(w, h) < s
directional	min(w, h) < s	h < s	w < s	从不
cornerLongSide	min(w, h) < s	h < s	w < s	max(w, h) < s
cornerShortSide	min(w, h) < s	h < s	w < s	min(w, h) < s

限制与降级标记

取决于图片内容的限制无法在调用运行前检查。它们按固定规则缩减输出，不会使调用失败，每次缩减都能在响应中看到。bbox、score 和 area 始终保留。

限制	数值	处理方式	标记
每个请求的提示数	50	400 invalid_request	无
每个请求的候选数	300	其余按分数顺序丢弃	dropStats.limit
maxInstances	1 至 300，默认 100	超出的搜索实例被丢弃	dropStats.limit
每个实例的顶点数	8,192	容差翻倍，最多 6 次，起点为请求值与 1 px 中的较大者；之后保留最大的若干部分；最大的部分单独超限时，实例没有 polygon	实例上的 tolerancePx，或 omitted: vertices
每个响应的几何数据量	4 MiB	每个顶点计 4 字节，加上 counts 的长度和 WebP 的大小。从分数顺序中第一个放不下的实例起，实例不带几何数据	omitted: budget、dropStats.budget
每个响应的 WebP 像素	32 百万像素	从第一个放不下的裁剪区域起，蒙版改为 coco 返回	mask.encoding
dropped 条目	300	分数高的在前	无

示例

每个提示使用不同的 minScore，并对其中一个加尺寸过滤：

{
  "model": "sam3",
  "image": { "id": "img_..." },
  "prompts": [
    { "text": "car", "options": { "filter": { "minScore": 0.7 } } },
    { "text": "person", "options": { "filter": { "minScore": 0.4, "minSize": { "px": 24 } } } }
  ],
  "options": { "maxInstances": 50 }
}

跨提示使用 group、nms 和 merge。sofa 与 couch 用两个名称找同一类物体，因此放在同一组，nms 丢弃每对重复实例中分数较低的一个。window 与 door 合并为一个 openings 实例，merged 为合并的实例数，prompt 为 2：

{
  "prompts": [
    { "text": "sofa", "group": "seat" },
    { "text": "couch", "group": "seat" },
    { "text": "window", "group": "openings", "options": { "merge": true } },
    { "text": "door", "group": "openings", "options": { "merge": true } }
  ],
  "options": { "nms": { "iou": 0.7 } }
}

为所有提示返回 COCO 蒙版，用 pycocotools 解码：

# body["options"] = {"defaults": {"geometry": ["mask"]}}
from pycocotools import mask as coco

m = instance["mask"]  # {"encoding": "coco", "size": [h, w], "counts": "..."}
pixels = coco.decode({"size": m["size"], "counts": m["counts"].encode()})  # h x w uint8，位于蒙版网格上

多边形、COCO 还是 WebP

输出	无损	实测大小	适用
polygon（默认）	否：简化后的轮廓	平均每实例 574 B（71 个顶点）；小物体 117 B，中等 317 B，大物体 1,087 B	显示、矢量编辑、几何运算
mask，coco	是，在蒙版网格上	约每实例 4.3 KB（100 个为 428 KB）	精确像素、pycocotools 流程
mask，webp	是，在蒙版网格上	约每实例 3.4 KB（100 个为 337 KB，含 base64）	发丝等极细致的轮廓，此时比 coco 小；生成较慢

多边形的大小为真实 SAM 3 蒙版在默认容差下的扁平整数 JSON。COCO 和 WebP 的大小为 100 个混合尺寸的合成蒙版在整图网格上的 JSON；绝对数值取决于轮廓，但比例成立。多边形字节随细节增加：容差为对角线的 0.0015 时每实例 356 B，0.0005 时 1,327 B。

默认容差为对角线的 0.001，是多边形相对精确蒙版仍满足质量门槛的最大比例，对象为中等和大物体：IoU 中位数不低于 0.98，第 5 百分位不低于 0.95，在 640、1280 和 2560 px 下均成立（640 px 下中位数为 0.988）。0.0015 两项都未通过（中位数 0.9785，第 5 百分位 0.9404）。默认值可能调整，因此对结果敏感时应显式设置 tolerance 或 tolerancePx。

mask 位于长边不超过 options.maskSize 的网格上；mask.size 为网格的 [高, 宽]。水平方向乘以 image.width / size[1]，垂直方向乘以 image.height / size[0]。详见图片。

二进制响应

Accept: application/cbor 以 CBOR（RFC 8949）代替 JSON 返回同一结果，结构和键相同。适用于 POST /v1/segment、POST /v1/refine、POST /v1/remove-background 和 JSON 模式的 POST /v1/batch/{endpoint}。多边形环（outer 和 holes 的每一项）为 RFC 8746 类型化数组，标签 69：uint16、小端、x 和 y 交错、图片像素的绝对值。WebP data 等二进制数据为字节串，不用 base64。

curl https://api.stack.foldbun.com/v1/segment \
  -H "Authorization: Bearer $FOLDBUN_API_KEY" \
  -H "Accept: application/cbor" \
  -H "Content-Type: application/json" \
  -d @request.json --output result.cbor

适用于较大的结果，例如实例很多或多边形很细致。环的每个坐标占 2 字节：100 个混合尺寸多边形实测为 64 KB，JSON 为 139 KB（小 54%）；WebP 蒙版去掉 base64 后小 26%；COCO 字符串只小约 2%。客户端的解码也更快。JSON 仍是默认：其他 Accept 值都返回 JSON，请求、错误和事件流始终为 JSON。

全部字段：API 参考。各模型的行为：sam3、sam-lite。