> ## Documentation Index
> Fetch the complete documentation index at: https://docs.generalrobotics.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# sam3-1

> Segment an image with SAM-3.1 using exactly one prompt type

Segment an image with SAM-3.1 using exactly one prompt type.

<Note>
  Input images up to **1280 x 720** (width x height). Larger images are rejected with HTTP 413, not downscaled — resize first.
</Note>

## Parameters

<ParamField body="image_input" type="ImageInput" required>
  RGB image as file path, URL, PIL Image, or numpy array.
</ParamField>

<ParamField body="text" type="Optional[str]">
  Text prompt describing objects to segment (exclusive with points/boxes).
</ParamField>

<ParamField body="points" type="Optional[Iterable[Iterable[float]]]">
  List of \[x, y] point coordinates (exclusive with text/boxes).
</ParamField>

<ParamField body="boxes" type="Optional[Iterable[Iterable[float]]]">
  List of \[x0, y0, x1, y1] box coordinates (exclusive with text/points).
</ParamField>

<ParamField body="labels" type="Optional[Iterable[int]]">
  Required for points/boxes. 1=foreground, 0=background.
</ParamField>

<ParamField body="timeout" type="Optional[float]">
  Optional HTTP timeout in seconds.
</ParamField>

## Returns

np.ndarray: Binary segmentation mask as numpy array (H, W) with dtype uint8.
Foreground pixels are 255, background pixels are 0.

## Example

```python theme={null}
from grid_cortex_client import CortexClient, ModelType
import numpy as np
from PIL import Image
client = CortexClient()
image = np.array(Image.open("cat.jpg"))
# Text prompt
mask = client.run(ModelType.SAM3_1, image_input=image, text="cat")
# Point prompts
mask = client.run(
    ModelType.SAM3_1, image_input=image,
    points=[[320, 240]], labels=[1]
)
# Box prompts
mask = client.run(
    ModelType.SAM3_1, image_input=image,
    boxes=[[100, 120, 520, 480]], labels=[1]
)
```


## Related topics

- [sam3](/models/cortex/sam3.md)
- [CortexClient](/python-api/grid-cortex-client/cortexclient.md)