Home Documentation API ReferenceImage Segmentation

Image Segmentation

Segment objects in images using AI (SAM 2). Returns a grayscale mask PNG of the selected region.

POST/v1/services/image-segmentation

Overview

Segment objects in an image using point or bounding box prompts powered by SAM 2 (Segment Anything Model 2). Upload an image and provide prompts via query parameters — the API returns a grayscale mask PNG where white pixels indicate the selected region.

<2s

Typical processing

SAM 2

AI segmentation model

Max batch size

Authentication

Include your API key in the Authorization header.

Header

Authorization: Bearer sk-live-your-api-key

Create API keys in your account settings .

Request

Body

Send as multipart/form-data.

Field	Type	Required	Description
`file`	binary	Required	Image file to segment (JPEG, PNG, WebP)

Query Parameters

At least one of points or box is required.

Parameter	Type	Required	Description
`points`	string	Conditional	JSON array of [x,y] point prompts. E.g. `[[100,200],[300,400]]`
`labels`	string	Optional	JSON array of point labels (1=foreground, 0=background). E.g. `[1,0]`
`box`	string	Conditional	Bounding box as JSON [x1,y1,x2,y2]. E.g. `[10,20,300,400]`

About prompts

You must provide at least one of points or box. You can combine both for more precise segmentation. Point labels default to 1 (foreground) when not specified. The output is a grayscale mask PNG where white (#FFFFFF) represents the selected region.

Examples

With point prompts

curl -X POST "https://api.maskr.io/v1/services/image-segmentation?points=[[100,200],[300,400]]&labels=[1,1]" \
  -H "Authorization: Bearer sk-live-your-api-key" \
  -F "[email protected]"

With bounding box

curl -X POST "https://api.maskr.io/v1/services/image-segmentation?box=[10,20,300,400]" \
  -H "Authorization: Bearer sk-live-your-api-key" \
  -F "[email protected]"

Response

200 OK

{
  "job_id": "abc123-def456",
  "status": "completed",
  "result": {
    "job_id": "abc123-def456",
    "status": "completed",
    "input_filename": "photo.jpg",
    "output_url": "https://api.maskr.io/v1/files/abc123-def456?expires=...&sig=...",
    "processing_time_ms": 850.2,
    "error": null,
    "original_width": 1920,
    "original_height": 1080,
    "output_width": 1920,
    "output_height": 1080,
    "credits_used": 1
  },
  "error": null
}

Response Fields

Field	Type	Description
`job_id`	string	Unique job identifier
`status`	string	`pending`, `processing`, `completed`, or `failed`
`result.output_url`	string \| null	Signed URL to download the segmentation mask (grayscale PNG, white = selected)
`result.processing_time_ms`	number \| null	Processing time in milliseconds
`result.credits_used`	integer \| null	Number of credits consumed
`error`	string \| null	Error message if processing failed

Batch Processing

POST/v1/services/image-segmentation/batch

Segment up to 50 images in a single request. Upload multiple files using the files field. The same points, labels, and box parameters are applied to all images.

cURL

curl -X POST "https://api.maskr.io/v1/services/image-segmentation/batch?points=[[100,200]]&labels=[1]" \
  -H "Authorization: Bearer sk-live-your-api-key" \
  -F "[email protected]" \
  -F "[email protected]"

Batch Response

{
  "batch_id": "batch-789",
  "status": "completed",
  "total_files": 2,
  "completed": 2,
  "failed": 0,
  "results": [
    { "job_id": "job-1", "status": "completed", "output_url": "...", ... },
    { "job_id": "job-2", "status": "completed", "output_url": "...", ... }
  ],
  "total_processing_time_ms": 1620.4,
  "total_credits_used": 2,
  "error": null
}

Partial Failures

If you run out of credits mid-batch, the API processes as many images as possible and marks the rest as failed. Check the completed and failed counts, and inspect each result's status field.