# API documentation

Foldbun Stack is a pay-per-use computer-vision model API. Segmentation, text recognition, document parsing, embeddings and background removal are available over HTTPS at `https://api.stack.foldbun.com`. Requests are authenticated with an API key and billed per call from a prepaid balance. Calls inside a pool's daily allowance are free of charge, and failed calls cost nothing.

The API is synchronous: one request returns one result. Asynchronous jobs and webhooks are not available yet.

## Use cases

One page per task: scenarios with figures, model choice and an example call.

| Use case | Endpoint | Models |
|---|---|---|
| [Interactive segmentation](https://stack.foldbun.com/docs/use-cases/interactive-segmentation/) | `POST /v1/segment`, `POST /v1/refine` | [`sam3`](https://stack.foldbun.com/docs/models/sam3/), [`sam-lite`](https://stack.foldbun.com/docs/models/sam-lite/) |
| [Concept segmentation](https://stack.foldbun.com/docs/use-cases/concept-segmentation/) | `POST /v1/segment` | [`sam3`](https://stack.foldbun.com/docs/models/sam3/) |
| [Text recognition (OCR)](https://stack.foldbun.com/docs/use-cases/text-recognition/) | `POST /v1/ocr` | [`ppocr-v6`](https://stack.foldbun.com/docs/models/ppocr-v6/) |
| [Document parsing](https://stack.foldbun.com/docs/use-cases/document-parsing/) | `POST /v1/documents/parse` | [`paddleocr-vl`](https://stack.foldbun.com/docs/models/paddleocr-vl/) |
| [Embeddings and search](https://stack.foldbun.com/docs/use-cases/embeddings/) | `POST /v1/embeddings` | [`dinov3`](https://stack.foldbun.com/docs/models/dinov3/), [`siglip2`](https://stack.foldbun.com/docs/models/siglip2/) |
| [Background removal](https://stack.foldbun.com/docs/use-cases/background-removal/) | `POST /v1/remove-background` | [`birefnet`](https://stack.foldbun.com/docs/models/birefnet/) |

## Models

Units and prices: [Billing](https://stack.foldbun.com/docs/billing/#price-list). `GET /v1/models` returns the live catalog for the calling account; the request is free and not metered.

| Model | Model name | Use cases | Pool |
|---|---|---|---|
| [`sam3`](https://stack.foldbun.com/docs/models/sam3/) | SAM 3 (Meta) | [Interactive segmentation](https://stack.foldbun.com/docs/use-cases/interactive-segmentation/), [Concept segmentation](https://stack.foldbun.com/docs/use-cases/concept-segmentation/) | Paid |
| [`sam-lite`](https://stack.foldbun.com/docs/models/sam-lite/) | SAM 2.1 Hiera-S (Meta) | [Interactive segmentation](https://stack.foldbun.com/docs/use-cases/interactive-segmentation/) | Free |
| [`ppocr-v6`](https://stack.foldbun.com/docs/models/ppocr-v6/) | PP-OCRv6 small (PaddlePaddle) | [Text recognition (OCR)](https://stack.foldbun.com/docs/use-cases/text-recognition/) | Public |
| [`paddleocr-vl`](https://stack.foldbun.com/docs/models/paddleocr-vl/) | PaddleOCR-VL 1.6 (0.9B) with PP-DocLayoutV3 layout analysis (PaddlePaddle) | [Document parsing](https://stack.foldbun.com/docs/use-cases/document-parsing/) | Paid |
| [`dinov3`](https://stack.foldbun.com/docs/models/dinov3/) | DINOv3 ViT-B/16 (Meta) | [Embeddings and search](https://stack.foldbun.com/docs/use-cases/embeddings/) | Public |
| [`siglip2`](https://stack.foldbun.com/docs/models/siglip2/) | SigLIP 2 base, patch 16, 224 px (Google) | [Embeddings and search](https://stack.foldbun.com/docs/use-cases/embeddings/) | Public |
| [`birefnet`](https://stack.foldbun.com/docs/models/birefnet/) | BiRefNet, general model (Peng Zheng et al.) | [Background removal](https://stack.foldbun.com/docs/use-cases/background-removal/) | Paid |

Pools decide which models an account can call: [Rate limits and pools](https://stack.foldbun.com/docs/rate-limits/).

## How a call works

1. Create an API key in the console. See [Quickstart](https://stack.foldbun.com/docs/quickstart/).
2. Send the image as base64, or upload it once and reuse the returned `img_` handle. See [Images](https://stack.foldbun.com/docs/images/).
3. Read the result. Every successful response carries the call `id`, the `model`, the `image`, the `cost` of the call, the `balance` after it, a `timing` object and a `billing` breakdown. See [Billing](https://stack.foldbun.com/docs/billing/); every field is described in the [API reference](https://stack.foldbun.com/docs/api/).

All coordinates in requests and responses are pixels of the oriented original: the uploaded image at full size with its EXIF orientation applied. Polygons and boxes use the same pixels; a requested mask carries its own grid size in `mask.size`. See [Images](https://stack.foldbun.com/docs/images/) and [Post-processing](https://stack.foldbun.com/docs/post-processing/).

## Where to go next

- [Quickstart](https://stack.foldbun.com/docs/quickstart/): first request with curl and Python.
- [Use cases](#use-cases): one page per task, with model choice and an example call.
- [Authentication](https://stack.foldbun.com/docs/authentication/): API keys, model scopes and expiry.
- [Errors](https://stack.foldbun.com/docs/errors/): the error envelope, codes and retry guidance.
- [API reference](https://stack.foldbun.com/docs/api/): every endpoint and schema, generated from the OpenAPI document.
- [Playground](https://stack.foldbun.com/docs/playground/): try every model in the browser without an account.