多张图片的分割
const url = 'https://api.stack.foldbun.com/v1/batch/segment';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"model":"sam3","items":[{"image":{"id":"img_3b1f0c5e9a7d42c8b6e1f0a9d8c7b6a5f4e3d2c1b0a998877665544332211000"},"prompts":[{"text":"cat"}]}]}'};
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/batch/segment \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "model": "sam3", "items": [ { "image": { "id": "img_3b1f0c5e9a7d42c8b6e1f0a9d8c7b6a5f4e3d2c1b0a998877665544332211000" }, "prompts": [ { "text": "cat" } ] } ] }'模型 sam3 或 sam-lite。条目为去掉 model 的 POST /v1/segment 请求体（SegmentItem），每个条目的选项、后处理和限制与单次调用相同。语义、模式、限制和事件格式见 BatchRequest、BatchItem 和 BatchSummary Schema 以及概述。推荐使用 Server-Sent Events；不推荐 JSON 模式。
1 至 128 个可打印 ASCII 字符。在同一账户内，密钥保留 24 小时：使用相同请求体重复请求，会返回原始响应（响应头 Idempotent-Replayed: true），且不会再次扣费或运行。相同密钥搭配不同请求体返回 409 idempotency_conflict。见概览。
模型、条目和可选的时限。
POST /v1/batch/segment：条目为 SegmentItem 请求体的 BatchRequest。
object
所有条目使用的模型 ID。端点有默认模型时可省略。
该端点的单次调用请求体，不含 model，按执行顺序排列。
不含 model 的单次调用端点请求体；图片只能是 {"id": "img_..."}。
object
整个批量的时限，单位为秒，从请求到达时起算。只能缩短所在模式的上限（事件流 600 秒，JSON 90 秒）。
所有条目使用的模型：sam3 或 sam-lite。
分割条目，按执行顺序排列。
去掉 model 的 POST /v1/segment 请求体：POST /v1/batch/segment 的一个条目。批量中图片只能是 {"id": "img_..."}。
object
待分割的图片。
object
POST /v1/images（或之前的调用）返回的句柄：img_ 加清理后图片的 SHA-256。仅在上传它的账户内有效。
预留（后续提供）。目前返回 400 unsupported。
JPEG、PNG 或 WebP 文件的标准 base64；允许带 data: 前缀。
提示，各类型合计最多 50 个；规则见 SegmentRequest。
一个提示：text、box 和 point 中恰好一个，另可带 group 和 options。
object
文本提示（sam3）：要查找的对象类型，1 至 200 个字符。
框提示：样例框（sam3）或对象框（sam-lite）。
样例框（sam3）：true 表示“查找更多类似项”。为 false 时，该框是负向样例框（“排除此类”）：与之相似的物体不会返回。仅适用于 sam3 的样例框。
点提示（sam3、sam-lite）：落在对象上的一个正向点击，单位为摆正后的原图的像素。此处不接受负向点（positive: false），请使用 POST /v1/refine。
object
水平位置，单位为摆正后的原图的像素。
垂直位置，单位为摆正后的原图的像素。
True：该点位于对象上。false：该点位于需要排除的区域上。
用于重叠去除（nms.scope: group）和合并的分组：1 到 64 个字母、数字和 _.:-。同一分组的提示相互比较和合并；没有分组的提示自成一组。会在实例上返回。
单个提示的实例的后处理，在 options.defaults 中为所有提示设置，在 prompts[].options 中为单个提示设置。每个字段先取内置默认值，再由 options.defaults 覆盖，再由该提示的 options 覆盖。对象（polygon、mask、filter、cleanup）按字段合并：设置 polygon.tolerance 时保留 polygon.holes。数组（geometry）和阈值对象（minSize、minArea、dropFragments、fillHoles）整体替换；被替换的阈值中缺少的字段取其默认值，null 关闭阈值。
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）。
搜索类实例（sam3 文本提示和样例框）的过滤条件。写在对象提示上返回 400 invalid_request；options.defaults.filter 对对象提示不生效。
object
保留的最低 score（dropStats.lowScore）。
最小框尺寸（dropStats.tooSmall）。默认：关闭。
object
阈值，以图片短边的比例表示。
阈值，单位为图片像素。
贴着图片边界的框如何判断（见表）。
框的边与图片边界的距离在此值（图片像素）以内时，视为贴边。
清理后实例的最小 area（dropStats.tooSmallArea）。默认：关闭。
object
阈值，以图片面积（image.width x image.height）的比例表示。
阈值，单位为平方图片像素。
蒙版清理，在尺寸过滤和几何输出之前作用于每个实例。面积为蒙版的像素面积。
object
除最大部分以外、面积小于此值的部分（彼此分离的块）被去除；最大的部分始终保留。null 保留所有部分。
object
阈值，以图片面积（image.width x image.height）的比例表示。
阈值，单位为平方图片像素。
面积小于此值的洞被填充。null 保留所有洞。
object
阈值，以图片面积（image.width x image.height）的比例表示。
阈值，单位为平方图片像素。
把该提示的实例与同一 group 中其他 merge: true 的实例合并为一个实例（见 SegmentRequest）。
请求级选项。后处理免费，按固定顺序进行；每一步只处理前面各步保留下来的实例，括号中是该步丢弃的实例所计入的 dropStats 计数：
- 分数：低于
filter.minScore的搜索类候选被丢弃（lowScore）。每个请求最多 300 个候选按分数顺序继续处理（limit）。 - 对每个实例进行清理（
cleanup）。 - 尺寸：在清理后的实例上先按
filter.minSize（tooSmall），再按filter.minArea（tooSmallArea）过滤。 - 重叠：
nms（overlap）。 - 合并：在每个
group内按merge合并。 - 数量：按分数顺序保留前
maxInstances个搜索类实例（limit）。对象提示的实例始终保留。 - 几何输出，然后应用下列响应限制。
分数顺序用于每一步以及 instances 的排列：score 降序，然后 prompt 升序，然后按模型候选的顺序。
取决于图片内容的限制。 这些限制无法在调用运行前检查，因此按固定规则缩减输出，而不是使调用失败；同一图片上的同一请求得到相同的结果，每次缩减都在响应中可见：
- 顶点上限，每个实例 8,192 个顶点（所有环合计）。超过时，将容差加倍后重新简化多边形，最多 6 次，起始值取请求的容差与 1 px 中的较大者；此时
tolerancePx给出实际使用的容差。仍然超过上限时，从最大的部分起依次保留，直到再加一个部分就会超出上限；最大的部分单独就超过上限时，该实例没有polygon，并带有omitted: vertices。 - 响应预算，每个响应 4 MiB 几何数据，按每个多边形顶点 4 字节、每个 COCO
counts字符串的长度和每个 WebP 蒙版的大小计算。实例按分数顺序使用预算；从第一个几何数据放不下的实例开始，实例保留bbox、score和area，但不带几何，并带有omitted: budget（budget）。 - WebP 像素预算，每个响应 32 百万像素的 WebP 裁剪区域，按分数顺序计算；从第一个放不下的裁剪区域开始，蒙版以
coco返回（由mask.encoding指明）。 dropped最多列出 300 个实例，分数高者优先。
在调用运行前检查（返回 400 invalid_request，不收费）：所有选项的取值范围、最多 50 个提示，以及 SegmentRequest 中列出的被拒绝的组合。
object
单个提示的实例的后处理，在 options.defaults 中为所有提示设置，在 prompts[].options 中为单个提示设置。每个字段先取内置默认值，再由 options.defaults 覆盖，再由该提示的 options 覆盖。对象（polygon、mask、filter、cleanup）按字段合并：设置 polygon.tolerance 时保留 polygon.holes。数组（geometry）和阈值对象（minSize、minArea、dropFragments、fillHoles）整体替换；被替换的阈值中缺少的字段取其默认值，null 关闭阈值。
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）。
搜索类实例（sam3 文本提示和样例框）的过滤条件。写在对象提示上返回 400 invalid_request；options.defaults.filter 对对象提示不生效。
object
保留的最低 score（dropStats.lowScore）。
最小框尺寸（dropStats.tooSmall）。默认：关闭。
object
阈值，以图片短边的比例表示。
阈值，单位为图片像素。
贴着图片边界的框如何判断（见表）。
框的边与图片边界的距离在此值（图片像素）以内时，视为贴边。
清理后实例的最小 area（dropStats.tooSmallArea）。默认：关闭。
object
阈值，以图片面积（image.width x image.height）的比例表示。
阈值，单位为平方图片像素。
蒙版清理，在尺寸过滤和几何输出之前作用于每个实例。面积为蒙版的像素面积。
object
除最大部分以外、面积小于此值的部分（彼此分离的块）被去除；最大的部分始终保留。null 保留所有部分。
object
阈值，以图片面积（image.width x image.height）的比例表示。
阈值，单位为平方图片像素。
面积小于此值的洞被填充。null 保留所有洞。
object
阈值，以图片面积（image.width x image.height）的比例表示。
阈值，单位为平方图片像素。
把该提示的实例与同一 group 中其他 merge: true 的实例合并为一个实例（见 SegmentRequest）。
返回的搜索类实例的最大数量，在过滤、重叠去除和合并之后计数。对象提示的实例不计入。
蒙版网格的长边，单位为像素（64 到 4096），只用于 mask 输出。网格不会比图片大，因此实际长边取该值与图片长边中的较小者；mask.size 给出实际尺寸。多边形和框始终以图片像素表示。
搜索类实例之间的重叠去除（非极大值抑制）。按分数顺序贪心处理：实例与同一范围内已保留的实例的 IoU 大于 iou 时被丢弃（dropStats.overlap）。对象提示的实例从不参与。缺省或 null：关闭。
object
IoU 大于此值时丢弃分数较低的实例（IoU 相等时两者都保留）。
mask：清理后蒙版的 IoU。box：bbox 的 IoU。
group：只比较同一 group 的实例。all：比较所有搜索类实例。
丢弃实例的报告。
object
返回 dropped：每个被丢弃实例的框、分数和原因。
设置时：只有分数不低于此值的候选计入 dropStats.lowScore 并列入 dropped。null：分数不低于 0.1 的候选计入 dropStats.lowScore，且不列出。
示例
{ "model": "sam3", "items": [ { "image": { "id": "img_3b1f0c5e9a7d42c8b6e1f0a9d8c7b6a5f4e3d2c1b0a998877665544332211000" }, "prompts": [ { "text": "cat" } ] } ]}批量已执行（单个条目仍可能失败：请求本身只会在执行开始前失败，返回常规错误信封）。带有 Accept: text/event-stream 时，响应体是逐条刷新的事件流：先是 progress，每完成一个条目发送一个 item，最后是 summary。否则为一份 JSON 文档；使用 Accept: application/cbor 时为一份 CBOR 文档。
事件形式为 event: <name> / data: <one-line JSON>，以空行分隔。名称：progress（BatchProgress）、item（BatchItem）、summary（BatchSummary，最后一个）。
示例
event: progressdata: {"done":0,"remaining":2}
event: itemdata: {"index":0,"status":"ok","result":{"id":"call_0193...","model":"dinov3","cost":0.05,"balance":9.95}}
event: progressdata: {"done":1,"remaining":1,"etaWaitMs":850}
event: itemdata: {"index":1,"status":"error","error":{"code":"insufficient_balance","message":"insufficient balance: this call can cost up to 0.05 credits"}}
event: summarydata: {"counts":{"ok":1,"error":1,"expired":0},"cost":0.05,"balance":0.01,"elapsedMs":2310}JSON 模式的响应（不推荐；见 BatchRequest）。
object
每个条目一项，按 index 排序。
单个条目的结果；item 事件的 data，也是 BatchResponse.items 的元素。
object
条目在请求中的位置。
ok：调用成功并已计费。error：调用失败，未计费。expired：条目完成前已超过批量时限；未计费。
状态为 ok 时：与单次调用的成功响应完全相同，包括 id、cost、balance、billing 和 timing。
object
状态为 error 时：单次调用的错误（余额不足只会使该条目失败；后续条目仍会逐条尝试）。
object
稳定的错误码，列于响应部分。
面向人的说明。
条目由相同 Idempotency-Key 下较早的批量回放而来时为 true；未运行，也未扣费。
最后的 summary 事件，也是 JSON 响应的 summary。
object
各状态的条目数量。
object
状态为 ok 的条目。
状态为 error 的条目。
状态为 expired 的条目。
本请求扣除的额度（回放的条目不会再次扣费）。
批量结束时的账户余额。
从请求到达到批量结束的时间，单位为毫秒。
示例
{ "items": [ { "status": "ok" } ]}JSON 模式的响应（不推荐；见 BatchRequest）。
object
每个条目一项，按 index 排序。
单个条目的结果；item 事件的 data，也是 BatchResponse.items 的元素。
object
条目在请求中的位置。
ok：调用成功并已计费。error：调用失败，未计费。expired：条目完成前已超过批量时限；未计费。
状态为 ok 时：与单次调用的成功响应完全相同，包括 id、cost、balance、billing 和 timing。
object
状态为 error 时：单次调用的错误（余额不足只会使该条目失败；后续条目仍会逐条尝试）。
object
稳定的错误码，列于响应部分。
面向人的说明。
条目由相同 Idempotency-Key 下较早的批量回放而来时为 true；未运行，也未扣费。
最后的 summary 事件，也是 JSON 响应的 summary。
object
各状态的条目数量。
object
状态为 ok 的条目。
状态为 error 的条目。
状态为 expired 的条目。
本请求扣除的额度（回放的条目不会再次扣费）。
批量结束时的账户余额。
从请求到达到批量结束的时间，单位为毫秒。
服务器生成的请求 ID（16 个十六进制字符）；出现在每个响应中。联系支持时应提供该值。
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 个十六进制字符）；出现在每个响应中。联系支持时应提供该值。