Sam V2.1 Hiera Large Serverless API

Meta's next-gen segmentation model for images and video.

~24.91s
PlaygroundAPI
Pricing
POST /v2/sam-v21-hiera-large · submit + poll
 1# pip install "segmind>=1.1.0"
 2# export SEGMIND_API_KEY="YOUR_API_KEY"
 3import segmind
 4
 5# Async (v2): submit to the queue and block until COMPLETED.
 6# run() returns the final result dict (600s deadline, 1.0s poll by default).
 7result = segmind.run(
 8    "sam-v21-hiera-large",
 9    image="https://huggingface.co/datasets/hf-internal-testing/sam2-fixtures/resolve/main/truck.jpg",
10    make_overlay=True,
11    save_polygons=True,
12    save_rle=True,
13    save_pngs=True,
14    points_per_side=32,
15    points_per_batch=64,
16    pred_iou_thresh=0.86,
17    stability_score_thresh=0,
18    min_mask_region_area=0,
19    nms_iou_thresh=0.7,
20    max_masks=0,
21    polygon_epsilon=0,
22    tile_size=0,
23    tile_stride=0,
24)
25print(result["status"])                      # COMPLETED
26print(result.get("output"))                  # model output (e.g. media URL)
27print(result["metrics"]["inference_time"])   # server compute seconds
28
29# --- Or submit + poll manually (track request_id, control the cadence) ---
30from segmind import SegmindClient, InferenceFailed, InferenceTimeout
31
32client = SegmindClient()                      # reads SEGMIND_API_KEY
33payload = {
34    "image": "https://huggingface.co/datasets/hf-internal-testing/sam2-fixtures/resolve/main/truck.jpg",
35    "make_overlay": True,
36    "save_polygons": True,
37    "save_rle": True,
38    "save_pngs": True,
39    "points_per_side": 32,
40    "points_per_batch": 64,
41    "pred_iou_thresh": 0.86,
42    "stability_score_thresh": 0,
43    "min_mask_region_area": 0,
44    "nms_iou_thresh": 0.7,
45    "max_masks": 0,
46    "polygon_epsilon": 0,
47    "tile_size": 0,
48    "tile_stride": 0,
49}
50job = client.submit_async("sam-v21-hiera-large", **payload)
51print(job.request_id)                         # available immediately
52try:
53    result = job.wait(timeout=600, interval=1.0)
54except InferenceTimeout as e:
55    print("still running:", e.request_id)
56except InferenceFailed as e:
57    print("failed:", e.detail)

API Endpoint

POSThttps://api.segmind.com/v1/sam-v21-hiera-large

Parameters

imagerequired
string (uri)

Input image URL or base64 encoded image

Default: "https://huggingface.co/datasets/hf-internal-testing/sam2-fixtures/resolve/main/truck.jpg"
make_overlayoptional
boolean

Generate overlay image with masks

Default: true
max_masksoptional
integer

Maximum number of masks to return (0 = no limit)

Default: 0Range: 0 - 100
min_mask_region_areaoptional
integer

Minimum mask area in pixels

Default: 0Range: 0 - 10000
nms_iou_threshoptional
number

Non-Maximum Suppression IoU threshold

Default: 0.7Range: 0 - 1
points_per_batchoptional
integer

Number of points per batch for processing

Default: 64Range: 16 - 128
points_per_sideoptional
integer

Number of points per side for mask generation

Default: 32Range: 8 - 64
polygon_epsilonoptional
number

Epsilon for polygon simplification

Default: 0Range: 0 - 10
pred_iou_threshoptional
number

Prediction IoU threshold for mask filtering

Default: 0.86Range: 0.5 - 1
save_pngsoptional
boolean

Generate individual PNG masks in ZIP

Default: true
save_polygonsoptional
boolean

Include polygon coordinates in output

Default: true
save_rleoptional
boolean

Include COCO RLE format in output

Default: true
stability_score_threshoptional
number

Stability score threshold for mask filtering

Default: 0Range: 0 - 1
tile_sizeoptional
integer

Tile size for large images (0 = disabled)

Default: 0Range: 0 - 2048
tile_strideoptional
integer

Tile stride for large images (0 = use tile_size)

Default: 0Range: 0 - 2048

Response Type

Returns: Text/JSON

Asynchronous requests (v2)

Use Async for video, long-running (>~60s), or high-concurrency workloads; Sync is simplest for fast image & LLM calls. Async submits a request and you poll it to completion.

  1. 1
    POST /v2/sam-v21-hiera-large

    Submit — returns request_id, status_url, response_url

  2. 2
    GET /v2/requests/{id}/status

    Poll — until COMPLETED or FAILED

  3. 3
    GET /v2/requests/{id}

    Result — final response body

Status states

QUEUED— Accepted, waiting for a worker
PROCESSING— Running on a worker
COMPLETED— Done — result body is ready
FAILED— Errored (incl. content/RAI blocks)
  • A FAILED request is served as HTTP 422 — the body still carries the error detail.
  • An unknown or expired request_id returns HTTP 404.
  • Results are retained for 1 hour, then expire.
  • Content / RAI blocks surface as FAILED, not a separate state.
  • Track completion by polling the status endpoint.

Common Error Codes

The API returns standard HTTP status codes. Detailed error messages are provided in the response body.

400

Bad Request

Invalid parameters or request format

401

Unauthorized

Missing or invalid API key

403

Forbidden

Insufficient permissions

404

Not Found

Model or endpoint not found

406

Insufficient Credits

Not enough credits to process request

429

Rate Limited

Too many requests

500

Server Error

Internal server error

502

Bad Gateway

Service temporarily unavailable

504

Timeout

Request timed out