根据点选和/或框修整单个蒙版
const url = 'https://api.stack.foldbun.com/v1/refine';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"model":"sam3","image":{"id":"img_3b1f0c5e9a7d42c8b6e1f0a9d8c7b6a5f4e3d2c1b0a998877665544332211000"},"points":[{"x":412,"y":230,"positive":true},{"x":80,"y":40,"positive":false}]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.stack.foldbun.com/v1/refine \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "model": "sam3", "image": { "id": "img_3b1f0c5e9a7d42c8b6e1f0a9d8c7b6a5f4e3d2c1b0a998877665544332211000" }, "points": [ { "x": 412, "y": 230, "positive": true }, { "x": 80, "y": 40, "positive": false } ] }'对单个对象进行交互式修整：正向和负向 points，可选 box。限制：最多 20 个点。按每次调用一次解码计费（refine，每次调用 1 个单位），与点的数量以及是否给出框无关，另加图片编码费（encode_image，缓存命中时减免；修整刚完成分割的图片通常会命中缓存）。因此，每次点击后重新发送全部点的客户端，每次点击的费用相同。
交互优先级：提交后 2 秒内未完成的调用返回 HTTP 504 和错误码 upstream_timeout（可重试）。
1 至 128 个可打印 ASCII 字符。在同一账户内，密钥保留 24 小时：使用相同请求体重复请求，会返回原始响应（响应头 Idempotent-Replayed: true），且不会再次扣费或运行。相同密钥搭配不同请求体返回 409 idempotency_conflict。见概览。
用于修整单个蒙版的图片、点选和/或框。
修整请求。至少需要一个点或一个 box。若没有 box，则至少有一个点必须为正向点。该接口在调用之间不保留状态：每次调用都应发送该物体的全部点。
object
用于修整的模型。
包含该对象的图片。
object
POST /v1/images（或之前的调用）返回的句柄：img_ 加清理后图片的 SHA-256。仅在上传它的账户内有效。
预留（后续提供）。目前返回 400 unsupported。
JPEG、PNG 或 WebP 文件的标准 base64；允许带 data: 前缀。
正向和负向点选（最多 20 个）。
图片上的一次点击。坐标必须非负，并位于图片（image.width x image.height）之内。
object
水平位置，单位为摆正后的原图的像素。
垂直位置，单位为摆正后的原图的像素。
True：该点位于对象上。false：该点位于需要排除的区域上。
对象周围的框（可选）。
结果的可选调整。修整的对象是对象提示：始终返回，multimask 的候选从不合并，也不做重叠比较。SegmentOptions 中的顶点上限和各项预算同样适用。
object
返回最多 3 个候选蒙版，而不是只返回最佳蒙版。
蒙版网格的长边，单位为像素（64 到 4096），只用于 mask 输出。网格不会比图片大，因此实际长边取该值与图片长边中的较小者；mask.size 给出实际尺寸。
每个实例的几何。bbox、score 和 area 始终返回；未请求的几何不会计算。
object
polygon：含洞的简化轮廓（Instance.polygon）。mask：像素蒙版（Instance.mask）。[]：不返回几何。
多边形输出。轮廓在清理后的蒙版上按图片分辨率描出（长边超过 4096 px 时，在长边 4096 px 的网格上描出后缩放），并用 Douglas-Peucker 算法简化。tolerance 和 tolerancePx 是同一项设置：在同一对象中同时给出返回 400 invalid_request；分层选项中以更具体的一层为准。
object
简化容差，以图片对角线（sqrt(image.width² + image.height²)）的比例表示：简化后的边与描出的轮廓之间的最大距离。默认值可能调整；对精度有要求时应显式设置。
简化容差，单位为图片像素，代替 tolerance。0 保留轮廓的全部顶点（受顶点上限约束）。
返回每个部分的洞。false 只返回外环。
每个实例最多的部分（彼此分离的块）数量。保留最大的部分。
蒙版输出，在 geometry 包含 mask 时使用。
object
coco：整张蒙版的 COCO 压缩 RLE，无损，可用 pycocotools 读取。webp：对象紧贴裁剪区域的无损 WebP；只在发丝等极细的轮廓上比 coco 小，生成较慢，并受 WebP 像素预算限制（见 SegmentOptions）。
蒙版清理，在尺寸过滤和几何输出之前作用于每个实例。面积为蒙版的像素面积。
object
除最大部分以外、面积小于此值的部分（彼此分离的块）被去除；最大的部分始终保留。null 保留所有部分。
object
阈值，以图片面积（image.width x image.height）的比例表示。
阈值，单位为平方图片像素。
面积小于此值的洞被填充。null 保留所有洞。
object
阈值，以图片面积（image.width x image.height）的比例表示。
阈值，单位为平方图片像素。
示例
{ "model": "sam3", "image": { "id": "img_3b1f0c5e9a7d42c8b6e1f0a9d8c7b6a5f4e3d2c1b0a998877665544332211000" }, "points": [ { "x": 412, "y": 230, "positive": true }, { "x": 80, "y": 40, "positive": false } ]}修整后的对象（使用 options.multimask 时最多 3 个候选），形状与分割结果相同，但没有 dropStats。使用 Accept: application/cbor 时为 CBOR。
object
调用 ID call_<uuid>；联系支持时应提供。
处理该调用的模型 ID。
坐标所对应的摆正后的原图。纯文本向量嵌入时不出现。
object
图片句柄：img_ 加清理后字节的 SHA-256。
摆正后的原图的宽度，单位为像素（已应用 EXIF 方向）。
摆正后的原图的高度，单位为像素（已应用 EXIF 方向）。
已存储图片的大小，单位为字节。
已存储图片的媒体类型（与上传的类型相同）。
本次调用扣除的额度。失败的调用，以及由每日包含额度覆盖的调用，为 0。内部账户只计量、不扣费，此时 cost 为该调用的价格。
调用后的账户余额，单位为额度（内部账户的余额不变）。
本次调用在服务器侧的耗时，单位为毫秒。queueMs 为从提交到 GPU 节点领取任务的时间（包括排队，以及节点故障后的重新排队）；processingMs 为从节点领取任务到结果返回的时间（获取图片、推理，以及节点与服务器之间的往返）。inferenceMs、imageFetchMs 和 serverMs 对此作进一步细分。不包含客户端与 API 之间的网络时间。
object
从提交到 GPU 节点领取任务的毫秒数。
从节点领取任务到结果返回的毫秒数。
节点测得的 GPU 节点上的模型耗时，不含获取图片。不会大于 processingMs。节点未上报时不出现。
节点获取图片字节所用的时间。图片随任务一同发送，或节点无需获取（编码缓存命中）时为 0。节点未上报时不出现。
API 服务器内的总耗时：从收到请求到响应写出之前。包括读取请求体、图片准备、准入、queueMs、processingMs 和计费结算。仅在重放由旧版服务器存储的幂等响应时不出现。
该调用的计价方式。
object
该调用每个计价单位一行。
object
价目表中的计费单位，与 GET /v1/models 的 prices[].unit 相同（例如 encode_image、prompt、refine、image）。
使用的单位数。
单个单位的标价。
该行的价格：unitPrice * quantity，waived 时为 0。对未扣费（charged 为 false）的调用（试用、每日包含额度），各行仍显示标价。
节点已持有该编码（cache: hit）时，图片编码费为 true；此时 amount 为 0，原本适用的费用为 unitPrice * quantity。
该调用的价格（各行金额之和；capped 时削减到余额）。
是否从账户余额中扣费。Playground 试用调用，以及由每日包含额度覆盖的调用（此时设置了 pool 和 allowance）为 false；计费调用为 true。内部账户按标价计量、不扣费，此时 charged 为 false，total 为该调用的价格。
其每日包含额度覆盖了该调用的模型池（public 或 free）。计费调用（包括超出额度的调用）、试用调用和内部账户为 null。
pool 当日（UTC）的包含调用，计入本次调用。仅在设置了 pool 时出现。
object
当日（UTC）已用调用次数，包括本次。
每个 UTC 日包含的调用次数。
仅当价格超过余额、扣费被削减到余额时出现，且为 true。
按分数顺序排列的被分割对象（见 SegmentOptions）。
一个被分割出的对象。除另有说明外，所有坐标均为图片像素。
object
产生该实例的提示在 prompts 中的索引（仅分割）；合并实例取其成员的最小索引。
提示的 group，仅当请求设置了分组时出现。
文本提示（sam3 文本提示），样例框为 _exemplar。点提示的实例没有该字段。POST /v1/refine 的响应中没有该字段。
实例的置信度。对于文本提示和样例框的实例，该值为检测置信度；对于点、框（sam-lite）和修整产生的实例，该值为蒙版的预测 IoU，即模型对蒙版与物体贴合程度的自我估计。合并实例取其成员的最高分。
[x1, y1, x2, y2]：紧贴清理后实例的框。x2 和 y2 不包含在内，因此 x2 - x1 为以像素计的宽度。
清理后实例的像素面积。
仅合并实例：合并的实例数。
geometry 包含 polygon 时：各部分，从大到小排列。没有任何部分能构成 3 个顶点的环时为空（只有一两个像素宽的对象）。
多边形的一个部分（彼此分离的块）。环为扁平整数数组 [x0, y0, x1, y1, ...]，单位为图片像素。每个顶点是轮廓像素的中心，因此 0 <= x <= image.width - 1 且 0 <= y <= image.height - 1。环至少有 3 个不同的顶点，且不闭合（不重复第一个顶点）。外环在屏幕上为顺时针方向（y 轴向下时鞋带公式面积为正），洞为逆时针方向。简化后的环可能自相交。
object
外环。
洞，从大到小排列。该部分没有洞或 polygon.holes 为 false 时没有该字段。
顶点上限（每个实例 8,192 个）要求使用比请求更大的容差时出现：实际使用的容差，单位为图片像素。
蒙版网格上的整张蒙版，以 COCO 压缩 RLE（列优先）表示。{"size", "counts"} 是 pycocotools 可直接使用的 COCO RLE 对象。
object
COCO 压缩 RLE。
蒙版网格的 [高, 宽]：图片缩放到长边不超过 options.maskSize，从不放大。蒙版坐标在水平方向按 image.width / size[1]、垂直方向按 image.height / size[0] 缩放。
COCO 压缩游程字符串。
蒙版网格上对象的紧贴裁剪区域，以无损 WebP 表示。对象像素为白色，其余为黑色；通道值不小于 128 即为对象。
object
无损 WebP 裁剪区域。
蒙版网格的 [高, 宽]，与 coco 相同。
裁剪区域左上角在蒙版网格上的 [x, y]。
裁剪区域在蒙版网格上的 [宽, 高]。
Base64 编码的 WebP；CBOR 响应中为字节串。
budget：响应预算已用尽，该实例不带几何。vertices：最大的部分单独就超过顶点上限，该实例没有 polygon。bbox、score 和 area 始终保留。
仅 POST /v1/segment：每个丢失了实例的提示一项，按提示顺序排列；没有丢失时为空。
单个提示丢失的实例，按原因计数。每个计数都会出现（没有时为 0）。
object
在 prompts 中的索引。
低于 filter.minScore 且分数不低于 report.lowScoreFloor（为 null 时取 0.1）的候选；模型会产出大量接近 0 的分数，这些不计入。
被 filter.minSize 丢弃。
被 filter.minArea 丢弃。
被 nms 丢弃。
超出每个请求 300 个候选或超出 maxInstances。
因响应预算用尽而不带几何返回（omitted: budget）；这些实例仍在 instances 中。
仅在设置 report.droppedBoxes 时出现：被丢弃的实例，分数高者优先，最多 300 个。
一个被丢弃的实例（report.droppedBoxes）。
object
在 prompts 中的索引。
丢弃它的步骤；名称与 DropStats 中相同。
实例的分数。
[x1, y1, x2, y2]，与 Instance.bbox 相同。对于 lowScore、limit 和部分 tooSmall 条目，实例在描出蒙版之前即被丢弃，框来自模型的低分辨率蒙版：是近似值，可能比对象大。
hit：图片编码已被复用，编码费已减免。这不是承诺；见概览。
本次调用收取的图片编码费；缓存命中时为 0。
示例
{ "image": { "contentType": "image/jpeg" }, "instances": [ { "mask": { "encoding": "coco" }, "omitted": "budget" } ], "dropped": [ { "reason": "lowScore" } ], "cache": "hit"}object
调用 ID call_<uuid>；联系支持时应提供。
处理该调用的模型 ID。
坐标所对应的摆正后的原图。纯文本向量嵌入时不出现。
object
图片句柄：img_ 加清理后字节的 SHA-256。
摆正后的原图的宽度，单位为像素（已应用 EXIF 方向）。
摆正后的原图的高度，单位为像素（已应用 EXIF 方向）。
已存储图片的大小，单位为字节。
已存储图片的媒体类型（与上传的类型相同）。
本次调用扣除的额度。失败的调用，以及由每日包含额度覆盖的调用，为 0。内部账户只计量、不扣费，此时 cost 为该调用的价格。
调用后的账户余额，单位为额度（内部账户的余额不变）。
本次调用在服务器侧的耗时，单位为毫秒。queueMs 为从提交到 GPU 节点领取任务的时间（包括排队，以及节点故障后的重新排队）；processingMs 为从节点领取任务到结果返回的时间（获取图片、推理，以及节点与服务器之间的往返）。inferenceMs、imageFetchMs 和 serverMs 对此作进一步细分。不包含客户端与 API 之间的网络时间。
object
从提交到 GPU 节点领取任务的毫秒数。
从节点领取任务到结果返回的毫秒数。
节点测得的 GPU 节点上的模型耗时，不含获取图片。不会大于 processingMs。节点未上报时不出现。
节点获取图片字节所用的时间。图片随任务一同发送，或节点无需获取（编码缓存命中）时为 0。节点未上报时不出现。
API 服务器内的总耗时：从收到请求到响应写出之前。包括读取请求体、图片准备、准入、queueMs、processingMs 和计费结算。仅在重放由旧版服务器存储的幂等响应时不出现。
该调用的计价方式。
object
该调用每个计价单位一行。
object
价目表中的计费单位，与 GET /v1/models 的 prices[].unit 相同（例如 encode_image、prompt、refine、image）。
使用的单位数。
单个单位的标价。
该行的价格：unitPrice * quantity，waived 时为 0。对未扣费（charged 为 false）的调用（试用、每日包含额度），各行仍显示标价。
节点已持有该编码（cache: hit）时，图片编码费为 true；此时 amount 为 0，原本适用的费用为 unitPrice * quantity。
该调用的价格（各行金额之和；capped 时削减到余额）。
是否从账户余额中扣费。Playground 试用调用，以及由每日包含额度覆盖的调用（此时设置了 pool 和 allowance）为 false；计费调用为 true。内部账户按标价计量、不扣费，此时 charged 为 false，total 为该调用的价格。
其每日包含额度覆盖了该调用的模型池（public 或 free）。计费调用（包括超出额度的调用）、试用调用和内部账户为 null。
pool 当日（UTC）的包含调用，计入本次调用。仅在设置了 pool 时出现。
object
当日（UTC）已用调用次数，包括本次。
每个 UTC 日包含的调用次数。
仅当价格超过余额、扣费被削减到余额时出现，且为 true。
按分数顺序排列的被分割对象（见 SegmentOptions）。
一个被分割出的对象。除另有说明外，所有坐标均为图片像素。
object
产生该实例的提示在 prompts 中的索引（仅分割）；合并实例取其成员的最小索引。
提示的 group，仅当请求设置了分组时出现。
文本提示（sam3 文本提示），样例框为 _exemplar。点提示的实例没有该字段。POST /v1/refine 的响应中没有该字段。
实例的置信度。对于文本提示和样例框的实例，该值为检测置信度；对于点、框（sam-lite）和修整产生的实例，该值为蒙版的预测 IoU，即模型对蒙版与物体贴合程度的自我估计。合并实例取其成员的最高分。
[x1, y1, x2, y2]：紧贴清理后实例的框。x2 和 y2 不包含在内，因此 x2 - x1 为以像素计的宽度。
清理后实例的像素面积。
仅合并实例：合并的实例数。
geometry 包含 polygon 时：各部分，从大到小排列。没有任何部分能构成 3 个顶点的环时为空（只有一两个像素宽的对象）。
多边形的一个部分（彼此分离的块）。环为扁平整数数组 [x0, y0, x1, y1, ...]，单位为图片像素。每个顶点是轮廓像素的中心，因此 0 <= x <= image.width - 1 且 0 <= y <= image.height - 1。环至少有 3 个不同的顶点，且不闭合（不重复第一个顶点）。外环在屏幕上为顺时针方向（y 轴向下时鞋带公式面积为正），洞为逆时针方向。简化后的环可能自相交。
object
外环。
洞，从大到小排列。该部分没有洞或 polygon.holes 为 false 时没有该字段。
顶点上限（每个实例 8,192 个）要求使用比请求更大的容差时出现：实际使用的容差，单位为图片像素。
蒙版网格上的整张蒙版，以 COCO 压缩 RLE（列优先）表示。{"size", "counts"} 是 pycocotools 可直接使用的 COCO RLE 对象。
object
COCO 压缩 RLE。
蒙版网格的 [高, 宽]：图片缩放到长边不超过 options.maskSize，从不放大。蒙版坐标在水平方向按 image.width / size[1]、垂直方向按 image.height / size[0] 缩放。
COCO 压缩游程字符串。
蒙版网格上对象的紧贴裁剪区域，以无损 WebP 表示。对象像素为白色，其余为黑色；通道值不小于 128 即为对象。
object
无损 WebP 裁剪区域。
蒙版网格的 [高, 宽]，与 coco 相同。
裁剪区域左上角在蒙版网格上的 [x, y]。
裁剪区域在蒙版网格上的 [宽, 高]。
Base64 编码的 WebP；CBOR 响应中为字节串。
budget：响应预算已用尽，该实例不带几何。vertices：最大的部分单独就超过顶点上限，该实例没有 polygon。bbox、score 和 area 始终保留。
仅 POST /v1/segment：每个丢失了实例的提示一项，按提示顺序排列；没有丢失时为空。
单个提示丢失的实例，按原因计数。每个计数都会出现（没有时为 0）。
object
在 prompts 中的索引。
低于 filter.minScore 且分数不低于 report.lowScoreFloor（为 null 时取 0.1）的候选；模型会产出大量接近 0 的分数，这些不计入。
被 filter.minSize 丢弃。
被 filter.minArea 丢弃。
被 nms 丢弃。
超出每个请求 300 个候选或超出 maxInstances。
因响应预算用尽而不带几何返回（omitted: budget）；这些实例仍在 instances 中。
仅在设置 report.droppedBoxes 时出现：被丢弃的实例，分数高者优先，最多 300 个。
一个被丢弃的实例（report.droppedBoxes）。
object
在 prompts 中的索引。
丢弃它的步骤；名称与 DropStats 中相同。
实例的分数。
[x1, y1, x2, y2]，与 Instance.bbox 相同。对于 lowScore、limit 和部分 tooSmall 条目，实例在描出蒙版之前即被丢弃，框来自模型的低分辨率蒙版：是近似值，可能比对象大。
hit：图片编码已被复用，编码费已减免。这不是承诺；见概览。
本次调用收取的图片编码费；缓存命中时为 0。
default
Section titled “default”错误信封。HTTP 状态码与 code 对应；只有 retryable: true 的错误才值得原样重复。失败的调用不收费。
| 状态码 | 错误码 |
|---|---|
| 400 | invalid_request, invalid_image（图片通过了上传检查，但无法解码）, unsupported |
| 401 | unauthorized |
| 402 | insufficient_balance |
| 403 | model_locked |
| 404 | not_found, image_not_found |
| 409 | idempotency_conflict, request_in_progress |
| 413 | payload_too_large |
| 429 | rate_limited, daily_limit_reached, too_many_batches（均带有 Retry-After） |
| 500 | internal_error |
| 502 | upstream_error, bad_model_output |
| 503 | model_unavailable, model_busy, unavailable（均带有 Retry-After） |
| 504 | upstream_timeout |
model_unavailable 也用于唯一提供该模型的 GPU 节点短时失联：失联后约一分钟内，交互式调用立即返回该错误并带较短的 Retry-After（5 秒），同步和批量调用则继续排队到各自的截止时间，不会直接失败。
各错误码的含义和重试建议：错误。
所有错误响应的响应体。
object
错误。
object
稳定的、机器可读的错误码。应依据该字段而不是 message 判断。与 HTTP 状态码的对应关系见响应部分。
面向人的说明。措辞可能变化。
为 true 时，原样重复同一请求有可能成功。
建议重试前等待的毫秒数；无建议时为 0。
示例
{ "error": { "code": "model_busy", "message": "model sam3 is busy; retry shortly", "retryable": true, "retryAfterMs": 5000 }}重试前须等待的整秒数；出现在 429 和 503 响应中。
服务器生成的请求 ID（16 个十六进制字符）；出现在每个响应中。联系支持时应提供该值。