分割
SAM 3 API：按文本提示分割
SAM 3 根据简短的文本提示或样例框找出所有匹配的实例，并可通过包含和排除点选细化单个对象。结果为带含洞简化多边形的实例、框和分数；像素蒙版按需返回。
价格
| 计费项 | 单位 | 额度 |
|---|---|---|
| 图像编码 每次调用收取一次。同一图像的编码仍在该账户的缓存中时免收；缓存最长保留 7 天，也可能更早被清除。 | 每张图像 | 0.5 按储值折合约 US$0.0005 |
文本提示POST /v1/segment 中的每个文本短语。样例框不另外收费；只含样例框而无文本提示的请求按一个提示计。 | 每个文本提示 | 0.05 按储值折合约 US$0.00005 |
点提示POST /v1/segment 中的每个点。 | 每个点 | 0.02 按储值折合约 US$0.00002 |
| 细化 每次 POST /v1/refine 调用：按一次解码计，与点的数量以及是否给出框无关。 | 每次细化 | 0.02 按储值折合约 US$0.00002 |
有余额的账户可用（付费）。 价格以额度计。调用失败不收费。
示例结果
API 在示例图片上的实际响应记录。
请求与响应
POST https://api.stack.foldbun.com/v1/segment，使用 Bearer API 密钥。POST /v1/segment 中每个点提示返回一个对象；细化单个对象的点选使用 POST /v1/refine。
请求
# macOS：把 "base64 -w0 street.webp" 换成 "base64 -i street.webp" curl https://api.stack.foldbun.com/v1/segment \ -H "Authorization: Bearer $FOLDBUN_API_KEY" \ -H "Content-Type: application/json" \ -d @- <<EOF {"model": "sam3", "image": {"base64": "$(base64 -w0 street.webp)"}, "prompts": [{"text": "car"}, {"text": "person"}], "options": {"defaults": {"filter": {"minScore": 0.5}}}} EOF
import base64, os, requests with open("street.webp", "rb") as f: image = base64.b64encode(f.read()).decode() r = requests.post( "https://api.stack.foldbun.com/v1/segment", headers={"Authorization": f"Bearer {os.environ['FOLDBUN_API_KEY']}"}, json={"model": "sam3", "image": {"base64": image}, "prompts": [{"text": "car"}, {"text": "person"}], "options": {"defaults": {"filter": {"minScore": 0.5}}}}, timeout=60, ) r.raise_for_status() print(r.json())
响应（节选）
{
"id": "call_01a1913c-25a0-73fd-a074-7a6ac6154590",
"model": "sam3",
"image": {"height": 1008, "id": "img_312c4e3a…c6e2", "width": 1343},
"cache": "miss",
"imageFee": 0.5,
"instances": [
{
"score": 0.9696,
"bbox": [0, 716, 207, 889],
"area": 27120,
"prompt": 0,
"label": "car",
"polygon": [
{"outer": [47, 718, 100, 728, 132, 743, …]}
]
}
… 26 more
],
"dropStats": [],
"cost": 0.6,
"balance": 1233.96
}请求字段
| 字段 | 说明 |
|---|---|
| image | {"base64": "…"}，或之前响应返回的 {"id": "img_…"}。 |
| prompts[].text | 简短的英文名词短语，1–200 个字符。返回所有匹配的实例。 |
| prompts[].box | 样例框 [x1, y1, x2, y2]；positive: false 用于排除相似对象。最多 10 个。 |
| prompts[].point | 对象上的点 {"x", "y"}；只返回该对象。 |
| options.defaults | 所有提示的后处理：geometry、polygon、mask、filter（minScore 默认 0.5）、cleanup、merge。prompts[].options 按提示覆盖。 |
| options.maxInstances | 1–300，默认 100。 |
| options.nms | 实例之间的重叠去除。 |
价格示例
| 调用 | 额度 |
|---|---|
| 1 张图，1 个文本提示 0.5 + 0.05 | 0.55 按储值折合约 US$0.00055 |
| 1 张图，5 个文本提示 0.5 + 5 × 0.05 | 0.75 按储值折合约 US$0.00075 |
| 1 张图，2 个文本提示和 1 个样例框 0.5 + 2 × 0.05 | 0.6 按储值折合约 US$0.0006 |
| 1,000 张图，每张 2 个文本提示 1,000 × (0.5 + 2 × 0.05) | 600 按储值折合约 US$0.60 |
按未命中缓存计算。缓存命中时可能减免 0.5 的编码费，不作保证。
限制
- 图片
- JPEG、PNG、静态 WebP；最大 20 MiB、4,000 万像素
- 坐标
- 按 EXIF 摆正后的原图的像素；蒙版可以比图小，并附带自己的尺寸
- 每次调用的提示数
- 最多 50 个（文本、样例框和点），其中样例框最多 10 个
- 每次细化调用的点选数
- 最多 20 个点
- 速率限制
- 取决于账户档位，见
GET /v1/models
常见问题
SAM 3 如何计费？
每次调用收取图像编码费（0.5 额度），每个文本提示另收 0.05 额度，样例框不另外收费，只含样例框而无文本提示的请求按一个提示计；细化调用（POST /v1/refine）收取图像编码费，另按每次调用收取 0.02 额度，与点的数量无关；POST /v1/segment 中的点提示每个收取 0.02 额度。同一图像的编码仍在该账户的缓存中时免收编码费；缓存最长保留 7 天，也可能更早被清除。
sam3 和 sam-lite 有什么区别？
sam3 支持文本提示、样例框和点提示：文本和样例框返回所有匹配实例，点提示返回一个对象；sam-lite（SAM 2.1 Hiera-S）每个点或框分割一个对象，价格更低，并包含在免费池中。
返回什么几何数据？
默认返回图片像素坐标下的含洞简化多边形（容差为图片对角线的 0.001）。设置 geometry: ["mask"] 时按需返回蒙版：COCO 压缩 RLE 或无损 WebP 裁剪区域，蒙版网格的长边由 options.maskSize 设置（默认 2048 px）。
相关模型
Foldbun Stack — 按量计费的视觉模型 API
通过 REST API 调用 SAM 3，请求与响应格式见文档。
阅读文档获取 API 密钥即将推出