Home Documentation API ReferenceObject Removal

Object Removal

Remove unwanted objects from images using AI inpainting. Upload an image and a mask to seamlessly erase and fill selected areas.

POST/v1/services/object-removal

Overview

Remove objects from a single image using AI-powered inpainting (LaMa). Upload the original image and a mask PNG where white pixels indicate areas to remove and black pixels indicate areas to keep. The AI fills in the removed areas to match the surrounding scene.

<3s

Typical processing

Image + Mask

Two-file input

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 = remove, black = keep). Optional if points/box provided.

Query Parameters

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

Mask vs. prompt-based removal

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 removal, 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 areas to remove and black (#000000) marks the areas to keep. Gray values are thresholded at 128.

Examples

With mask file

curl -X POST https://api.maskr.io/v1/services/object-removal \
  -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-removal?points=[[100,200],[300,400]]&labels=[1,1]" \
  -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": 2150.3,
    "error": null,
    "original_width": 1920,
    "original_height": 1080,
    "output_width": 1920,
    "output_height": 1080,
    "credits_used": 3
  },
  "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 inpainted image
`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-removal/batch

Process up to 50 image-mask pairs in a single request. Upload matching pairs using the images and masks fields. The number of images must match the number of masks.

cURL

curl -X POST https://api.maskr.io/v1/services/object-removal/batch \
  -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-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": 4280.6,
  "total_credits_used": 6,
  "error": null
}

Partial Failures

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