Getting Started with a Background Removal API (Node.js & Python)

If you're removing backgrounds from more than a handful of images a week, an API saves hours. This guide walks through using ours, but the concepts apply to any background removal API.

1. Get a key

Create a free account, open the dashboard, and create an API key. Copy it somewhere safe — it's shown once. You get 50 free preview calls a month for testing.

Keep the key on your server or in environment variables. Never put it in browser code or a public repository.

2. Your first request

curl -X POST https://www.removingbackground.io/v1/removebg \
  -H "X-Api-Key: $RBG_API_KEY" \
  -F image_file=@photo.jpg \
  -F size=preview \
  -o cutout.png

size=preview is free (up to 600×600px). Change it to full for full resolution (1 credit).

3. Node.js: process a folder

import fs from "node:fs";
import path from "node:path";

const dir = "./photos";
for (const file of fs.readdirSync(dir)) {
  const form = new FormData();
  form.append("image_file", new Blob([fs.readFileSync(path.join(dir, file))]), file);
  form.append("size", "full");
  form.append("bg_color", "#ffffff");
  const res = await fetch("https://www.removingbackground.io/v1/removebg", {
    method: "POST",
    headers: { "X-Api-Key": process.env.RBG_API_KEY },
    body: form,
  });
  if (!res.ok) { console.error(file, (await res.json()).error.message); continue; }
  fs.writeFileSync(`./out/${file.replace(/\.\w+$/, ".jpg")}`, Buffer.from(await res.arrayBuffer()));
}

4. Python

import os, requests
r = requests.post(
    "https://www.removingbackground.io/v1/removebg",
    headers={"X-Api-Key": os.environ["RBG_API_KEY"]},
    files={"image_file": open("photo.jpg", "rb")},
    data={"size": "full", "crop": "true"},
    timeout=120,
)
r.raise_for_status()
open("cutout.png", "wb").write(r.content)

5. Handle errors properly

Errors come back as JSON with a code. The ones to handle:

• 402 insufficient_credits — top up, then retry
• 429 rate_limited — wait and retry with backoff
• 502 processing_failed — retry once; credits are refunded automatically

6. Check your balance

GET /v1/account returns your credits and free calls used this month — useful for alerts before a big run.

Full reference: API documentation.

FAQ

Can I send an image URL instead of a file?

Yes, use the image_url parameter with a public http(s) URL.

Can I get WebP output?

Yes — add format=webp.