HomeDocumentationAPI ReferenceBackground Removal

Background Removal

Remove backgrounds from images with AI precision. Returns a grayscale PNG mask at original resolution.

POST/v1/services/background-removal

Overview

Remove the background from a single image. Returns a grayscale PNG mask at original resolution. White pixels represent the foreground, black pixels represent the background.

<200ms
Typical processing
PNG
Grayscale mask
50
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 process (JPEG, PNG, WebP)

Examples

Basic request
curl -X POST https://api.maskr.io/v1/services/background-removal \
  -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": 187.5,
    "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 grayscale PNG mask
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
401Unauthorized
Missing or invalid API key. Check your Authorization header.
402Insufficient Credits
{"detail": "Insufficient credits"}
Not enough credits to process this image. Top up your balance .
413File Too Large
Image exceeds the maximum file size limit (25 MB).
422Validation Error
{
  "detail": [
    {
      "loc": ["body", "file"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Batch Processing

POST/v1/services/background-removal/batch

Process up to 50 images in a single request. Send multiple files using the files field. Each image returns a grayscale PNG mask at its original resolution.

cURL
curl -X POST https://api.maskr.io/v1/services/background-removal/batch \
  -H "Authorization: Bearer sk-live-your-api-key" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "[email protected]"
Batch Response
{
  "batch_id": "batch-789",
  "status": "completed",
  "total_files": 3,
  "completed": 3,
  "failed": 0,
  "results": [
    { "job_id": "job-1", "status": "completed", "output_url": "...", ... },
    { "job_id": "job-2", "status": "completed", "output_url": "...", ... },
    { "job_id": "job-3", "status": "completed", "output_url": "...", ... }
  ],
  "total_processing_time_ms": 523.8,
  "total_credits_used": 9,
  "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.

Partial Failure Response
{
  "batch_id": "batch-790",
  "status": "completed",
  "total_files": 5,
  "completed": 2,
  "failed": 3,
  "results": [
    { "job_id": "job-1", "status": "completed", "output_url": "...", "credits_used": 1, ... },
    { "job_id": "job-2", "status": "completed", "output_url": "...", "credits_used": 1, ... },
    { "job_id": "batch-790_2", "status": "failed", "output_url": null, "error": "Insufficient credits", ... },
    { "job_id": "batch-790_3", "status": "failed", "output_url": null, "error": "Insufficient credits", ... },
    { "job_id": "batch-790_4", "status": "failed", "output_url": null, "error": "Insufficient credits", ... }
  ],
  "total_processing_time_ms": 290.3,
  "total_credits_used": 2,
  "error": null
}