How to Remove Backgrounds from Image URLs

01

When URL input is right

URL input is best when the source image already lives somewhere your backend can point to: a CDN, Shopify media URL, supplier image URL, S3 presigned URL, GCS signed URL, R2 object URL, or a stable public asset from a CMS. In those cases, sending image_url avoids downloading the file into your app just to upload it again (this is the ordinary setup using image_file).

Use image_url when:
  - the source already has a stable CDN or object-storage URL
  - your worker does not need to download and re-upload the file
  - the API can fetch the exact URL without cookies or app auth

Use image_file when:
  - the source is private, short-lived, or session-dependent
  - you already have the bytes in your backend
  - URL fetch failures would be harder to debug than direct upload

If the image is already in your backend as bytes, direct multipart image_file upload is usually less fragile. URL mode is not automatically more production grade. It is production grade when the URL itself is a durable input.

02

The request shape

The simplest production shape is a multipart request with image_url as a normal form field. You still send output options like format, channels, size, crop, and bg_color alongside it if you need additional options.

curl -f "https://api.backgrounderase.com/v2" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "image_url=https://cdn.example.com/products/sku-123.jpg" \
  -F "format=png" \
  -F "channels=rgba" \
  -F "size=full" \
  -o sku-123-transparent.png

In a worker, use FormData the same way you would for a file upload. The difference is that the API downloads the source image from the URL before processing it.

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

const apiKey = process.env.BACKGROUNDERASE_API_KEY;
const sourceUrl = "https://cdn.example.com/products/sku-123.jpg";

const form = new FormData();
form.append("image_url", sourceUrl);
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("./sku-123-transparent.png", Buffer.from(await response.arrayBuffer()));

For a transparent PNG, use format=png and channels=rgba. For a marketplace-ready white background image, use a flattened format like jpg plus bg_color=#ffffff. The URL chooses the input. The output flags choose the result.

03

Preflight the source URL

The most useful debugging habit is testing the exact URL before you blame the processor. Not the product page. Not the image as it appears in your admin UI. The exact string you will send as image_url.

curl -L --fail --output /dev/null \
  --write-out "status=%{http_code}\ncontent_type=%{content_type}\nfinal_url=%{url_effective}\n" \
  "https://cdn.example.com/products/sku-123.jpg"

A good URL preflight answers four questions: did it return a 200, did redirects end somewhere sensible, did the body claim to be an image, and is the URL reachable without your application cookies? A browser tab is not a sufficient test because your browser may be carrying auth state the API will never have.

const response = await fetch("https://cdn.example.com/products/sku-123.jpg", {
  redirect: "follow",
});

console.log("Status:", response.status);
console.log("Content-Type:", response.headers.get("content-type"));
console.log("Final URL:", response.url);

if (!response.ok) {
  throw new Error(`URL fetch failed with ${response.status}`);
}

const contentType = response.headers.get("content-type") || "";
if (!contentType.toLowerCase().startsWith("image/")) {
  throw new Error(`URL did not return an image: ${contentType || "unknown"}`);
}

04

Signed and private URLs

Signed URLs are often the right compromise for private object storage. You keep the bucket private, generate temporary read access for one object, and send that temporary URL to the API. The important word is temporary. The URL needs to survive queue delay, API fetch time, retries, and clock skew.

import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

const s3 = new S3Client({ region: "us-east-1" });

const imageUrl = await getSignedUrl(
  s3,
  new GetObjectCommand({
    Bucket: "my-private-bucket",
    Key: "incoming/sku-123 (front).jpg",
  }),
  { expiresIn: 15 * 60 },
);

const form = new FormData();
form.append("image_url", imageUrl);
form.append("format", "png");
form.append("channels", "rgba");

If signed URL failures are frequent, switch the architecture: have your backend download the private object and send image_file, or process from a queue where the worker can create fresh signed URLs immediately before each attempt.

05

Handle response modes

Multipart requests generally return raw image bytes. That means your worker should check HTTP status, confirm an image Content-Type, and write the response body directly to disk or object storage.

JSON mode is different. It is useful when the platform you are integrating with expects JSON, but you should parse the response as JSON and decode the base64 field. Do not mix the two response paths.

const response = await fetch("https://api.backgrounderase.com/v2", {
  method: "POST",
  headers: {
    "x-api-key": process.env.BACKGROUNDERASE_API_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    image_url: "https://cdn.example.com/products/sku-123.jpg",
    format: "jpg",
    bg_color: "#ffffff",
    size: "hd",
  }),
});

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

const body = await response.json();
const output = Buffer.from(body.image, "base64");
await writeFile("./sku-123-white.jpg", output);

{
  "id": "imgjob_01j2",
  "sourceUrl": "https://cdn.example.com/products/sku-123.jpg",
  "sourceUrlCheckedAt": "2026-07-07T14:20:00.000Z",
  "sourceContentType": "image/jpeg",
  "outputFormat": "png",
  "channels": "rgba",
  "status": "ready",
  "resultKey": "processed/sku-123-transparent.png",
  "attempts": 1
}

Store the original source URL, the checked content type, the output flags, and the result key. If an output looks wrong later, you need to know whether the URL changed, redirected, expired, or returned a different image than the one the user saw.

06

Failure handling

URL failures are not all retryable. A timeout or upstream 5xx from a remote host may deserve a bounded retry. A 403, 404, expired signature, login page, or HTML response usually needs a different URL or a direct upload path.

The retry rule I prefer: retry transient network and service errors; fail fast on permanent URL accessibility problems. If the source URL itself is bad, retries just add cost and make the logs harder to read.

07

Production checklist

A good image URL pipeline is boring because every URL has already proven it can be fetched, every response mode has one handler, and every failure tells you whether to retry or fix the source.