# SAM 2.1 Hiera-S (sam-lite)

`sam-lite` is SAM 2.1 Hiera-S, the small variant of the Segment Anything Model 2.1 by Meta. It segments one object per prompt from a box or a point, costs less than `sam3`, and is part of the free pool. It does not accept text prompts, and it has no "find more like this" mode.

| | |
|---|---|
| Model ID | `sam-lite` |
| Model | SAM 2.1 Hiera-S (Meta) |
| Weights | Official SAM 2.1 Hiera-S checkpoint by Meta |
| Use cases | [Interactive segmentation](https://stack.foldbun.com/docs/use-cases/interactive-segmentation/) |
| Endpoints | `POST /v1/segment`, `POST /v1/refine` |
| Pool | Free (after the first top-up): the first 1,000 calls per UTC day are free, then billed from the balance |
| Billing units | `encode_image` (waived on a cache hit), `box`, `point`, `refine`. Units and prices: [Billing](https://stack.foldbun.com/docs/billing/#price-list) |
| Licence | Apache-2.0 |

## How it works

A call has two stages: the image is encoded once, and every prompt is then decoded separately. Billing follows these two stages.

**Image encoding.** The image is resized to 1024 × 1024 pixels and passed through the Hiera-S image encoder, a hierarchical vision transformer that turns the image into feature maps. This is billed once per call as `encode_image`. The result is cached per account and image, on a best-effort basis (deleted after at most 7 days); when a later call finds the encoding in the cache, the stage is skipped and the fee is waived. The cached encoding is stored compactly, so a result on a cache hit can differ very slightly from a fresh encode.

**Prompts.** A light prompt encoder turns points and boxes into embeddings, and a light mask decoder produces the mask. The prompts of a `/v1/segment` call are batched through the decoder, but each prompt yields its own mask, so each prompt is billed (`point` or `box`). Each mask also needs post-processing, upsampling to the image size and polygon tracing, and this work grows with the size of the image. A single point is ambiguous, so the decoder predicts 3 candidate masks for it and the best one by predicted IoU is returned; the `score` of an instance is that predicted IoU.

**Refinement.** `POST /v1/refine` is one decode for one object. All points and the optional box are inputs of that single pass, so a call is billed once as `refine`, however many points it carries. With `options.multimask`, the candidates of the pass (up to 3) are returned instead of the best one.

## In each use case

### Interactive segmentation

- **`POST /v1/segment`** takes `box` (the object inside the box) and `point` (the object under the point) prompts, mixed in one call, and returns exactly one instance per prompt. Each instance holds `prompt`, `score`, `bbox`, `area` and `polygon`, and no `label`.
- `positive` is not used: a box always marks the object and a point is always positive. Negative points belong to `POST /v1/refine`.
- Text prompts and exemplar boxes are not accepted, and there is no "find more like this" mode. Concept prompts are served by [`sam3`](https://stack.foldbun.com/docs/models/sam3/#concept-segmentation).
- Every prompt is an object prompt, so it is always returned: `filter`, `nms` and `options.maxInstances` do not apply. `cleanup`, the geometry options and `merge` do; see [Post-processing](https://stack.foldbun.com/docs/post-processing/).
- **`POST /v1/refine`** takes up to 20 positive and negative points and an optional box for one object. The response holds the best mask, or up to 3 candidates with `options.multimask`. The whole call is one decode. The call has interactive priority with a 2 second deadline.

Comparison with [`sam3`](https://stack.foldbun.com/docs/models/sam3/): [Interactive segmentation](https://stack.foldbun.com/docs/use-cases/interactive-segmentation/#supported-models).

Use case guide and example call: [Interactive segmentation](https://stack.foldbun.com/docs/use-cases/interactive-segmentation/).

### Concept segmentation

Not supported. `sam-lite` accepts neither text prompts nor exemplar boxes. Use [`sam3`](https://stack.foldbun.com/docs/models/sam3/#concept-segmentation) to find every instance of a concept.

## Limits and notes

- 1 to 50 prompts per segment call (boxes and points together); at most 20 points per refine call, with at least one point or a box.
- Boxes and points must be non-negative and lie inside the image.
- Image limits: see [Images](https://stack.foldbun.com/docs/images/). All coordinates are pixels of the oriented original. Polygons and boxes are in image pixels. A requested mask lies on a grid whose long side is at most `options.maskSize` (default 2048 px): scale it by `mask.size`.
- Latency: recorded Playground calls had `timing.processingMs` of about 180 ms. The figure depends on the image, on queueing and on node load, and it is not a guarantee.