# Background removal

Background removal separates the foreground subject from the background with hair-level detail. The result is either an RGBA cutout of the subject, or the 8-bit grayscale alpha matte on its own. Typical uses are product photos, portraits, compositing, and pipelines that apply the alpha themselves.

## Cutout or matte

`options.output` selects what is returned.

- `cutout` (default): an RGBA image of the subject with a transparent background. It is ready to place on a new background and needs no further work.
- `matte`: an 8-bit grayscale alpha matte, white for the subject and black for the background, with intermediate grays where the edge is partly transparent (hair, fur). It suits pipelines that apply the alpha themselves, for example masking in an editor, compositing against a different crop of the original, or feeding the matte to another step.

Both outputs are billed per `image` at the same unit price.

## Cutout

The cutout keeps the subject's colours and drops the background, with soft alpha along strands of hair.

![A Yorkshire terrier on asphalt on the left, and the same dog on a checkerboard transparency pattern on the right, with the background removed.](../../../../assets/docs/birefnet-cutout.webp)

*Recorded Playground result for `output: "cutout"`. The checkerboard marks transparent pixels.*

## Matte

The matte carries the alpha channel alone, as a grayscale image.

![The same photo of a Yorkshire terrier on the left, and its alpha matte on the right: a white silhouette of the dog on a black background.](../../../../assets/docs/birefnet-matte.webp)

*Recorded Playground result for `output: "matte"`: white is the subject, black is the background.*

## Output formats

`options.format` selects the encoding of the returned image.

- `png` (default): lossless PNG.
- `webp`, for `cutout`: lossy RGB at quality 90 with a lossless alpha channel, so the matte is exact. A WebP cutout is typically about 10 times smaller than the PNG, for example about 200 kB instead of 2 MB at 1791 by 1008 px, with no visible difference. Responses arrive faster.
- `webp`, for `matte`: lossless WebP of the gray matte. It is stored as gray RGB, so every decoder shows it as gray, and the red channel is the matte.

## Supported models

`birefnet` is the default and only model of `POST /v1/remove-background`.

| | [`birefnet`](https://stack.foldbun.com/docs/models/birefnet/#background-removal) |
|---|---|
| Model | BiRefNet, general model |
| Accepts | One image |
| Returns | An RGBA cutout or an 8-bit grayscale matte, as PNG or WebP |
| List price (credits) | 1 per image |
| Pool | Paid: billed from the balance |
| Recorded processing time | 882 ms (one recorded call) |

## Example call

The dog photo of the figures, cut out and returned as WebP:

```bash
curl https://api.stack.foldbun.com/v1/remove-background \
  -H "Authorization: Bearer $FOLDBUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "birefnet",
    "image": { "id": "img_3343c2ff2ab3bf8b5a45e85a184f65e819d577d6de2ac81cc32eb0bb88fb9e4d" },
    "options": { "output": "cutout", "format": "webp" }
  }'
```

The response is abridged: the `data` string is shortened.

```json
{
  "id": "call_01a1913f-3d29-73dc-ab68-81ad46905b04",
  "model": "birefnet",
  "image": {
    "id": "img_3343c2ff2ab3bf8b5a45e85a184f65e819d577d6de2ac81cc32eb0bb88fb9e4d",
    "width": 1091,
    "height": 1008,
    "bytes": 204026,
    "contentType": "image/jpeg"
  },
  "format": "webp",
  "width": 1091,
  "height": 1008,
  "data": "UklGRtYGAABXRUJQVlA4...",
  "cost": 1,
  "balance": 995,
  "timing": { "queueMs": 0, "processingMs": 882 },
  "billing": {
    "lines": [
      { "unit": "image", "quantity": 1, "unitPrice": 1, "amount": 1, "waived": false }
    ],
    "total": 1,
    "charged": true,
    "pool": null
  }
}
```

### Reading the response

- `format` is `webp`, as requested with `options.format`.
- `width` and `height` are the size of the returned image. Here it is 1091 × 1008, the same as the input (`image.width`, `image.height`), because the long side is below the default `options.size` of 2048. A larger image is scaled down on its long side to `options.size`.
- `data` is the image inline as a base64 string; there is no download URL.
- `billing.charged` is `true` and `pool` is `null`: the call was debited from the balance, so `cost` is 1.

All fields: [API reference](https://stack.foldbun.com/docs/api/operations/removebackground/).

**Cost of this call.** 1 (`image`) credit, as charged in this response; a matte costs the same, and there is no cache discount. Unit prices: [Billing](https://stack.foldbun.com/docs/billing/#price-list).

### Complete flow in Python

```python
import base64
import os

import requests

response = requests.post(
    "https://api.stack.foldbun.com/v1/remove-background",
    headers={"Authorization": f"Bearer {os.environ['FOLDBUN_API_KEY']}"},
    json={
        "image": {"id": "img_3343c2ff2ab3bf8b5a45e85a184f65e819d577d6de2ac81cc32eb0bb88fb9e4d"},
        "options": {"output": "cutout", "format": "webp"},
    },
    timeout=120,
)
response.raise_for_status()
result = response.json()

with open(f"cutout.{result['format']}", "wb") as f:
    f.write(base64.b64decode(result["data"]))
```

## Endpoints and reference

| Endpoint | In this use case | Reference |
|---|---|---|
| `POST /v1/remove-background` | One image to a cutout (RGBA) or an alpha matte (8-bit gray), as PNG or WebP | [API reference](https://stack.foldbun.com/docs/api/operations/removebackground/) |

- [`birefnet`](https://stack.foldbun.com/docs/models/birefnet/): how the model works, its limits and measured latency.
- [Billing](https://stack.foldbun.com/docs/billing/#price-list): `birefnet` bills one `image` per call.
- [Images](https://stack.foldbun.com/docs/images/): image limits, storage and coordinates.