API Documentation

Background removal API for production image workflows.

Use BackgroundErase to remove image backgrounds through a simple HTTPS API. Send an image, choose transparent or flattened output, and receive production-ready image bytes your application can store, transform, or publish.

Get an API key Start quickstart API status

Simple upload contract

Multipart form data is the recommended path. Existing upload workers can usually add one endpoint and one auth header.

Transparent by default

PNG RGBA output preserves transparency for design tools, storefronts, CMS pipelines, and downstream image processors.

Enterprise ready

Use retries, health checks, queue workers, status monitoring, and dedicated support paths when the API sits in a critical workflow.

Privacy-first defaults

User images are not used for model training by default. Training use requires explicit opt-in from the account page.

Documentation sections

Overview Quickstart API keys Endpoint Get account Inputs Options Responses Errors Operations Tutorials Compatibility Security Support

Quickstart

Make your first background removal request

The fastest production path is a multipart POST with an API key in the x-api-key header.

Create an API key

Open the API Access section in your account and generate a key for your backend service.

Go to API Access

Send multipart data

Attach the image as image_file. Add output options as regular form fields.

View input fields

Write the response

For image responses, stream or write the raw response body to your destination file.

View responses

cURL

curl -f "https://api.backgrounderase.com/v2" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "image_file=@/absolute/path/to/image.jpg" \
  -F "format=png" \
  -F "channels=rgba" \
  -F "size=full" \
  -o output.png

Node.js

import { readFile, writeFile } from "node:fs/promises";

const apiKey = process.env.BACKGROUND_ERASE_API_KEY;
const input = await readFile("./input.jpg");

const form = new FormData();
form.append("image_file", new Blob([input], { type: "image/jpeg" }), "input.jpg");
form.append("format", "png");
form.append("channels", "rgba");
form.append("size", "full");

const response = await fetch("https://api.backgrounderase.com/v2", {
  method: "POST",
  headers: { "x-api-key": apiKey },
  body: form
});

if (!response.ok) {
  throw new Error(await response.text());
}

await writeFile("./output.png", Buffer.from(await response.arrayBuffer()));

Python

import os
import requests

api_key = os.environ["BACKGROUND_ERASE_API_KEY"]

with open("input.jpg", "rb") as image:
    response = requests.post(
        "https://api.backgrounderase.com/v2",
        headers={"x-api-key": api_key},
        files={"image_file": ("input.jpg", image, "image/jpeg")},
        data={"format": "png", "channels": "rgba", "size": "full"},
        timeout=30,
    )

response.raise_for_status()

with open("output.png", "wb") as result:
    result.write(response.content)

Authentication

Authenticate every request with an API key

API keys are account-scoped credentials. Treat them like production secrets and keep them on a trusted server, worker, or automation backend.

Recommended header

Send the API key on every production request:

x-api-key: YOUR_API_KEY

Accepted alternatives

Backend clients may also use Authorization: Bearer, Authorization: Token, or Authorization: Api-Key. Keep query-string and JSON-body keys for legacy integrations only.

Key management

Generate keys from Account API Access. Rotate keys when team members leave, environments change, or credentials may have been exposed.

Browser and mobile apps should call your backend first. Your backend can attach the BackgroundErase API key and forward only the data required for processing.

Endpoint

Base URL and health checks

Use the versioned endpoint for image processing. Use health endpoints for uptime probes and readiness checks.

POST

https://api.backgrounderase.com/v2

Remove the background from a submitted image.

GET

https://api.backgrounderase.com/v2/account

Validate an API key and read safe account metadata for your integration.

GET

https://api.backgrounderase.com/v2/health

Health check for monitoring and automated readiness checks. Root aliases are also available at /health and /.

View status

Get account

Verify keys and account state before production jobs

Use GET /v2/account from your backend to confirm that a key is valid, identify the key mode, and display safe account details in internal tooling.

Request

curl -f "https://api.backgrounderase.com/v2/account" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "status": "ok",
  "api_key": {
    "valid": true,
    "mode": "live",
    "fingerprint": "tok_fp_abc123"
  },
  "account": {
    "email": "[email protected]",
    "plan": "Business",
    "subscription_status": "active",
    "billing_model": "metered_monthly",
    "usage_unit": "image"
  }
}

Key validation

A successful response includes api_key.valid, a non-secret fingerprint, and a mode of live, admin, or synthetic.

Account metadata

The account object exposes safe fields such as email, plan, subscription status, billing model, and usage unit. It does not return the raw key record.

Failure handling

Missing, invalid, or revoked keys return JSON errors with a status code and request ID. Treat these as configuration issues rather than retryable image-processing failures.

Inputs

Send files, URLs, or base64 images

Multipart uploads are recommended for most production systems because they avoid base64 expansion and preserve a direct file upload contract.

Field	Type	Use	Notes
`image_file`	multipart file	Recommended	Best default for production. Send the source file in multipart form data.
`image_url`	multipart or JSON	Optional	The API fetches a publicly reachable image URL. Avoid expiring or authenticated URLs.
`image_base64`	multipart or JSON	Optional	Use when your system already stores images as base64. Data URL prefixes are accepted.
`image_file_b64`	multipart	Optional	Multipart alias for base64 image uploads. Prefer image_file when you have the original bytes.
`image`	JSON base64	Legacy	Legacy JSON mode. Commonly returns an alpha mask for client-side compositing.
`raw request body`	image bytes	Legacy	Accepted for older integrations when no multipart or JSON content type is sent.

Options

Control output format, sizing, masks, and backgrounds

Options can be sent as multipart form fields alongside image_file. Boolean values accept common forms such as true, false, 1, and 0.

Option	Values	Default	Notes
`format`	png, jpg/jpeg, webp, bmp, tiff/tif, gif	png	Controls the output file type. JPG, BMP, and GIF are flattened because they cannot preserve RGBA transparency.
`channels`	rgba, alpha	rgba	Use rgba for a finished image or alpha for a single-channel mask.
`size`	preview, medium, hd, full, auto	full	Caps final output size without upscaling. auto is treated as full.
`crop`	true, false	false	Tight-crops the non-transparent region of the result.
`bg_color`	CSS color, #rrggbb, #rgb	none	Flattens transparency against a solid background color.
`despill`	true, false	false	Reduces green-screen spill on RGBA outputs while preserving luminance.

Alpha mask output

curl -f "https://api.backgrounderase.com/v2" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "image_file=@/absolute/path/to/image.jpg" \
  -F "channels=alpha" \
  -F "format=png" \
  -o mask.png

When to request alpha masks

Use channels=alpha when your application needs to composite locally, blend the mask into a custom editor, or preserve original pixels while controlling the final render yourself.

Responses

Handle image bytes and JSON responses deliberately

Most multipart requests return raw image bytes. Always inspect status and Content-Type before deciding whether to write a file or parse an error.

Status	Content-Type	Meaning
`200`	image/png, image/webp, image/jpeg	Raw image bytes. Write the response body directly to disk or object storage.
`200`	application/json	JSON mode response with a base64 image or mask, or account metadata from GET /v2/account.
`4xx`	application/json	Validation, authentication, payload, or rate-limit issue. Read the error body.
`5xx`	application/json or text	Transient service or upstream issue. Retry with backoff and alert if sustained.

Errors

Design predictable retry and recovery behavior

Validation errors should be fixed before retrying. Rate-limit and service errors should use bounded retries with jittered exponential backoff.

Status	Name	Recommended action
`400`	Bad request	Check field names, image encoding, and option values.
`401 / 403`	Unauthorized	Verify x-api-key, subscription status, and key propagation.
`413`	Payload too large	Compress the input, use image_url, or downscale before upload.
`415`	Unsupported media type	Use multipart form data or valid JSON.
`429`	Rate limited	Apply exponential backoff or contact sales for higher throughput.
`5xx`	Service error	Retry safely, then contact support with timestamp and request details.

Example error

{
  "error": {
    "code": "image_too_large",
    "message": "image too large (>30 MB).",
    "status": 413,
    "request_id": "req_abc123",
    "details": {}
  }
}

Operations

Run BackgroundErase safely in production

Treat image processing as a pipeline dependency. The most reliable integrations combine input validation, queueing, retries, and monitoring.

Keep API keys server-side. Never ship keys in mobile, browser, or no-code clients unless routed through a trusted backend.

Check both HTTP status and Content-Type before writing a response to disk.

Use retries with exponential backoff for 429 and 5xx responses. Do not retry malformed requests.

Set request timeouts and queue large batches instead of running unbounded concurrent uploads.

Store original and processed asset IDs in your own system so jobs can be replayed safely.

Monitor the status page and your own error budget when BackgroundErase is in a critical path.

Know the privacy default: BackgroundErase does not train on user images unless the account explicitly opts in.

Tutorials

Implementation guides for common stacks and workflows

These guides live in the help center and go deeper than the API reference. Use them when you are wiring BackgroundErase into a specific application, automation platform, or batch job.

Python integration

Send multipart requests from a standard-library Python script.

Node.js integration

Use the built-in Node.js HTTP stack to post files and write PNGs.

Docker gateway

Run a local gateway that calls the API and composites results.

No-code integrations

Build workflows in n8n, Make, Zapier, Airtable, and more.

iOS integration

Add BackgroundErase to a Swift or SwiftUI application.

iOS API client

Use a lightweight iOS client to process photos in-app.

SaaS integration

Design queues, workers, and product flows around background removal.

Ecommerce automation

Process catalog images and route assets into storefront workflows.

Car inventory automation

Clean up dealership and automotive inventory photos in batches.

Compatibility

Switch from remove.bg, Photoroom, and similar APIs

BackgroundErase intentionally supports the common multipart contract used by several background-removal providers. The closer your current integration is to remove.bg or Photoroom's basic endpoint, the less code you need to touch.

For remove.bg-style requests, start by changing the endpoint to https://api.backgrounderase.com/v2 and replacing the API key. Keep the shared form fields, then remove or remap any provider-specific options your old pipeline used.

BackgroundErase equivalent

curl -H "x-api-key: YOUR_BACKGROUND_ERASE_API_KEY" \
  -f "https://api.backgrounderase.com/v2" \
  -F "image_file=@/absolute/path/to/image.jpg" \
  -F "crop=true" \
  -F "bg_color=FFFFFF" \
  -F "format=jpg" \
  -F "size=hd" \
  -o result.jpg

Drop-in multipart pattern

Keep the same file upload flow, replace the endpoint with https://api.backgrounderase.com/v2, and send your BackgroundErase API key in x-api-key.

Mask-first workflows

If your product composites masks locally, request channels=alpha and keep your existing downstream compositing pipeline.

remove.bg

Closest drop-in

https://api.remove.bg/v1.0/removebg

Change the endpoint and API key. Common fields such as image_file, image_url, crop, bg_color, format, and size map directly.

Review provider-specific fields such as type, scale, bg_image_url, and JSON result modes before removing the old integration.

Official docs

Photoroom

Closest drop-in

https://sdk.photoroom.com/v1/segment

BackgroundErase accepts the same core remove.bg-style multipart arguments used by Photoroom's basic remove-background endpoint.

Advanced Image Editing API features, templates, shadows, and positioning options are not part of the drop-in path.

Official docs

Clipdrop / Jasper

Low-change upload

https://clipdrop-api.co/remove-background/v1

Both APIs use x-api-key, multipart form data, image_file, and raw image-byte responses.

Clipdrop chooses output format with the Accept header. Use BackgroundErase form fields such as format, crop, bg_color, and size instead.

Official docs

Slazzer

Moderate mapping

https://api.slazzer.com/v2.0/remove_image_background

The request is multipart and the response is binary image data, so the worker shape is familiar.

Rename source_image_file/source_image_url/source_image_base64 to image_file/image_url/image_base64, bg_color_code to bg_color, and channel to channels.

Official docs

Picsart

Partial migration

https://api.picsart.io/tools/1.0/removebg

Hosted image_url flows, bg_color, and PNG/JPG/WEBP format choices have straightforward equivalents.

Picsart uses a different auth header, different image file field name, and JSON-oriented response patterns, so update response handling.

Official docs

Security

Protect credentials and sensitive media

Background removal often touches user-uploaded media. Keep credentials isolated, limit who can trigger processing, and route enterprise privacy questions through sales or support.

Server-side keys

Attach API keys only from trusted server environments, queue workers, or private automation runners.

Least privilege

Separate development and production keys. Rotate credentials when changing vendors, systems, or team access.

Auditability

Store your own request metadata, job IDs, and asset IDs so your team can debug and replay workflows.

AI Training Policy

Your images are not training data by default

Our principle: We believe your proprietary data is yours alone. While many AI services treat your uploads as their training library, BackgroundErase only uses your data to improve our models if you explicitly give us the green light.

If the training opt-in is not enabled on the account page, uploads are not archived for future training runs and are not retained for over 24 hours.

Read the policy Review account setting

Support

Need help with a production integration?

Send a short description, sample request shape, response status, and approximate timestamp. For enterprise deployments, include expected monthly volume and latency requirements so we can route the conversation correctly.

Contact support Enterprise options