交互分割

以 Markdown 查看在 Playground 中试用即将推出

交互分割返回调用方所标出物体的蒙版：物体上的一个点、围绕物体的一个框，或一组正负点选。每个标记恰好对应一个物体。典型用途包括标注工具和图片编辑器中的点选选取，以及已知物体位置的处理流程，例如来自检测器的框。如需在不逐个标记的情况下找出某一概念的全部实例，请参阅概念分割。

用点标出物体

一个点在物体上标出一个位置，并为该物体返回一个蒙版，即模型候选结果中最佳的一个。一次 POST /v1/segment 调用可以包含多个点：按 prompts 的顺序，每个点返回一个实例，图片只编码一次。点始终是正向标记，因为单独的负点什么也选不中。负点用于修整，在其中用于修剪蒙版（见通过点选修整单个物体）。

草地上趴着的狗：整只狗上有蓝色蒙版，胸前有一个绿色圆点。

sam-lite：单个正点（绿色圆点）的 Playground 录制结果。该图为带 points 的 /v1/refine 调用的结果；分数为唯一实例的 score。

使用 sam3 时，点可以与文本提示和样例框在同一调用中混用。每个点仍恰好返回一个实例，且没有 label。filter、nms 和 options.maxInstances 只作用于文本提示和样例框的实例，样例框从不影响点。例如，汽车上的一个点加上文本提示 person，会返回该汽车以及图片中的每个人。

用框标出物体

使用 sam-lite 时，一个框返回框内物体的蒙版。框和点可以在一次调用中混用，每个提示对应一个实例。sam-lite 不使用 positive：框始终标出物体，点始终为正点。

厨房场景：绿色框内的水壶上有蓝色蒙版。

sam-lite：单个框（绿色轮廓）的 Playground 录制结果，已裁剪至框的周边。该图为带 box 的 /v1/refine 调用的结果；分数为唯一实例的 score。

使用 sam3 时，POST /v1/segment 中的框是样例框：会返回框内的物体以及与之相似的物体（见样例框）。如只需框内的物体，请将框发送到 POST /v1/refine，见下一节。

通过点选修整单个物体

POST /v1/refine 根据正负点和可选的框分割或修整单个物体。正点标出物体，负点标出需要排除的部分。一次调用至少需要一个点或一个框，最多接受 20 个点。该调用为交互优先级，截止时间为 2 秒。默认模型为 sam3；sam-lite 使用相同的请求体。

整个调用是针对一个物体的一次解码：点和框是同一次推理的输入，因此无论有多少个点，调用只计费一次（见 SAM 调用如何计费）。默认情况下，响应以多边形给出最佳蒙版。options.multimask 改为返回最多 3 个候选蒙版，适用于单次点选含义不明确的情形，例如点在衬衫上，既可能指衬衫，也可能指整个人。

典型流程：围绕汽车的一个框加上车身上的一个正点，即可标出该汽车。蒙版溢出到相邻物体或背景时，下一次调用在该处添加一个负点，该区域即从蒙版中去除。

编辑器每次调用都应发送完整的点选集合：该接口在调用之间不保留状态。图片编码仍在缓存中时，对同一图片的重复调用响应迅速，且免收编码费。

输出选项

默认输出为图片像素坐标下的多边形。像素蒙版、多边形容差以及碎片与洞的清理均为选项：POST /v1/segment 中为 options.defaults 和 prompts[].options，POST /v1/refine 中为 options.output 和 options.cleanup。点提示和框提示都是物体提示，因此总是返回，filter 不适用。详见后处理。

支持的模型

	`sam3`	`sam-lite`
模型	SAM 3	SAM 2.1 Hiera-S
在 `/v1/segment` 中标出单个物体	点	点或框
`/v1/segment` 中的框	样例框：返回相似物体	框内的物体
同一调用中的文本提示	支持	不支持
`/v1/refine`	点和可选的框；最多 3 个候选蒙版	点和可选的框；最多 3 个候选蒙版
标价（额度）	图片编码每张 0.5 + `/v1/segment` 中每个点 0.02，或每次 `/v1/refine` 调用 0.02	图片编码每张 0.2 + `/v1/segment` 中每个点或框 0.01，或每次 `/v1/refine` 调用 0.01
模型池	付费池：从余额中扣费	免费池：首次充值后每个 UTC 日前 1,000 次调用免费，超出后从余额中扣费
录制的处理时间	约 390 至 560 ms（录制的概念提示调用）	约 180 ms
适用场景	同一调用还需要文本提示或样例框，或同一图片也使用 `sam3` 做概念分割	成本和延迟最为重要，且每个物体都由调用方标出

两个模型都使用图片编码缓存：对同一图片、使用同一模型，在 /v1/segment 调用之后紧接着进行的 /v1/refine 调用，通常无需支付图片编码费。详见计费。两个模型各自如何得出这些结果，见 sam3 的工作原理和 sam-lite 的工作原理。

调用示例

在第一张图的狗身上点选一次，使用 sam-lite 发送到 POST /v1/refine：

curl https://api.stack.foldbun.com/v1/refine \
  -H "Authorization: Bearer $FOLDBUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sam-lite",
    "image": { "id": "img_3b73d4112efca712359a1b2c89922b8494fac4a8f0b033c4dfc5205c3ec95b12" },
    "points": [{ "x": 760, "y": 560, "positive": true }]
  }'

以下响应有删减：多边形环已缩短。

{
  "id": "call_01a1913c-4de0-7f15-afbd-d26a0d0c347f",
  "model": "sam-lite",
  "image": {
    "id": "img_3b73d4112efca712359a1b2c89922b8494fac4a8f0b033c4dfc5205c3ec95b12",
    "width": 1512,
    "height": 1008,
    "bytes": 378383,
    "contentType": "image/jpeg"
  },
  "instances": [
    {
      "score": 0.9844,
      "bbox": [382, 102, 1171, 912],
      "area": 351204,
      "polygon": [
        { "outer": [602, 103, 771, 131, 910, 224, 1096, 421, 1170, 633, 1051, 811, 904, 911, 612, 905, 441, 801, 383, 583, 436, 301, 522, 168] }
      ]
    }
  ],
  "cache": "miss",
  "imageFee": 0.2,
  "cost": 0,
  "balance": 0,
  "timing": { "queueMs": 0, "processingMs": 186 },
  "billing": {
    "lines": [
      { "unit": "encode_image", "quantity": 1, "unitPrice": 0.2, "amount": 0.2, "waived": false },
      { "unit": "refine", "quantity": 1, "unitPrice": 0.01, "amount": 0.01, "waived": false }
    ],
    "total": 0.21,
    "charged": false,
    "pool": "free",
    "allowance": { "used": 1, "limit": 1000 }
  }
}

响应解读

instances 只有一项：狗的蒙版。修整调用的响应没有 prompt 和 label；/v1/segment 中的点实例有 prompt，没有 label。
score 为 0.9844，是蒙版的预测 IoU，即模型对蒙版与物体贴合程度的自我估计。设置 options.multimask 时，instances 包含最多 3 个候选蒙版以供选择。
bbox 和 polygon 的单位为摆正后的原图的像素，此处为 1512 × 1008（image.width、image.height）。bbox 为 [x1, y1, x2, y2]，x2 和 y2 不包含在内；area 为蒙版的像素面积。polygon 是按面积从大到小排列的部分列表；每个部分有 outer 环，有洞时还有 holes，均为扁平整数数组 [x0, y0, x1, y1, ...]。像素蒙版只在请求时返回（见图片）。
cache 为 miss，imageFee 为 0.2：图片在本次调用中完成编码。对同一图片的下一次点选通常返回 hit，imageFee 为 0。
billing.charged 为 false，pool 为 free：本次调用是当天 1,000 次包含调用中的第一次，因此 cost 为 0，而各计费行显示的是标价。

全部字段：API 参考。

本次调用的费用。 按标价计算，新图片为 0.2（encode_image）+ 0.01（refine）= 0.21 额度；编码仍在缓存中时，之后每次点选为 0.01 额度。上述调用由免费池的每日额度覆盖，未扣费。单价见计费。

接口与参考

接口	在本用例中	参考
`POST /v1/segment`	一次调用分割多个物体：每个点一个实例，使用 `sam-lite` 时每个框也是一个实例	API 参考
`POST /v1/refine`	根据正负点和可选的框分割单个物体：返回最佳蒙版，或最多 3 个候选蒙版	API 参考

sam3 和 sam-lite：各模型的工作原理、限制和实测延迟。
SAM 调用如何计费：计费单位与计费示例，包括逐次点选的编辑过程。
图片：点、框和蒙版所用的像素坐标。
概念分割：根据文本提示或样例框找出某一概念的全部实例。