概览

Foldbun Stack 公共 API 0.1.0-draft

按用量付费的计算机视觉模型 API（分割、OCR、文档解析、向量嵌入、背景移除）。v1 草案：仅支持同步调用；异步任务和 webhook 后续提供。

请求 ID。 每个响应（包括错误响应）都带有 X-Request-Id：由服务器生成的 16 个随机十六进制字符（客户端发送的该请求头会被忽略）。联系支持时应提供该值。

认证。 Authorization: Bearer fbs_...（在控制台创建的 API 密钥）。密钥可带有 model:<id> 范围；带有范围时，只能调用这些模型。

金额。 金额单位为额度，以 JSON 数字表示，最多 6 位小数（最小单位为微额度，因此金额是精确的）。储值按 US$1 = 1,000 额度到账。cost 为本次调用的扣费，balance 为调用后的账户余额。失败的调用不收费。

图片。 每个图片输入均为 {"id": "img_<sha256>"}、{"base64": "..."} 或 {"url": "https://..."}（url 为预留：后续提供，目前返回 400 unsupported）。上传的图片由 Stack 清理，内嵌的 image.base64 与上传的处理方式相同：元数据（EXIF、XMP、注释、缩略图）和附加在图片之后的数据在上传时删除，像素不会被修改或重新编码。图片本身最长保留 7 天（见下文）。图片不会转发给 GPU 节点，节点只收到 Stack 按模型生成的缩放副本。请求和响应中的所有坐标均为摆正后的原图的像素坐标：即应用 EXIF 方向后的上传图片，保持完整尺寸。其尺寸以 image.width / image.height 返回（POST /v1/images 也会返回）；不会缩放，除下文的输入限制外，也没有短边限制。框和多边形始终以图片像素表示；蒙版可以比图片小：蒙版在 mask.size 中给出自己的尺寸，客户端应按其缩放（见 options.maskSize）。img_<sha256> 是清理后字节的 SHA-256（不是上传文件的 SHA-256）。句柄只在上传它的账户内有效，并按尽力而为的方式保留，最长保留 7 天后删除，从账户首次存储该图片时起算（容量不足时更早淘汰，先淘汰最久未使用的图片；不设最短保留期限）：遇到 404 image_not_found 时，应重新上传。图片存储暂时不可用时，调用返回带有 Retry-After 的 503 unavailable。通过了上传检查但无法解码的文件，在首次使用时返回 400 invalid_image；该句柄之后始终返回 invalid_image，且调用不收费。接受的格式：JPEG、PNG、静态 WebP；每次上传最大 20 MiB 和 40 百万像素（每边 16384 px），JPEG 最多 64 个扫描段（常见编码器生成的渐进式文件约 10 个；超出返回 400 invalid_request）；JSON 请求体最大 28 MiB，以容纳 base64 图片。

缓存与 SAM 编码费。 SAM 系列模型（sam3、sam-lite）每次调用收取图片编码费（encode_image）。同一张图片的编码已为调用账户计算过、且仍缓存在 GPU 节点上时，该费用减免，响应中带有 "cache": "hit" 和 "imageFee": 0。这是额外的好处，而非承诺：缓存的编码最长保留 7 天后删除，容量不足时更早淘汰，不设最短保留期限。缓存按账户隔离，不会在账户之间共享。

分割结果。 默认情况下，实例带有含洞的简化多边形，不带蒙版；蒙版（COCO 压缩 RLE 或无损 WebP 裁剪区域）按需返回。后处理（分数和尺寸过滤、清理、重叠去除、合并）免费，按提示配置；见 SegmentRequest 和 SegmentOptions。

CBOR 响应。 Accept 列出 application/cbor 时，POST /v1/segment、POST /v1/refine、POST /v1/remove-background 以及 POST /v1/batch/{endpoint} 的 JSON 模式以 CBOR（RFC 8949，Content-Type: application/cbor）响应；其他 Accept 返回 JSON。结构和键名与 JSON 响应相同。多边形环（outer 以及 holes 的每一项）为 RFC 8746 类型化数组，tag 69（uint16，小端序，x 与 y 交错，图片像素绝对坐标）；二进制载荷（WebP 蒙版和背景移除的 data）为字节串而非 base64；整数为 CBOR 整数，其他数字为浮点数。请求、错误和事件流始终为 JSON。重放的响应（Idempotency-Key）按重复请求的 Accept 编码。

错误。 {"error": {"code", "message", "retryable", "retryAfterMs"}}。429 和 503 带有 Retry-After 响应头（单位为秒）。错误码列于 Error Schema 中。

幂等。 对任何会消耗额度的 POST 请求发送 Idempotency-Key: <1..128 printable ASCII>。在同一账户内，密钥保留 24 小时。使用相同请求体重复请求，会返回原始响应（状态码和响应体，另带响应头 Idempotent-Replayed: true），且不会再次扣费或运行；相同密钥搭配不同请求体返回 409 idempotency_conflict；第一个请求仍在运行时使用相同密钥返回 409 request_in_progress。只保存最终结果（2xx 和永久性的 4xx）；402、429 或 5xx 会释放该密钥，因此可以用同一密钥重试相同的请求。请求体格式错误（结构检查返回的 400 invalid_request）以及调用的 API 密钥无权使用的模型（403 model_locked）会在查找 Idempotency-Key 之前返回：这两种响应既不保存也不重放，因此密钥永远不会收到其无权调用的模型的已保存响应。

模型池与限制。 密钥可调用哪些模型、调用速度多快，取决于账户层级（适用于调用账户的内容见 GET /v1/models）。已注册账户使用公共池（少数模型，每个 UTC 日 100 次调用，每分钟 10 次，超出返回 429 daily_limit_reached）；已储值账户还可使用免费池（每个 UTC 日包含 1,000 次免费调用），并且所有模型均可用余额调用。免费池的每分钟 60 次只用于控制包含额度内调用的速度：超出每日额度的调用，或每分钟超过 60 次的调用，按正常价格从余额中扣费，且没有每分钟限制（账户的并发限制仍然适用）。因超出速率而需要计费、但余额无法支付的调用返回 429 rate_limited。余额不足返回 402 insufficient_balance。

批量。 POST /v1/batch/{endpoint} 在一个请求中，对同一端点（segment、ocr、documents/parse、embeddings、remove-background）、同一模型，依次运行最多 1,000 个单次调用请求体（items）。条目以批量等级调度（低于交互和同步流量，账户之间公平）。每个条目按单次调用的方式计价、计费和结算，完成后立即生效；每分钟限速对整个请求只消耗一个令牌。条目中的图片必须是 {"id": "img_..."} 句柄（需先上传）。推荐使用 Server-Sent Events（Accept: text/event-stream）：结果逐条到达，进度心跳保持连接（最长 600 秒）。普通 JSON 模式等待全部条目完成，限制为 90 秒；条目较多时不推荐。timeoutSec 只能缩短时限。时限到达时未完成的条目以 expired 返回，不计费。带有 Idempotency-Key 时，重复提交的批量会重放已完成的条目。Playground 试用通道不提供批量。

更多。 指南：快速开始、错误、速率限制与模型池、计费。机器可读的契约为 openapi.yaml。

信息

OpenAPI 版本： 3.1.0

身份验证

bearer

在控制台创建的 API 密钥，以 Authorization: Bearer fbs_... 发送。密钥由 fbs_ 加 43 个 base62 字符和 6 个字符的校验和组成。密钥可带有 model:<id> 范围；带有范围时，只能调用这些模型（否则返回 403 model_locked）。密钥缺失、格式错误、已过期或已吊销时返回 401 unauthorized。

安全方案类型： http

Bearer 格式： API key

概览

Foldbun Stack 公共 API 0.1.0-draft

接口

身份验证

bearer