概念分割

概念分割为某一概念的每个实例返回一个蒙版：街景中的所有汽车、摊位上的所有李子、所有与框选样例相似的物体。实例数量事先未知，调用方也不逐个标记。典型用途包括计数、数据集自动标注，以及先找出某一类的全部物体再做筛选。如需分割由调用方用点、框或点选标出的物体，请参阅交互分割。

文本提示

文本提示以 1 至 200 个字符给出一个概念。图片中该概念的每个实例都作为单独的蒙版返回，并附带分数。一次调用可以包含多个提示，图片只编码一次（见 SAM 调用如何计费）。

sam3：提示 car 和 person 的 Playground 录制结果。每个蒙版对应 instances 中的一项，按 prompt 着色。

样例框

样例框为围绕一个物体的 [x1, y1, x2, y2]。只含框时，sam3 返回框内的物体以及与之相似的物体：调用中的所有框合成一个视觉查询。框和文本提示可以混用，此时这些框作用于同一调用中的每个文本提示。样例框适合难以命名或有大量相似物体的情形，例如下图中的水果。

sam3：单个样例框（绿色轮廓）的 Playground 录制结果。90 个蒙版的 label 为 _exemplar，图例中的 “exemplar box” 即指此值。

positive 默认为 true，表示“找出更多类似的”。设为 "positive": false 时，该框为负样例框（“不要这样的”）：与框内物体相似的物体会被排除。负框用于修整每个文本提示的查询，或只含框时的查询。只含框的调用至少需要一个正样例框，框全部为负的调用需要有文本提示。点不计入：只与点并存的负框不被接受。样例框最多 10 个。

与点提示混用

一次调用还可以包含点提示。每个点恰好返回一个物体，即点所在位置的最佳蒙版，其实例没有 label。点不受 filter、nms、options.maxInstances 和样例框影响。点提示的详细说明见用点标出物体。

过滤、限制与合并

分数低于 filter.minScore（默认 0.5）的实例被丢弃，最多返回 options.maxInstances（默认 100）个搜索实例。尺寸与面积过滤、重叠去除（nms）、碎片清理和按 group 合并同样是选项，可在 options.defaults 中为整个调用设置，也可在 prompts[].options 中为单个提示设置。dropStats 报告每个提示丢失了什么。全部选项、处理顺序和限制见后处理。

支持的模型

概念提示仅由 sam3 提供；sam-lite 既不接受文本提示，也不接受样例框。

	sam3
模型	SAM 3
接受	文本提示（1 至 200 个字符）、样例框（正向或负向）、点
返回	每个匹配一个实例，标注为提示文字或 _exemplar
标价（额度）	图片编码每张 0.5 + 每个文本提示 0.05（样例框不另外收费；只含框的调用计为一次提示），每个点 0.02
模型池	付费池：从余额中扣费
录制的处理时间	约 390 至 560 ms（录制的概念提示调用）

sam3 如何得出这些结果，见工作原理。

调用示例

在第一张图的街景上使用文本提示 car 和 person，发送到 POST /v1/segment：

curl https://api.stack.foldbun.com/v1/segment \
  -H "Authorization: Bearer $FOLDBUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sam3",
    "image": { "id": "img_312c4e3a0ef23fa991baec515316f6b5897d4d534ad7058c57d8563cfcbdc6e2" },
    "prompts": [{ "text": "car" }, { "text": "person" }]
  }'

以下响应有删减：实例列表和多边形环已缩短。

{
  "id": "call_01a1913c-25a0-73fd-a074-7a6ac6154590",
  "model": "sam3",
  "image": {
    "id": "img_312c4e3a0ef23fa991baec515316f6b5897d4d534ad7058c57d8563cfcbdc6e2",
    "width": 1343,
    "height": 1008,
    "bytes": 388375,
    "contentType": "image/jpeg"
  },
  "instances": [
    {
      "prompt": 0,
      "label": "car",
      "score": 0.9696,
      "bbox": [0, 716, 207, 889],
      "area": 14261,
      "polygon": [
        { "outer": [0, 888, 0, 762, 41, 744, 96, 718, 158, 724, 206, 781, 206, 888] }
      ]
    }
  ],
  "cache": "miss",
  "imageFee": 0.5,
  "cost": 0.6,
  "balance": 998.4,
  "timing": { "queueMs": 0, "processingMs": 473 },
  "billing": {
    "lines": [
      { "unit": "encode_image", "quantity": 1, "unitPrice": 0.5, "amount": 0.5, "waived": false },
      { "unit": "prompt", "quantity": 2, "unitPrice": 0.05, "amount": 0.1, "waived": false }
    ],
    "total": 0.6,
    "charged": true,
    "pool": null
  }
}

响应解读

• instances 为每个匹配一项：图中有 9 辆车和 18 个人，JSON 只显示第一项。prompt 是 prompts 中的索引（0 为 car），label 重复提示文字；样例框产生的实例，label 为 _exemplar。
• score 为 0.9696，是该实例的检测置信度，范围 0 至 1。
• bbox 和 polygon 的单位为摆正后的原图的像素，此处为 1343 × 1008（image.width、image.height）。bbox 为 [x1, y1, x2, y2]，x2 和 y2 不包含在内；area 为物体的像素面积。polygon 是按面积从大到小排列的部分列表：每个部分有 outer 环，物体有洞时还有 holes，均为扁平整数数组 [x0, y0, x1, y1, ...]。像素蒙版只在请求时返回（见后处理和图片）。
• dropStats（此处未显示）按提示列出被丢弃的候选数量及原因。没有丢弃任何实例时为空数组。
• cache 为 miss，imageFee 为 0.5：图片在本次调用中完成编码。对同一图片的后续调用，例如点选修整，通常返回 hit，imageFee 为 0。
• billing.lines 中 encode_image 出现一次，prompt 的 quantity 为 2，对应两个文本提示。charged 为 true，pool 为 null，因此 cost 等于 total，并已从 balance 中扣除。

全部字段：API 参考。

本次调用的费用。 新图片为 0.5（encode_image）+ 2 × 0.05（prompt）= 0.60 额度，与本响应的实际扣费一致；编码已缓存时为 0.10 额度。单价见计费。

接口与参考

接口	在本用例中	参考
POST /v1/segment	根据 1 至 50 个提示找出某一概念的全部实例：文本提示、样例框，以及可选的点	API 参考

• sam3：模型的工作原理、限制和实测延迟。
• SAM 调用如何计费：计费单位与计费示例，包括带样例框的提示。
• 交互分割：使用 sam3 或 sam-lite，通过点、框和点选分割单个物体。