Home Documentation API ReferenceObject Extraction

Object Extraction

Extract objects from images using a mask. Returns the isolated object with transparent background.

POST/v1/services/object-extraction

Overview

Extract objects from an image using a mask. Upload the original image and a mask PNG where white pixels indicate the object to keep and black pixels indicate the background to remove. Returns the extracted object with a transparent background, optionally with feathered edges.

<1s

Typical processing

Transparent

PNG/WebP output

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
`image`	binary	Required	Original image file (JPEG, PNG, WebP)
`mask`	binary	Optional	Mask PNG (white = keep/extract, black = remove). Optional if points/box provided.

Query Parameters

Parameter	Type	Default	Description
`points`	string	`—`	JSON array of [x,y] point prompts, alternative to mask. E.g. `[[100,200],[300,400]]`
`labels`	string	`—`	JSON array of point labels (1=foreground, 0=background). E.g. `[1,0]`
`box`	string	`—`	Bounding box as JSON [x1,y1,x2,y2]. E.g. `[10,20,300,400]`
`feather`	integer	`0`	Edge feathering in pixels (0–50). Softens edges for smoother blending.
`output_format`	string	`webp`	Output format: `webp` or `png`

Mask vs. prompt-based extraction

Provide either a mask file OR point/box prompts. When using prompts instead of a mask, the API runs AI segmentation internally to generate the mask — you're only charged for the extraction, not the segmentation.

About the mask

The mask should be the same dimensions as the original image. Use a grayscale or binary PNG where white (#FFFFFF) marks the object to keep and black (#000000) marks the background to remove. This is the inverse of the object removal mask convention.

Examples

With mask file

curl -X POST "https://api.maskr.io/v1/services/object-extraction?feather=5&output_format=png" \
  -H "Authorization: Bearer sk-live-your-api-key" \
  -F "[email protected]" \
  -F "[email protected]"

With point prompts (no mask)

curl -X POST "https://api.maskr.io/v1/services/object-extraction?points=[[100,200],[300,400]]&labels=[1,1]&output_format=png" \
  -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": 420.7,
    "error": null,
    "original_width": 1920,
    "original_height": 1080,
    "output_width": 1920,
    "output_height": 1080,
    "credits_used": 2
  },
  "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 extracted object (transparent PNG or WebP)
`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/object-extraction/batch

Extract objects from up to 50 image-mask pairs in a single request. The same feather and output_format parameters are applied to all images.

cURL

curl -X POST "https://api.maskr.io/v1/services/object-extraction/batch?output_format=png" \
  -H "Authorization: Bearer sk-live-your-api-key" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "[email protected]"

Batch Response

{
  "batch_id": "batch-456",
  "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": 810.2,
  "total_credits_used": 4,
  "error": null
}