Image Segmentation — detect object masks from images

Image Segmentation API

What it does

Image Segmentation detects and separates objects in an image, then returns a mask for each detected region. Send a JPEG, PNG, or WebP file and you get object masks back in a structured response you can use for editing, analysis, or downstream computer vision workflows.

The request body accepts a binary file and an optional max_masks limit from 1 to 200, with a default of 50. That makes it easy to control how many segments you want from a single image without changing the source image itself.

The response includes mask_count, the original image_size (h and w), and a masks array. Each mask can include area, bbox as [x, y, w, h], mask_rle with run-length encoded data, plus predicted_iou and stability_score for quality assessment.

Use Image Segmentation when you need to isolate foreground objects, prepare regions for annotation, measure object coverage, or feed segmented regions into an image pipeline. It’s a practical fit for product photography, scene understanding, and automated image analysis.

What you'll get back

Returns a JSON object with masks, image_size, and mask_count fields.

masks is an array of mask objects. Each mask can include area (integer), bbox ([x, y, w, h] integer array), mask_rle (an object with size, order, and counts), predicted_iou (number), and stability_score (number).

image_size is an object with h and w integers, and mask_count is an integer.

{
  "masks": [],
  "image_size": {
    "h": 0,
    "w": 0
  },
  "mask_count": 0
}

About this endpoint

What it does

Uploads an image and automatically segments the objects it contains. The response returns the detected masks along with basic metadata about each mask and the source image size.

Request Body

Parameter	Type	Mandatory	Description
file	String	Yes	Image file (JPEG/PNG/WebP, max 20 MB).
max_masks	Integer	No	Maximum number of masks to return. Default: 50. Minimum: 1. Maximum: 200.

Response

Returns a JSON object with masks as an array of mask objects, image_size as an object with the image dimensions, and mask_count as an integer. Each mask object includes area, bounding box, RLE-encoded mask data, and scoring fields.

Parameter	Type	Mandatory	Description
masks	Object Array	No	Array of detected mask objects. Each item includes:<br>`area` (integer)<br>`bbox` (integer array, `[x, y, w, h]`)<br>`mask_rle` (object, run-length encoded boolean mask)<br>`predicted_iou` (number)<br>`stability_score` (number)
masks[].area	Integer	No	Mask area.
masks[].bbox	String Array	No	Bounding box as an integer array in the form `[x, y, w, h]`.
masks[].mask_rle	Object	No	Run-length encoded boolean mask. Includes nested fields `size`, `order`, and `counts`.
masks[].mask_rle.size	String Array	No	Mask size as an integer array in the form `[height, width]`.
masks[].mask_rle.order	ENUM	No	Mask run order. Allowed value: `F`.
masks[].mask_rle.counts	String Array	No	Run lengths in column-major order.
masks[].predicted_iou	Number	No	Predicted intersection-over-union score.
masks[].stability_score	Number	No	Stability score.
image_size	Object	No	Image dimensions. Includes `h` and `w`.
image_size.h	Integer	No	Image height.
image_size.w	Integer	No	Image width.
mask_count	Integer	No	Number of masks returned.

Body

Name

Type

Description

bodyREQUIRED

object

—

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

Image Segmentation API

What it does

Quickstart

What you'll get back

About this endpoint

What it does

Request Body

Response

Body

Errors any endpoint can return