Skip to main content
ModelRunner
meta avatar

Segment Anything 2 (Auto-Segment) API

meta/sam2/auto-segment

Automatically segment a photo into a combined object/region mask — no prompts, points, or clicks needed.

segmentationmask
0.01
OpenAPI

Model Input

Input

URL of the image to be automatically segmented.

Format of the returned mask image.

Number of points sampled along each side of the image grid. Higher values produce more, finer masks but run slower.

Predicted IoU quality threshold; masks below this confidence are discarded. Raise for fewer, cleaner masks.

Stability score threshold for filtering masks. Raise for fewer, more stable masks.

Minimum mask region area in pixels; smaller disconnected regions are removed.

You need to be logged in to run this model and view results.
Log in

Model Output

Output

Loading
Generated in 149.215 seconds
Logs (1 lines)

Model Example Requests

Examples

Example output 1Example output 2Example output 3

Segment Anything 2 (Auto-Segment) API

Segment Anything 2 (Auto-Segment) is a image-to-image AI model by meta. On ModelRunner it runs through a REST API or via MCP from any AI assistant, at $0.01 per image.

POST https://queue.modelrunner.run/meta/sam2/auto-segment

cURL

# Submit a request to the queue. Input fields go at the top level of the
# body. The optional reserved "metadata" object holds your own flat string
# tags — stored on the request, never sent to the model; filter later with
# GET https://queue.modelrunner.run/requests?metadata=<url-encoded JSON>.
curl -X POST https://queue.modelrunner.run/meta/sam2/auto-segment \
  -H "Authorization: Key $MRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://media.modelrunner.ai/Y7AkNTD51Far8RIR-fruit-on-table.png",
    "output_format": "png",
    "points_per_side": 32,
    "pred_iou_thresh": 0.88,
    "min_mask_region_area": 100,
    "stability_score_thresh": 0.95,
    "metadata": {
      "project": "my-project"
    }
  }'
# → { "request_id": "...", "status_url": "...", "response_url": "..." }

# Poll status_url until "COMPLETED", then fetch the result
curl "https://queue.modelrunner.run/meta/sam2/auto-segment/requests/$REQUEST_ID/status" \
  -H "Authorization: Key $MRUN_API_KEY"
curl "https://queue.modelrunner.run/meta/sam2/auto-segment/requests/$REQUEST_ID" \
  -H "Authorization: Key $MRUN_API_KEY"

JavaScript

import { modelrunner } from "@modelrunner/client";

const result = await modelrunner.subscribe("meta/sam2/auto-segment", {
  input: {
    "image_url": "https://media.modelrunner.ai/Y7AkNTD51Far8RIR-fruit-on-table.png",
    "output_format": "png",
    "points_per_side": 32,
    "pred_iou_thresh": 0.88,
    "min_mask_region_area": 100,
    "stability_score_thresh": 0.95
  },
});
console.log(result);

Python

import os
import requests

headers = {"Authorization": f"Key {os.environ['MRUN_API_KEY']}"}

submitted = requests.post(
    "https://queue.modelrunner.run/meta/sam2/auto-segment",
    headers=headers,
    json={
      "image_url": "https://media.modelrunner.ai/Y7AkNTD51Far8RIR-fruit-on-table.png",
      "output_format": "png",
      "points_per_side": 32,
      "pred_iou_thresh": 0.88,
      "min_mask_region_area": 100,
      "stability_score_thresh": 0.95
    },
).json()

# Poll submitted["status_url"] until "COMPLETED", then:
result = requests.get(submitted["response_url"], headers=headers).json()

Input parameters

NameTypeRequiredDescription
image_urlstring (uri)yesURL of the image to be automatically segmented.
output_formatenumnoFormat of the returned mask image. Default: "png".
points_per_sideintegernoNumber of points sampled along each side of the image grid. Higher values produce more, finer masks but run slower. Default: 32.
pred_iou_threshnumbernoPredicted IoU quality threshold; masks below this confidence are discarded. Raise for fewer, cleaner masks. Default: 0.88.
stability_score_threshnumbernoStability score threshold for filtering masks. Raise for fewer, more stable masks. Default: 0.95.
min_mask_region_areaintegernoMinimum mask region area in pixels; smaller disconnected regions are removed. Default: 100.

Machine-readable: OpenAPI schema · llms.txt

Use Segment Anything 2 (Auto-Segment) from Claude & Cursor (MCP)

Point Claude Code, Claude Desktop, Cursor, or any MCP client at the ModelRunner MCP server and Segment Anything 2 (Auto-Segment) becomes a tool your assistant can call directly — it authorizes via OAuth (no API key in config) and runs this model with the run_model tool using the endpoint meta/sam2/auto-segment.

MCP client config (Claude Desktop, Cursor)

{
  "mcpServers": {
    "modelrunner": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.modelrunner.run/mcp"]
    }
  }
}

Claude Code

claude mcp add --transport http modelrunner https://mcp.modelrunner.run/mcp

Then ask your assistant, for example: “Run meta/sam2/auto-segment on ModelRunner to generate image”. MCP setup guide.

Model Details

Model Details

Segment Anything 2 (Auto-Segment) automatically partitions an image into masks: give it one photo and it returns a single combined segmentation mask covering every object, region, and surface it finds — no prompt, no clicks, and no point or box inputs required. It runs the model in fully automatic mode, sampling a grid of points across the image and merging the results into one mask image at the input's dimensions. The output is a standard image you can drop straight into a compositing, matting, or labeling pipeline.

## Best for - Producing a one-shot combined mask of everything in a photo for compositing or background work - Generating segmentation masks to bootstrap labeling and annotation datasets - Pre-processing images into region maps for downstream editing, matting, or analysis - Batch mask generation across many stills where no per-image prompting is practical

## Choose another model when - You want to mask one specific object by clicking a point or drawing a box rather than segmenting everything automatically — use a prompt-driven / interactive segmentation model - You want a clean cut-out of the single main subject with the background removed — use a background-removal model - You want to edit or regenerate the photo itself rather than produce a mask — use an image-editing or text-to-image model - You need to segment a video over time rather than a single frame — use a video segmentation model

## Tips - Automatic mode is aggressive: it segments sub-regions, shadows, and surface patches, so the mask count can far exceed the number of obvious objects in the scene. Expect fine-grained partitioning rather than a few large regions. - Feed the highest-resolution source you have; the mask is returned at the input's dimensions. - `points_per_side` controls grid density (higher = more, finer masks but slower); `pred_iou_thresh` and `stability_score_thresh` filter low-quality masks (raise them for cleaner, fewer masks); `min_mask_region_area` drops tiny fragments below the given pixel area. These are advanced controls — the defaults work for most images.

## Limitations - Returns a single combined mask image, not per-object layers, so overlapping or adjacent regions are merged in the output. - Thin structures, reflective and transparent surfaces, and low-contrast boundaries can be segmented imperfectly.

To run via the ModelRunner JavaScript client: ```js import { modelrunner } from "@modelrunner/client";

const result = await modelrunner.subscribe("meta/sam2/auto-segment", { input: { image_url: "https://media.modelrunner.ai/example-scene.png", output_format: "png", }, }); ```