AI Background Removal API

Remove Background is a professional-mode plugin for teams that need to remove backgrounds from images automatically. The model performs foreground extraction across a broad range of subjects and objects rather than being tied to a single object category. The API can return a production-ready transparent PNG, a direct single-channel grayscale mask with no RGB data, or a layered ZIP archive containing the foreground mask.

Important: Remove Background must be the only plugin in the tasks array. Do not combine it with Heal, Crop, Color Correction, Clean Backdrop, or any other plugin in the same job. If you need additional processing, run background removal as a separate API request.

Background Removal Jobs This API Solves

How To Remove An Image Background By API

1. Upload one source image Send the JPG or PNG as multipart form data to /retoucher/start together with your token and JSON payload.
2. Choose the required output Request Layer: 0 for a ready transparent PNG, add MaskOnly: 1 for a direct one-channel mask PNG, or use Layer: 1 for a ZIP containing the foreground mask.
3. Poll and download Check /retoucher/status/{id} until the job completes, then download the result from /retoucher/getFile/{id}.

For bulk background removal, submit one job per image and manage the returned job IDs in your own queue. This pattern works for SKU imports, marketplace feeds, DAM/PIM synchronization, and other high-volume image-processing workflows.

Choose Transparent PNG, Alpha-only PNG, Or Layered Mask

Example Output

The first example shows a clean product-style batch: multiple strawberries are preserved as a single foreground group. The API can return the ready transparent cutout, the soft alpha-only mask shown here, or the foreground mask in a layered ZIP archive.

Second Example: Object Cutout From A Complex Scene

This example demonstrates a harder real-world scene with overlapping furniture, shadows, fine edges, and a blurred outdoor background. The photographed object happens to be a potted succulent, but the workflow is category-independent: the same API request is used for other foreground objects.

Ready Transparent PNG

Use flat output when your application needs the final image immediately. Set outputFormat to png and keep Layer at 0. The downloaded file is an RGBA PNG with transparency.

{
  "mode": "professional",
  "outputFormat": "png",
  "tasks": [
    {
      "Plugin": "Remove Background",
      "version": 1,
      "Layer": 0
    }
  ]
}

cURL Request

curl --location 'https://retoucher.hz.labs.retouch4.me/api/v1/retoucher/start' \
  --form 'file=@Remove_Background_Strawberries_Source.png' \
  --form 'token=YOUR_RETOUCH_TOKEN' \
  --form-string 'payload={"mode":"professional","outputFormat":"png","tasks":[{"Plugin":"Remove Background","version":1,"Layer":0}]}'

Poll /retoucher/status/{id} until state becomes completed, then download the transparent PNG:

curl --location 'https://retoucher.hz.labs.retouch4.me/api/v1/retoucher/getFile/remove-background-job-id' \
  --output remove-background-result.png

Alpha-only Mask PNG Without RGB

Use MaskOnly: 1 when your application needs the segmentation matte itself, without the source image's RGB channels and without extracting a ZIP archive. Keep Layer: 0 and set outputFormat to png.

The downloaded file is an 8-bit, single-channel grayscale PNG (PNG color type 0). It contains no RGB channels: pixel value 0 is background, 255 is foreground, and intermediate values represent partial foreground coverage. In imaging code, use this grayscale channel as alpha.

Choose edge behavior: set BinaryMask: 0 for a soft matte with intermediate values around hair and anti-aliased edges. Use BinaryMask: 1, or omit it, for a hard mask thresholded to black and white at 0.5.

{
  "mode": "professional",
  "outputFormat": "png",
  "tasks": [
    {
      "Plugin": "Remove Background",
      "version": 1,
      "Layer": 0,
      "MaskOnly": 1,
      "BinaryMask": 0
    }
  ]
}

cURL Request

curl --location 'https://retoucher.hz.labs.retouch4.me/api/v1/retoucher/start' \
  --form 'file=@Remove_Background_Strawberries_Source.png' \
  --form 'token=YOUR_RETOUCH_TOKEN' \
  --form-string 'payload={"mode":"professional","outputFormat":"png","tasks":[{"Plugin":"Remove Background","version":1,"Layer":0,"MaskOnly":1,"BinaryMask":0}]}'

The live example above was produced directly by this request. Download the alpha-only soft mask PNG.

Layered ZIP With Foreground Mask

Use layered output when your editor, DAM, or backend pipeline needs the foreground mask together with layer identity and archive metadata. Set outputFormat to zip and Layer to 1. The ZIP contains a mask PNG named with type=mask and id=foreground. If you only need mask pixels and no archive, use MaskOnly: 1 instead.

{
  "mode": "professional",
  "outputFormat": "zip",
  "tasks": [
    {
      "Plugin": "Remove Background",
      "version": 1,
      "Layer": 1
    }
  ]
}

Layered ZIP Contents

The example archive contains this file:

index=0&blendmode=normal&name=Remove Background&type=mask&id=foreground.png

Download the example layered ZIP archive.

Parameters

Field	Type	Required	Description
Plugin	string	yes	Must be Remove Background.
version	integer	recommended	Use 1 for the current Remove Background model.
Layer	integer or boolean	no	0 returns a flat PNG: RGBA by default, or one-channel grayscale when MaskOnly is enabled. 1 returns a ZIP archive with the foreground mask.
MaskOnly	boolean or 0/1	no	With Layer: 0, 1 returns only the matte as an 8-bit, single-channel grayscale PNG. The file has no RGB channels. Default: 0.
BinaryMask	boolean or 0/1	no	1 returns hard black/white coverage at a 0.5 threshold and is the default. 0 preserves soft intermediate coverage for hair and anti-aliased edges.
outputFormat	string	yes	Use png for a ready transparent PNG or direct alpha-only mask, or zip for the layered mask archive.

Integration Notes

• Remove Background cannot be combined with other plugins in one job.
• For final cutouts, use outputFormat: "png"; JPEG cannot store transparency.
• For a direct mask file without RGB channels, use outputFormat: "png", Layer: 0, and MaskOnly: 1.
• Use BinaryMask: 0 for soft alpha coverage or BinaryMask: 1 for a hard black-and-white mask.
• For manual compositing or quality control, use the ZIP workflow and read the foreground mask layer.
• To create a white-background product image, first download the transparent PNG or mask, then composite the foreground over white in your application.
• The normal Cloud API flow still applies: submit with /retoucher/start, poll /retoucher/status/{id}, and download with /retoucher/getFile/{id}.

Background Removal API FAQ