Segmentation

SAM 3 API: segmentation from text prompts

PaidModel licence: SAM License

SAM 3 finds every instance that matches a short text prompt or an exemplar box, and refines single objects with include and exclude clicks. Results are instances with simplified polygons (holes included), boxes and scores; pixel masks are available on request.

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.5 ≈ US$0.0005 top-up
Text prompt Each text phrase in `POST /v1/segment`. Exemplar boxes add no charge; a request with exemplar boxes but no text prompt is billed as one prompt.	per text prompt	0.05 ≈ US$0.00005 top-up
Point prompt Each point in `POST /v1/segment`.	per point	0.02 ≈ US$0.00002 top-up
Refinement Each `POST /v1/refine` call: one decode, whatever the number of points and whether a box is given.	per refinement	0.02 ≈ US$0.00002 top-up

Available to accounts with a balance (paid pool). Prices are in credits. Failed calls cost nothing.

Sample results

Recorded responses of the API on sample images.

Street scene: segmented 9 × "car", 18 × "person". — **Street scene**prompts: "car", "person"27 instances

Fruit stall: segmented 90 similar objects. — **Fruit stall**prompts: one exemplar box, no text90 instances

Living room: segmented 1 × "cat", 5 × "cushion". — **Living room**prompts: "cushion", "cat"6 instances

Request and response

POST https://api.stack.foldbun.com/v1/segment with a Bearer API key. Points in POST /v1/segment give one object each; clicks that refine one object use POST /v1/refine.

API reference

curlPythonRequest

# macOS: replace "base64 -w0 street.webp" with "base64 -i street.webp"
curl https://api.stack.foldbun.com/v1/segment \
  -H "Authorization: Bearer $FOLDBUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{"model": "sam3", "image": {"base64": "$(base64 -w0 street.webp)"},
 "prompts": [{"text": "car"}, {"text": "person"}],
 "options": {"defaults": {"filter": {"minScore": 0.5}}}}
EOF

import base64, os, requests

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

r = requests.post(
    "https://api.stack.foldbun.com/v1/segment",
    headers={"Authorization": f"Bearer {os.environ['FOLDBUN_API_KEY']}"},
    json={"model": "sam3",
          "image": {"base64": image},
          "prompts": [{"text": "car"}, {"text": "person"}],
          "options": {"defaults": {"filter": {"minScore": 0.5}}}},
    timeout=60,
)
r.raise_for_status()
print(r.json())

Response (shortened)

{
  "id": "call_01a1913c-25a0-73fd-a074-7a6ac6154590",
  "model": "sam3",
  "image": {"height": 1008, "id": "img_312c4e3a…c6e2", "width": 1343},
  "cache": "miss",
  "imageFee": 0.5,
  "instances": [
    {
      "score": 0.9696,
      "bbox": [0, 716, 207, 889],
      "area": 27120,
      "prompt": 0,
      "label": "car",
      "polygon": [
        {"outer": [47, 718, 100, 728, 132, 743, …]}
      ]
    }
    … 26 more
  ],
  "dropStats": [],
  "cost": 0.6,
  "balance": 1233.96
}

Request fields

Field	Description
image	`{"base64": "…"}` or `{"id": "img_…"}` from an earlier response.
prompts[].text	Short English noun phrase, 1–200 characters. All matching instances are returned.
prompts[].box	Exemplar box `[x1, y1, x2, y2]`; `positive: false` excludes look-alikes. At most 10.
prompts[].point	Point `{"x", "y"}` on one object; returns exactly that object.
options.defaults	Post-processing for all prompts: `geometry`, `polygon`, `mask`, `filter` (`minScore` defaults to 0.5), `cleanup`, `merge`. `prompts[].options` overrides it per prompt.
options.maxInstances	1–300, default 100.
options.nms	Overlap removal between instances.

Pricing examples

Call	Credits
1 image, 1 text prompt 0.5 + 0.05	0.55 ≈ US$0.00055 top-up
1 image, 5 text prompts 0.5 + 5 × 0.05	0.75 ≈ US$0.00075 top-up
1 image, 2 text prompts and 1 exemplar box 0.5 + 2 × 0.05	0.6 ≈ US$0.0006 top-up
1,000 images, 2 text prompts each 1,000 × (0.5 + 2 × 0.05)	600 ≈ US$0.60 top-up

Without a cache hit. A cache hit can waive the 0.5 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 call: Up to 50 (text, exemplar boxes and points), of which at most 10 exemplar boxes
Clicks per refine call: Up to 20 points
Rate limit: Depends on the account tier; see GET /v1/models

Frequently asked questions

How is SAM 3 billed?

Each call pays the image encoding (0.5 credits) plus 0.05 credits per text prompt; exemplar boxes add no charge, and a request with exemplar boxes but no text prompt is billed as one prompt. Refine calls (POST /v1/refine) pay the image encoding plus 0.02 credits per call, whatever the number of points; point prompts in POST /v1/segment pay 0.02 credits each. The encoding fee is 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.

What is the difference between sam3 and sam-lite?

sam3 accepts text prompts, exemplar boxes and point prompts; text and exemplars return every matching instance, a point returns one object. sam-lite (SAM 2.1 Hiera-S) segments one object per point or box, costs less and is part of the free pool.

Which geometry is returned?

A simplified polygon with holes, in image pixels, by default (tolerance 0.001 × image diagonal). Masks are returned on request with geometry: ["mask"], as COCO compressed RLE or a lossless WebP crop on a grid whose long side options.maskSize sets (default 2048 px).

Related models

Models and pricing

Foldbun Stack — pay-per-use vision model API

Call SAM 3 through the REST API; the docs list request and response formats.

Read the docsGet an API keyComing soon