# API 文档

Foldbun Stack 是按量计费的计算机视觉模型 API。分割、文字识别、文档解析、向量嵌入和背景移除均可通过 HTTPS 访问 `https://api.stack.foldbun.com`。请求使用 API 密钥认证，按调用从预付余额中扣费。模型池每日包含额度内的调用免费，失败的调用不收费。

API 为同步调用：一次请求返回一次结果。异步任务和 webhook 暂不提供。

## 用例

每个任务一页：含配图的场景说明、模型选择和调用示例。

| 用例 | 接口 | 模型 |
|---|---|---|
| [交互分割](https://stack.foldbun.com/zh/docs/use-cases/interactive-segmentation/) | `POST /v1/segment`、`POST /v1/refine` | [`sam3`](https://stack.foldbun.com/zh/docs/models/sam3/)、[`sam-lite`](https://stack.foldbun.com/zh/docs/models/sam-lite/) |
| [概念分割](https://stack.foldbun.com/zh/docs/use-cases/concept-segmentation/) | `POST /v1/segment` | [`sam3`](https://stack.foldbun.com/zh/docs/models/sam3/) |
| [文字识别（OCR）](https://stack.foldbun.com/zh/docs/use-cases/text-recognition/) | `POST /v1/ocr` | [`ppocr-v6`](https://stack.foldbun.com/zh/docs/models/ppocr-v6/) |
| [文档解析](https://stack.foldbun.com/zh/docs/use-cases/document-parsing/) | `POST /v1/documents/parse` | [`paddleocr-vl`](https://stack.foldbun.com/zh/docs/models/paddleocr-vl/) |
| [嵌入与检索](https://stack.foldbun.com/zh/docs/use-cases/embeddings/) | `POST /v1/embeddings` | [`dinov3`](https://stack.foldbun.com/zh/docs/models/dinov3/)、[`siglip2`](https://stack.foldbun.com/zh/docs/models/siglip2/) |
| [抠图](https://stack.foldbun.com/zh/docs/use-cases/background-removal/) | `POST /v1/remove-background` | [`birefnet`](https://stack.foldbun.com/zh/docs/models/birefnet/) |

## 模型

单位与价格：[计费](https://stack.foldbun.com/zh/docs/billing/#价目表)。`GET /v1/models` 返回调用账户的实时目录；该请求免费，不计量。

| 模型 | 模型名称 | 用例 | 模型池 |
|---|---|---|---|
| [`sam3`](https://stack.foldbun.com/zh/docs/models/sam3/) | SAM 3（Meta） | [交互分割](https://stack.foldbun.com/zh/docs/use-cases/interactive-segmentation/)、[概念分割](https://stack.foldbun.com/zh/docs/use-cases/concept-segmentation/) | 付费 |
| [`sam-lite`](https://stack.foldbun.com/zh/docs/models/sam-lite/) | SAM 2.1 Hiera-S（Meta） | [交互分割](https://stack.foldbun.com/zh/docs/use-cases/interactive-segmentation/) | 免费 |
| [`ppocr-v6`](https://stack.foldbun.com/zh/docs/models/ppocr-v6/) | PP-OCRv6 small（PaddlePaddle） | [文字识别（OCR）](https://stack.foldbun.com/zh/docs/use-cases/text-recognition/) | 公共 |
| [`paddleocr-vl`](https://stack.foldbun.com/zh/docs/models/paddleocr-vl/) | PaddleOCR-VL 1.6（0.9B），配合 PP-DocLayoutV3 版面分析（PaddlePaddle） | [文档解析](https://stack.foldbun.com/zh/docs/use-cases/document-parsing/) | 付费 |
| [`dinov3`](https://stack.foldbun.com/zh/docs/models/dinov3/) | DINOv3 ViT-B/16（Meta） | [嵌入与检索](https://stack.foldbun.com/zh/docs/use-cases/embeddings/) | 公共 |
| [`siglip2`](https://stack.foldbun.com/zh/docs/models/siglip2/) | SigLIP 2 base，patch 16，224 px（Google） | [嵌入与检索](https://stack.foldbun.com/zh/docs/use-cases/embeddings/) | 公共 |
| [`birefnet`](https://stack.foldbun.com/zh/docs/models/birefnet/) | BiRefNet 通用模型（Peng Zheng 等） | [抠图](https://stack.foldbun.com/zh/docs/use-cases/background-removal/) | 付费 |

模型池决定账户可调用哪些模型：[速率限制与模型池](https://stack.foldbun.com/zh/docs/rate-limits/)。

## 调用流程

1. 在控制台创建 API 密钥。详见[快速开始](https://stack.foldbun.com/zh/docs/quickstart/)。
2. 以 base64 发送图片，或先上传一次，再复用返回的 `img_` 句柄。详见[图片](https://stack.foldbun.com/zh/docs/images/)。
3. 读取结果。每个成功响应都包含调用 `id`、`model`、`image`、本次调用的 `cost`、调用后的 `balance`、`timing` 对象和 `billing` 明细。详见[计费](https://stack.foldbun.com/zh/docs/billing/)；所有字段的说明见 [API 参考](https://stack.foldbun.com/zh/docs/api/)。

请求和响应中的所有坐标，均为摆正后的原图的像素坐标：即应用 EXIF 方向后、保持完整尺寸的上传图片。多边形和框使用同样的像素；按需返回的蒙版在 `mask.size` 中给出自己的网格尺寸。详见[图片](https://stack.foldbun.com/zh/docs/images/)和[后处理](https://stack.foldbun.com/zh/docs/post-processing/)。

## 后续阅读

- [快速开始](https://stack.foldbun.com/zh/docs/quickstart/)：使用 curl 和 Python 发送第一个请求。
- [用例](#用例)：每个任务一页，含模型选择和调用示例。
- [身份验证](https://stack.foldbun.com/zh/docs/authentication/)：API 密钥、模型范围和有效期。
- [错误](https://stack.foldbun.com/zh/docs/errors/)：错误信封、错误码和重试建议。
- [API 参考](https://stack.foldbun.com/zh/docs/api/)：由 OpenAPI 文档生成的全部接口和数据结构。
- [Playground](https://stack.foldbun.com/zh/docs/playground/)：无需账户，在浏览器中试用全部模型。