How to Remove Image Backgrounds with an API

Need to remove image backgrounds programmatically? Whether you're building an e-commerce product catalog, a photo editing app, or automating image processing at scale, you need a background removal API that's fast, accurate, and won't break the bank.

This tutorial walks you through the entire process: from getting an API key to making your first background removal call, handling the response, and integrating it into your application. We'll cover cURL, Node.js, and Python with copy-paste code you can use immediately.

What You'll Need

• A ClearCut API key (free — 50 images/month, no credit card)
• An image in JPG, PNG, or WebP format (up to 25MB)
• One of: cURL (any terminal), Node.js 18+, or Python 3.8+

Step 1: Get Your Free API Key

Step 2: Remove Your First Background

The ClearCut API has a single endpoint: POST /v1/remove. Send an image, get back a transparent PNG. That's the entire API.

Request Format

• URL: https://clearcut-2834.polsia.app/v1/remove
• Method: POST
• Auth: Authorization: Bearer YOUR_API_KEY
• Body: multipart/form-data with an image field
• Response: The transparent PNG image (binary)

Working Code Examples

# Remove background from a local image
curl -X POST https://clearcut-2834.polsia.app/v1/remove \
  -H "Authorization: Bearer cc_YOUR_API_KEY" \
  -F "image=@photo.jpg" \
  --output result.png

# The output is a transparent PNG
# Check the processing time from response headers:
curl -X POST https://clearcut-2834.polsia.app/v1/remove \
  -H "Authorization: Bearer cc_YOUR_API_KEY" \
  -F "image=@photo.jpg" \
  -D - --output result.png 2>/dev/null | grep X-Processing-Time

import { readFileSync, writeFileSync } from 'fs';

const API_KEY = 'cc_YOUR_API_KEY';
const API_URL = 'https://clearcut-2834.polsia.app/v1/remove';

async function removeBackground(imagePath) {
  const formData = new FormData();
  const imageBuffer = readFileSync(imagePath);
  const blob = new Blob([imageBuffer], { type: 'image/jpeg' });
  formData.append('image', blob, 'photo.jpg');

  const response = await fetch(API_URL, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${API_KEY}` },
    body: formData,
  });

  if (!response.ok) {
    const err = await response.json();
    throw new Error(err.error?.message || 'API request failed');
  }

  // Response is the PNG image directly
  const buffer = Buffer.from(await response.arrayBuffer());
  const processingTime = response.headers.get('X-Processing-Time');
  console.log(`Done in ${processingTime}`);

  return buffer;
}

// Usage
const result = await removeBackground('./photo.jpg');
writeFileSync('./result.png', result);
console.log('Saved result.png');

import requests

API_KEY = "cc_YOUR_API_KEY"
API_URL = "https://clearcut-2834.polsia.app/v1/remove"

def remove_background(image_path: str, output_path: str):
    """Remove background from an image file."""
    with open(image_path, "rb") as f:
        response = requests.post(
            API_URL,
            headers={"Authorization": f"Bearer {API_KEY}"},
            files={"image": ("photo.jpg", f, "image/jpeg")},
        )

    if response.status_code != 200:
        error = response.json()
        raise Exception(error.get("error", {}).get("message", "Failed"))

    # Response body is the transparent PNG
    with open(output_path, "wb") as out:
        out.write(response.content)

    processing_time = response.headers.get("X-Processing-Time", "N/A")
    print(f"Saved to {output_path} (processed in {processing_time})")

# Usage
remove_background("photo.jpg", "result.png")

All three examples do the same thing: send photo.jpg to the API and save the transparent PNG as result.png. Processing typically takes 1–2 seconds per image.

Step 3: Handle the Response

// 400 — No image or invalid format
{
  "error": {
    "code": "NO_IMAGE",
    "message": "No image provided. Send a file with field name \"image\"."
  }
}

// 503 — Service temporarily unavailable
{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Background removal service is temporarily limited."
  }
}

Processing Images in Batch

Need to process hundreds of images? Here's how to batch them efficiently with concurrency control, so you don't overwhelm the API or your own machine.

import { readFileSync, writeFileSync, readdirSync } from 'fs';
import { join, basename } from 'path';

const API_KEY = 'cc_YOUR_API_KEY';
const API_URL = 'https://clearcut-2834.polsia.app/v1/remove';
const CONCURRENCY = 3; // Process 3 images at a time

async function processOne(inputPath, outputDir) {
  const formData = new FormData();
  const blob = new Blob([readFileSync(inputPath)]);
  formData.append('image', blob, basename(inputPath));

  const res = await fetch(API_URL, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${API_KEY}` },
    body: formData,
  });

  if (!res.ok) throw new Error(`Failed: ${res.status}`);
  const outPath = join(outputDir, basename(inputPath, '.jpg') + '.png');
  writeFileSync(outPath, Buffer.from(await res.arrayBuffer()));
  return outPath;
}

// Process a folder of images with concurrency limit
const files = readdirSync('./input').filter(f => /\.(jpg|png|webp)$/i.test(f));
for (let i = 0; i < files.length; i += CONCURRENCY) {
  const batch = files.slice(i, i + CONCURRENCY);
  const results = await Promise.all(
    batch.map(f => processOne(join('./input', f), './output'))
  );
  console.log(`Batch ${Math.floor(i / CONCURRENCY) + 1}: ${results.length} done`);
}

import os
import requests
from concurrent.futures import ThreadPoolExecutor

API_KEY = "cc_YOUR_API_KEY"
API_URL = "https://clearcut-2834.polsia.app/v1/remove"

def process_one(input_path, output_dir):
    with open(input_path, "rb") as f:
        resp = requests.post(
            API_URL,
            headers={"Authorization": f"Bearer {API_KEY}"},
            files={"image": f},
        )
    resp.raise_for_status()
    name = os.path.splitext(os.path.basename(input_path))[0]
    out_path = os.path.join(output_dir, f"{name}.png")
    with open(out_path, "wb") as out:
        out.write(resp.content)
    return out_path

# Process all images in ./input with 3 threads
input_dir = "./input"
output_dir = "./output"
os.makedirs(output_dir, exist_ok=True)
images = [f for f in os.listdir(input_dir) if f.endswith((".jpg", ".png", ".webp"))]

with ThreadPoolExecutor(max_workers=3) as pool:
    paths = [os.path.join(input_dir, img) for img in images]
    results = list(pool.map(lambda p: process_one(p, output_dir), paths))

print(f"Processed {len(results)} images")

Pricing: ClearCut vs. Other APIs

Background removal APIs vary wildly in pricing. Here's how ClearCut compares to the popular alternatives for developers who care about cost:

At scale, the difference is dramatic. Processing 10,000 product photos costs $200 with ClearCut vs. $2,000+ with most alternatives. Same transparent PNGs. Same quality. 10x less money.

API Reference Quick Card

For the full API reference, error codes, and language-specific SDKs, check the ClearCut API documentation.

Common Use Cases

• E-commerce product photos: Strip backgrounds to create clean white-background listings for marketplaces. See the e-commerce guide →
• Profile picture processing: Let users upload photos and automatically remove backgrounds for avatars or ID cards.
• Design tool integration: Add one-click background removal to your Figma plugin, web editor, or design platform.
• Batch catalog processing: Process thousands of product images overnight using the batch examples above.
• Real estate listings: Remove cluttered backgrounds from property photos, furniture shots, or staging images.

See more developer integration patterns in the developer use cases guide.

Tips for Best Results

1. Use high-resolution input. The AI works best with clear, well-lit images. Low-resolution or blurry photos may produce rough edges.
2. JPG is fine. You don't need to convert to PNG before sending. JPG, PNG, and WebP all work. The output is always a transparent PNG.
3. Check the X-Processing-Time header. First request after a cold start may take 10–12 seconds. Subsequent requests are 1–2 seconds.
4. Retry on 503. If the service is temporarily limited, wait 5 seconds and retry. The model scales automatically.
5. Batch with concurrency 3–5. The API handles concurrent requests well. Going above 5 won't speed things up much.