# 交互分割

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

## 用点标出物体

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

![草地上趴着的狗：整只狗上有蓝色蒙版，胸前有一个绿色圆点。](../../../../../assets/docs/sam-lite-point.webp)

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

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

## 用框标出物体

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

![厨房场景：绿色框内的水壶上有蓝色蒙版。](../../../../../assets/docs/sam-lite-box.webp)

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

使用 `sam3` 时，`POST /v1/segment` 中的框是样例框：会返回框内的物体以及与之相似的物体（见[样例框](https://stack.foldbun.com/zh/docs/use-cases/concept-segmentation/#样例框)）。如只需框内的物体，请将框发送到 `POST /v1/refine`，见下一节。

## 通过点选修整单个物体

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

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

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

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

## 输出选项

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

## 支持的模型

| | [`sam3`](https://stack.foldbun.com/zh/docs/models/sam3/#交互分割) | [`sam-lite`](https://stack.foldbun.com/zh/docs/models/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` 调用，通常无需支付图片编码费。详见[计费](https://stack.foldbun.com/zh/docs/billing/#sam-图片编码费与缓存命中)。两个模型各自如何得出这些结果，见 [`sam3` 的工作原理](https://stack.foldbun.com/zh/docs/models/sam3/#工作原理)和 [`sam-lite` 的工作原理](https://stack.foldbun.com/zh/docs/models/sam-lite/#工作原理)。

## 调用示例

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

```bash
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 }]
  }'
```

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

```json
{
  "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, ...]`。像素蒙版只在请求时返回（见[图片](https://stack.foldbun.com/zh/docs/images/#蒙版)）。
- `cache` 为 `miss`，`imageFee` 为 0.2：图片在本次调用中完成编码。对同一图片的下一次点选通常返回 `hit`，`imageFee` 为 0。
- `billing.charged` 为 `false`，`pool` 为 `free`：本次调用是当天 1,000 次包含调用中的第一次，因此 `cost` 为 0，而各计费行显示的是标价。

全部字段：[API 参考](https://stack.foldbun.com/zh/docs/api/operations/refine/)。

**本次调用的费用。** 按标价计算，新图片为 0.2（`encode_image`）+ 0.01（`refine`）= 0.21 额度；编码仍在缓存中时，之后每次点选为 0.01 额度。上述调用由免费池的每日额度覆盖，未扣费。单价见[计费](https://stack.foldbun.com/zh/docs/billing/#价目表)。

## 接口与参考

| 接口 | 在本用例中 | 参考 |
|---|---|---|
| `POST /v1/segment` | 一次调用分割多个物体：每个点一个实例，使用 `sam-lite` 时每个框也是一个实例 | [API 参考](https://stack.foldbun.com/zh/docs/api/operations/segment/) |
| `POST /v1/refine` | 根据正负点和可选的框分割单个物体：返回最佳蒙版，或最多 3 个候选蒙版 | [API 参考](https://stack.foldbun.com/zh/docs/api/operations/refine/) |

- [`sam3`](https://stack.foldbun.com/zh/docs/models/sam3/) 和 [`sam-lite`](https://stack.foldbun.com/zh/docs/models/sam-lite/)：各模型的工作原理、限制和实测延迟。
- [SAM 调用如何计费](https://stack.foldbun.com/zh/docs/billing/#sam-调用如何计费)：计费单位与计费示例，包括逐次点选的编辑过程。
- [图片](https://stack.foldbun.com/zh/docs/images/#坐标)：点、框和蒙版所用的像素坐标。
- [概念分割](https://stack.foldbun.com/zh/docs/use-cases/concept-segmentation/)：根据文本提示或样例框找出某一概念的全部实例。