Skip to main content
Segment objects in an image using point or box prompts with SAM 2.

​
Parameters

​
image_input
str | PIL.Image | np.ndarray
required
RGB image.
​
prompts
List[List[int]]
required
List of [x, y] pixel coordinates.
​
labels
List[int]
required
1 = foreground, 0 = background, one per prompt point.
​
multimask_output
bool
If True, returns multiple candidate masks.
​
mode
str
Endpoint mode; only "image" currently supported.
​
timeout
float | None
Optional HTTP timeout.

​
Returns

np.ndarray — Binary segmentation mask of shape (H, W) with dtype uint8. Foreground pixels are 255, background is 0.

​
Example Output

SAM2 point-prompted segmentation output

​
Example

from grid_cortex_client import CortexClient
import numpy as np
from PIL import Image

client = CortexClient()
img = Image.open("scene.jpg")  # 640x480 RGB
mask = client.run(
    model_id="sam2",
    image_input=img,
    prompts=[[320, 350]],
    labels=[1],  # 1 = foreground
)

print(mask.shape, mask.dtype)
# (480, 640) uint8

print(np.unique(mask))
# [0, 255]

foreground = np.count_nonzero(mask)
print(f"foreground pixels: {foreground} ({foreground / mask.size * 100:.1f}%)")
# foreground pixels: 138532 (45.1%)