How to Generate Transparent PNGs with an API

01

The exact request

If you already have a local file, the cleanest request is multipart form data. Attach the source image as image_file, set format to png, and set channels to rgba. That combination means: return an image file with red, green, blue, and alpha channels.

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

In a Node worker, the same request shape looks like this. The part people forget is response handling: most successful multipart requests return binary image bytes, not JSON. Do not call response.json() unless you know your request will return json (most requests don't).

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

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

const form = new FormData();
form.append("image_file", new Blob([input], { type: "image/jpeg" }), "product.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());
}

const contentType = response.headers.get("content-type") || "";
if (!contentType.toLowerCase().startsWith("image/")) {
  throw new Error(`Expected image bytes, got ${contentType || "unknown content type"}`);
}

await writeFile("./product-transparent.png", Buffer.from(await response.arrayBuffer()));

You can send image URLs instead of file bytes when the source already lives in object storage, but the output decision stays the same. URL input changes how the API fetches the source; format and channels still decide what comes back.

02

RGBA is the finished image

RGBA is the output you want when the asset should be immediately useful in a storefront, CMS, design tool, ad builder, profile editor, or batch catalog job. The RGB channels hold the visible foreground color. The alpha channel says how opaque each pixel is.

This is why a transparent PNG is usually larger than a JPEG. It has to preserve both color and per-pixel opacity, and PNG uses lossless compression. That size is usually worth it for a reusable asset. You can always create smaller flattened derivatives later, but once you flatten transparency onto white, black, or a brand color, you cannot recover the original alpha edge from that flattened file.

03

When alpha masks are better

channels=alpha is a different product. It returns a PNG mask where the pixel values represent opacity. That is useful when your application wants to composite locally, feed the mask into an editor, keep the original pixels untouched, or run multiple foreground/background combinations from one segmentation result.

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

The confusion usually starts because both are PNG files. The file extension does not tell you whether the output is a finished cutout or a mask. The request does. Build your storage keys and database fields with names like transparentResultKey and alphaMaskKey so future code does not guess based on .png.

04

Crop, size, and canvas choices

Transparency is only one part of the output. The canvas around the subject decides how the asset behaves downstream. A transparent PNG can preserve the original image dimensions, or it can be tight-cropped to the subject. Both are correct in different workflows.

transparent PNG:
  format=png
  channels=rgba
  bg_color omitted

alpha mask:
  format=png
  channels=alpha

white marketplace image:
  format=jpg
  channels=rgba
  bg_color=#ffffff

tight cutout:
  format=png
  channels=rgba
  crop=true

Be careful with bg_color. A background color is useful when you want a flattened output, like a white-background marketplace JPEG. It is not the setting for a true transparent PNG. If you set a background color, you are asking for pixels behind the subject to be filled or composited, not left transparent.

05

Avoid halos and bad edges

Most transparent PNG complaints are edge complaints. A result looks fine in one viewer, then shows a white fringe on a dark background or a dark fringe on a light one. Sometimes the segmentation is wrong. Sometimes the alpha is fine, but the RGB colors in semi-transparent edge pixels were prepared against the wrong background.

The practical test is simple: put the output on multiple backgrounds before you approve it. A checkerboard only proves that transparency exists. Dark, light, and colored backgrounds reveal whether the edge will survive real layouts.

06

Validate and store the result

A production worker should not blindly save any successful HTTP response as output.png. Check the status code, inspect Content-Type, and, for extra safety, verify the PNG magic bytes before the file becomes a user-visible asset.

import os
import requests

api_key = os.environ["BACKGROUNDERASE_API_KEY"]

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

response.raise_for_status()

if not response.headers.get("content-type", "").startswith("image/"):
    raise RuntimeError("Processor did not return image bytes")

with open("product-transparent.png", "wb") as result:
    result.write(response.content)

function assertPng(buffer) {
  const signature = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);

  if (!buffer.subarray(0, 8).equals(signature)) {
    throw new Error("Expected a PNG file");
  }
}

Storage naming should make the output type obvious. Transparent PNGs, alpha masks, flattened JPEGs, and preview derivatives should not share a vague key like result.png. Future you will not remember which result that meant.

products/prod_123/source/original.jpg
products/prod_123/renders/transparent-full.png
products/prod_123/renders/transparent-hd.png
products/prod_123/renders/mask.png
products/prod_123/renders/white-background.jpg

For web delivery, serve transparent PNGs with Content-Type: image/png. Do not run them through an image optimization step that silently converts everything to JPEG. If you create WebP or AVIF variants later, test that your conversion keeps alpha and that every consuming platform supports the chosen format.

07

Production checklist

Transparent output should be fully accounted for by the time it reaches users. The request options, storage names, validation checks, and preview UI should all agree on what kind of image was created.