Skip to main content
POST
/
remove
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
The core endpoint for background removal. Send an image, get back a processed image with the background removed.

​
Request

​
image_file
file
required
The image file to process. Supports JPEG, PNG, and WebP formats. Maximum size: 20MB.
​
format
string
default:"png"
Output image format.
  • png — Lossless with transparency support
  • jpg — Smaller file size, no transparency
  • webp — Best compression with transparency
​
channels
string
default:"rgba"
Output color channels.
  • rgba — Include alpha channel (transparency)
  • rgb — Opaque output, uses bg_color for background
​
bg_color
string
Background color when channels is rgb. Accepts:
  • Hex: #ffffff, #fff
  • RGB: rgb(255, 255, 255)
  • Named: white, black, red
​
size
string
default:"full"
Output image size preset.
  • full — Original resolution
  • preview — 256px max dimension
  • small — 512px max dimension
  • medium — 1024px max dimension
  • large — 2048px max dimension
​
crop
boolean
default:"false"
Crop the output to the subject bounds, removing empty space around the subject.

​
Response

The API returns the processed image directly in the response body. Check the response headers for metadata:
HeaderDescription
Content-TypeMIME type of the image (image/png, image/jpeg, image/webp)
X-Request-IDUnique request ID for support inquiries
X-Processing-Time-MsProcessing time in milliseconds
X-Image-WidthOutput image width in pixels
X-Image-HeightOutput image height in pixels

​
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

​
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

​
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=small" \
  -F "crop=true" \
  -o thumbnail.png

​
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

​
Error Responses

StatusCodeDescription
400validation_errorInvalid parameter value
400missing_imageNo image file provided
400image_too_largeImage exceeds 20MB limit
401authentication_errorInvalid or missing API key
402payment_requiredInsufficient credits
429rate_limit_exceededToo many requests
500internal_server_errorServer 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