Remove Background

The core endpoint for background removal. Send an image, get back a processed image with the background removed.

Request

file

required

The image file to process. Supports JPEG, PNG, and WebP formats. Maximum size: 20MB.

string

default:"png"

Output image format.

png — Lossless with transparency support
jpg — Smaller file size, no transparency
webp — Best compression with transparency

string

default:"rgba"

Output color channels.

rgba — Include alpha channel (transparency)
rgb — Opaque output, uses bg_color for background (white by default)
alpha — Grayscale alpha mask only: white foreground, black background

string

Background color when channels is rgb or rgba. Accepts:

Hex: #ffffff, #fff
RGB: rgb(255, 255, 255)
Named: white, black, red

string

default:"full"

Output image size preset.

full — Original resolution
preview — up to 0.25 megapixels
medium — up to 1.5 megapixels
hd — up to 4 megapixels

boolean | string

default:"false"

Crop the output to the subject bounds, removing empty space around the subject. Pass true/false, or an aspect ratio like 1:1, 4:3, 16:9 to crop to that ratio around the subject.

string

Padding around the subject when crop is enabled, as a fraction (0.1) or percentage (10%).

Response

The API returns the processed image directly in the response body. Check the response headers for metadata:

Header	Description
`Content-Type`	MIME type of the image (`image/png`, `image/jpeg`, `image/webp`)
`X-Request-ID`	Unique request ID for support inquiries
`X-Processing-Time-Ms`	Processing time in milliseconds
`X-Image-Width`	Output image width in pixels
`X-Image-Height`	Output image height in pixels
`X-Matte-Confidence`	Confidence in the alpha matte, `0`–`1`. `1` means a fully decisive mask; lower values mean the model hedged. Heuristic, not a calibrated probability
`X-Matte-Ambiguous-Ratio`	Fraction of pixels with alpha between 0.1 and 0.9, `0`–`1`. High values indicate large uncertain regions — useful for flagging results for manual review

Examples

Basic Usage

Remove background and save as PNG with transparency:

curl -X POST https://api.poof.bg/v1/remove \
  -H "x-api-key: YOUR_API_KEY" \
  -F "image_file=@photo.jpg" \
  -o result.png

from poofbg import Poof

client = Poof(api_key="YOUR_API_KEY")
result = client.remove("photo.jpg")
result.save("result.png")

import { Poof } from '@poof-bg/js';
import fs from 'fs/promises';

const poof = new Poof({ apiKey: 'YOUR_API_KEY' });
const image = await fs.readFile('photo.jpg');
const result = await poof.remove(image);
await fs.writeFile('result.png', result);

White Background

Get a JPEG with a white background (great for e-commerce):

curl -X POST https://api.poof.bg/v1/remove \
  -H "x-api-key: YOUR_API_KEY" \
  -F "image_file=@product.jpg" \
  -F "format=jpg" \
  -F "channels=rgb" \
  -F "bg_color=#ffffff" \
  -o product-white-bg.jpg

result = client.remove(
    "product.jpg",
    format="jpg",
    channels="rgb",
    bg_color="#ffffff"
)
result.save("product-white-bg.jpg")

const result = await poof.remove(image, {
  format: 'jpg',
  channels: 'rgb',
  bgColor: '#ffffff'
});

Alpha Mask Only

Get just the grayscale alpha mask (white = foreground, black = background) — useful for custom compositing pipelines:

curl -X POST https://api.poof.bg/v1/remove \
  -H "x-api-key: YOUR_API_KEY" \
  -F "image_file=@photo.jpg" \
  -F "channels=alpha" \
  -o mask.png

result = client.remove("photo.jpg", channels="alpha")
result.save("mask.png")

const result = await poof.remove(image, { channels: 'alpha' });
await fs.writeFile('mask.png', result);

Cropped Thumbnail

Get a small, cropped preview:

curl -X POST https://api.poof.bg/v1/remove \
  -H "x-api-key: YOUR_API_KEY" \
  -F "image_file=@photo.jpg" \
  -F "size=preview" \
  -F "crop=true" \
  -o thumbnail.png

result = client.remove(
    "photo.jpg",
    size="preview",
    crop=True
)
result.save("thumbnail.png")

const result = await poof.remove(image, {
  size: 'preview',
  crop: true
});

WebP for Web

Optimal format for web delivery:

curl -X POST https://api.poof.bg/v1/remove \
  -H "x-api-key: YOUR_API_KEY" \
  -F "image_file=@photo.jpg" \
  -F "format=webp" \
  -o result.webp

result = client.remove("photo.jpg", format="webp")
result.save("result.webp")

const result = await poof.remove(image, { format: 'webp' });

Error Responses

Status	Code	Description
400	`validation_error`	Invalid parameter value
400	`missing_image`	No image file provided
400	`image_too_large`	Image exceeds 20MB limit
401	`authentication_error`	Invalid or missing API key
402	`payment_required`	Insufficient credits
429	`rate_limit_exceeded`	Too many requests
500	`internal_server_error`	Server error, retry later

See Error Handling for detailed troubleshooting.

curl -X POST https://api.poof.bg/v1/remove \
  -H "x-api-key: YOUR_API_KEY" \
  -F "image_file=@photo.jpg" \
  -F "format=png" \
  -F "size=full" \
  -o result.png

​Request

​Response

​Examples

​Basic Usage

​White Background

​Alpha Mask Only

​Cropped Thumbnail

​WebP for Web

​Error Responses

Request

Response

Examples

Basic Usage

White Background

Alpha Mask Only

Cropped Thumbnail

WebP for Web

Error Responses