Segmentation

SAM 2.1 API: segmentation from points and boxes

FreeModel licence: Apache 2.0

SAM 2.1 Hiera-S segments one object per point or box. It costs less than SAM 3, needs no text and is included in the free pool.

Read the docsGet an API keyComing soonAPI reference

Price

Billed item	Unit	Credits
Image encoding Charged once per call. Waived while the encoding of the same image is still cached for the account; cached encodings are kept for at most 7 days and may be dropped earlier.	per image	0.2 ≈ US$0.0002 top-up
Point or box prompt Each point or box in `POST /v1/segment`.	per point or box	0.01 ≈ US$0.00001 top-up
Refinement Each `POST /v1/refine` call: one decode, whatever the number of points and whether a box is given.	per refinement	0.01 ≈ US$0.00001 top-up

Included in the free pool: 1,000 calls per day after the first top-up. Prices are in credits. Failed calls cost nothing.

Sample results

Recorded responses of the API on sample images.

Dog on grass: object outline segmented from one prompt. — **Dog on grass**1 point (include)1 mask

Kitchen counter: object outline segmented from one prompt. — **Kitchen counter**1 box1 mask

Bicycle: object outline segmented from one prompt. — **Bicycle**1 point (include)1 mask

Request and response

POST https://api.stack.foldbun.com/v1/refine with a Bearer API key. Several points or boxes in one call, one mask each, use POST /v1/segment.

API reference

curlPythonRequest

# macOS: replace "base64 -w0 dog.webp" with "base64 -i dog.webp"
curl https://api.stack.foldbun.com/v1/refine \
  -H "Authorization: Bearer $FOLDBUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{"model": "sam-lite", "image": {"base64": "$(base64 -w0 dog.webp)"},
 "points": [{"x": 760, "y": 560, "positive": true}]}
EOF

import base64, os, requests

with open("dog.webp", "rb") as f:
    image = base64.b64encode(f.read()).decode()

r = requests.post(
    "https://api.stack.foldbun.com/v1/refine",
    headers={"Authorization": f"Bearer {os.environ['FOLDBUN_API_KEY']}"},
    json={"model": "sam-lite",
          "image": {"base64": image},
          "points": [{"x": 760, "y": 560, "positive": True}]},
    timeout=60,
)
r.raise_for_status()
print(r.json())

Response (shortened)

{
  "id": "call_01a1913c-4de0-7f15-afbd-d26a0d0c347f",
  "model": "sam-lite",
  "image": {"height": 1008, "id": "img_3b73d411…5b12", "width": 1512},
  "cache": "miss",
  "imageFee": 0.2,
  "instances": [
    {
      "score": 0.9844,
      "bbox": [382, 102, 1171, 912],
      "area": 295827,
      "polygon": [
        {
          "outer": [894, 134, 906, 151, 907, 159, …],
          "holes": [
            [699, 695, 703, 691, 670, 670, …]
          ]
        }
      ]
    }
  ],
  "cost": 0.21,
  "balance": 1234.35
}

Request fields

Field	Description
image	`{"base64": "…"}` or `{"id": "img_…"}` from an earlier response.
points[]	Up to 20 points `{"x", "y", "positive"}` on one object; `positive: false` excludes an area.
box	Optional box `[x1, y1, x2, y2]` around the object.
options.multimask	Return up to 3 candidate masks instead of the best one.
prompts[]	`POST /v1/segment`: 1–50 prompts, each a `box` or a `point`; one instance per prompt.
options.defaults	Output options for all prompts, for example `geometry: ["mask"]`. `prompts[].options` overrides it per prompt.

Pricing examples

Call	Credits
1 image, 1 point 0.2 + 0.01	0.21 ≈ US$0.00021 top-up
1 image, 5 boxes 0.2 + 5 × 0.01	0.25 ≈ US$0.00025 top-up
1,000 images, 1 point each 1,000 × (0.2 + 0.01)	210 ≈ US$0.21 top-up

Without a cache hit. A cache hit can waive the 0.2 encoding fee; this is not guaranteed.

Limits

Images: JPEG, PNG, static WebP; up to 20 MiB and 40 megapixels
Coordinates: Pixels of the original image with EXIF orientation applied; masks can be smaller and carry their own size
Prompts per segment call: Up to 50 points or boxes, one instance each
Points per refine call: Up to 20 points
Rate limit: Depends on the account tier; see GET /v1/models

Frequently asked questions

How is SAM 2.1 billed?

Each call pays the image encoding (0.2 credits). A segment call adds 0.01 credits per point or box; a refine call adds 0.01 credits, whatever the number of points and whether a box is given. The model is in the free pool: 1,000 calls per day at no charge after the first top-up.

What is the difference between sam-lite and sam3?

sam-lite takes points and boxes only and segments one object per point or box; it costs less than sam3 and is part of the free pool. sam3 accepts text prompts, exemplar boxes and point prompts; text and exemplars return every matching instance, and a point returns one object.

How are points and boxes sent?

The refine endpoint takes up to 20 include or exclude points and an optional box for a single object. The segment endpoint takes up to 50 prompts, each a point or a box, and returns one instance per prompt.

Related models

Models and pricing

Foldbun Stack — pay-per-use vision model API

Call SAM 2.1 Hiera-S through the REST API; the docs list request and response formats.

Read the docsGet an API keyComing soon