---
title: Generate Image Foreground Mask API
slug: background-removal
url: https://apyhub.com/callable-labs/service/background-removal
provider: Callable Labs
categories: [Artificial Intelligence, Image Processing]
tags: [image-masking, subject-detection, image-segmentation, computer-vision]
auth: api_key
version: 0.1.0
service_type: sync
endpoints: 1
atoms: 600
mcp: true
---

# Generate Image Foreground Mask API

Detect the main subject in an image and return a PNG mask or JSON metadata. Useful for background removal, cropping, and image pipeline automation.

## Endpoints

| Method | URL | Description | Atoms |
| --- | --- | --- | --- |
| POST | `https://api.eu.apyhub.com/callable-labs/background-removal/v1/background/mask` | What it does Generates a subject mask for an input image. The request accepts an image source and o… | 600 |

## Endpoint reference

### Get the subject mask

`POST https://api.eu.apyhub.com/callable-labs/background-removal/v1/background/mask` · 600 atoms · accepts `application/json` · returns `application/json`

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `crop` | body | boolean | no | Crop the result to the subject's bounding box. Default: `false`. Default: `false`. |
| `image` | body | any | yes | Image source object. Provide exactly one of `url` or `base64`; see nested fields. |
| `format` | body | string | no | Output format. Allowed values: `json`, `png`. Default: `json`. `json` returns metadata plus a PNG data URI; `png` returns the 8-bit grayscale mask. One of: json, png. Default: `json`. |
| `padding` | body | integer | no | Pixels kept around the subject when `crop` is true. Default: `0`; minimum: `0`, maximum: `1000`. Default: `0`. |
| `quality` | body | string | no | Output quality. Allowed values: `best`, `fast`. Default: `best`. `best` prioritizes detail; `fast` is suitable for previews. One of: best, fast. Default: `best`. |
| `max_size` | body | any | no | Longest side of the output in pixels. Default: original size; minimum: `64`, maximum: `4096`. Default: `null`. |

#### Quickstart

Send a public image URL to remove its background and return mask metadata in JSON.

```bash
curl -X POST "https://api.eu.apyhub.com/callable-labs/background-removal/v1/background/mask" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "image": {
      "url": "https://assets.apyhub.com/samples/cat.jpg"
    }
  }'
```

#### What you'll get back

Returns a JSON object with these top-level fields: `format` and `media_type` are strings, `width` and `height` are output dimensions in pixels, `bytes` is the payload size, `data_uri` is a `data:<media_type>;base64,...` string, `bbox` is either an object with `x`, `y`, `width`, and `height` or `null`, `foreground_ratio` is a number between 0 and 1, and `quality` is `"best"` or `"fast"`.

```json
{
  "format": "json",
  "media_type": "image/png",
  "width": 800,
  "height": 600,
  "bytes": 124532,
  "data_uri": "data:image/png;base64,iVBORw0KGgoAAA...",
  "bbox": { "x": 120, "y": 45, "width": 540, "height": 510 },
  "foreground_ratio": 0.42,
  "quality": "best"
}
```

## About

## What it does
Generate Image Foreground Mask API lets you isolate a subject from an image and return either a mask or a background-removed image. Send a public image URL or base64-encoded image data, and choose whether you want JSON metadata or image bytes back.

Use the subject mask endpoint when you need a grayscale cutout for compositing, edge cleanup, or downstream image analysis. The response includes the output format, media type, width, height, byte size, data URI, subject bounding box, foreground ratio, and the quality setting used. If nothing is found, `bbox` is `null`.

Use the background-removal endpoint when you need a ready-to-use subject image. You can crop to the subject's bounding box, add padding, limit the output size, and pick `best` or `fast` quality. Output can be `json`, `png`, `webp`, or `jpeg`; JPEG requires an opaque background color in `#RRGGBB` form. This is a good fit for product photos, profile pictures, asset pipelines, and any workflow that needs transparent backgrounds or a consistent subject crop.

Both endpoints accept images up to 20 MB and return a data URI alongside the image metadata, so you can pass results straight into your storage, preview, or rendering pipeline.

## Usage

Base URL: `https://api.eu.apyhub.com` (default region — see
`GET https://apyhub.com/api/public/regions` for the rest).

Authenticate with an ApyHub API key in the `apy-token` header.
Full docs and a live playground: https://apyhub.com/callable-labs/service/background-removal