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.

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

Matte

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

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
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:

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.

{
  "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.

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.

Complete flow in 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

• birefnet: how the model works, its limits and measured latency.
• Billing: birefnet bills one image per call.
• Images: image limits, storage and coordinates.