How to Use the Photoroom API to Automate Background Removal at Scale

You’ve got 500 product images that need clean white backgrounds before tomorrow’s catalog launch, and your designer just quoted you three days of work. If you’ve been there — manually cutting out products in Photoshop at 11 PM, or paying per-image rates to a retouching service that still gets the edges wrong — then the Photoroom API is worth your full attention.

Photoroom started as a consumer mobile app for background removal and has grown into a serious backend tool used by e-commerce teams, SaaS platforms, and marketplace operators. The API lets you programmatically remove backgrounds, add new ones, and apply AI-driven edits at a scale that would be impossible manually. This tutorial walks you through everything: getting your API key, making your first request, handling real-world edge cases, and deciding whether the pricing makes sense for your use case.

What the Photoroom API Actually Does

At its core, the Photoroom API accepts an image and returns a version with the background removed — delivered as a PNG with a transparent background. But it goes further than basic cutout tools:

• Background removal with subject-aware AI (handles hair, fur, complex edges)
• Background replacement — solid colors, custom images, or AI-generated scenes
• Shadow and reflection effects for product shots
• Batch processing via standard REST calls
• Output format control — size, DPI, format (PNG/JPEG/WebP)

The underlying model is the same one powering the Photoroom mobile app, which has been downloaded over 100 million times and refined on an enormous volume of real-world images. That matters because generic segmentation models struggle with transparent objects, reflective surfaces, and fine hair detail — problems that Photoroom has specifically invested in solving.

Before You Start: What You’ll Need

• A Photoroom account (free tier available at photoroom.com)
• An API key (generated from your dashboard)
• A REST client — curl, Postman, or any HTTP library in your language of choice
• Basic familiarity with JSON responses and multipart form data

No SDK is required, though community wrappers exist for Python and Node.js on GitHub.

Step 1: Get Your API Key

1. Go to photoroom.com/api and create or log into your account.
2. Navigate to Dashboard → API Keys.
3. Click Generate New Key. Give it a descriptive name (e.g., catalog-pipeline-prod).
4. Copy the key immediately — it won’t be shown again in full.

Store it as an environment variable, not hardcoded in your source:

export PHOTOROOM_API_KEY="your_key_here"

Step 2: Make Your First Background Removal Request

The endpoint is straightforward. Here’s a curl example:

curl -X POST "https://sdk.photoroom.com/v1/segment" \
  -H "x-api-key: $PHOTOROOM_API_KEY" \
  -F "image_file=@/path/to/your/product.jpg" \
  --output result.png

That’s it for the baseline call. The API returns a PNG with transparency where the background was. Response time on a typical product image (under 5 MB) is usually under two seconds.

What the API accepts:

• JPEG, PNG, WebP
• Up to 25 MP resolution
• Max file size: 30 MB per request

Step 3: Add a Background or Color

Returning a transparent PNG is useful for compositing in your own pipeline, but if you want Photoroom to apply a background in one step, you can pass additional parameters.

Solid white background (common for e-commerce):

curl -X POST "https://sdk.photoroom.com/v1/segment" \
  -H "x-api-key: $PHOTOROOM_API_KEY" \
  -F "[email protected]" \
  -F "bg_color=%23FFFFFF" \
  --output product_white_bg.jpg

Custom background image:

curl -X POST "https://sdk.photoroom.com/v1/segment" \
  -H "x-api-key: $PHOTOROOM_API_KEY" \
  -F "[email protected]" \
  -F "bg_image=@background_scene.jpg" \
  --output product_composed.jpg

Color values are hex-encoded and URL-encoded (so #FFFFFF becomes %23FFFFFF). This is a common trip-up — if your background color isn’t applying, check the encoding first.

Step 4: Build a Batch Processing Script

Single-image requests are fine for testing. Production workloads need a loop. Here’s a minimal Python script that processes a folder of images concurrently using requests and concurrent.futures:

import os
import requests
from concurrent.futures import ThreadPoolExecutor, as_completed
from pathlib import Path

API_KEY = os.environ["PHOTOROOM_API_KEY"]
API_URL = "https://sdk.photoroom.com/v1/segment"
INPUT_DIR = Path("./input_images")
OUTPUT_DIR = Path("./output_images")
OUTPUT_DIR.mkdir(exist_ok=True)

def remove_background(image_path: Path) -> str:
    with open(image_path, "rb") as f:
        response = requests.post(
            API_URL,
            headers={"x-api-key": API_KEY},
            files={"image_file": (image_path.name, f, "image/jpeg")},
            data={"bg_color": "%23FFFFFF"},
        )
    if response.status_code == 200:
        output_path = OUTPUT_DIR / f"{image_path.stem}_bg_removed.png"
        output_path.write_bytes(response.content)
        return f"✓ {image_path.name}"
    else:
        return f"✗ {image_path.name} — {response.status_code}: {response.text}"

image_paths = list(INPUT_DIR.glob("*.jpg")) + list(INPUT_DIR.glob("*.png"))

with ThreadPoolExecutor(max_workers=5) as executor:
    futures = {executor.submit(remove_background, p): p for p in image_paths}
    for future in as_completed(futures):
        print(future.result())

Key notes on this approach:

• max_workers=5 is conservative — stay within your plan’s rate limit (see pricing section below)
• Add exponential backoff for 429 Too Many Requests responses
• Log failures to a file separately so you can retry them without re-processing successes

Step 5: Handle Edge Cases Gracefully

Real-world image pipelines break on real-world images. Here’s what to watch for:

1. Transparent or glass products The model handles most cases, but highly reflective or transparent subjects (wine glasses, clear bottles) can lose detail at the edges. Pre-test a sample set before committing a full catalog run.

2. Images with people Hair and loose clothing edges are where cheaper tools fail noticeably. Photoroom’s model performs well here, but very fine or windswept hair in low-contrast backgrounds can still lose strands. If pixel-perfect accuracy is critical, build in a manual QA step for flagged outputs.

3. File size limits Files over 30 MB will return a 413 Payload Too Large error. Resize or compress before upload — for most e-commerce use cases, 2000×2000 px at 72 DPI is more than sufficient.

4. Rate limiting The API uses standard HTTP 429 responses with a Retry-After header. Respect it. Aggressive retry-without-backoff loops will get your key temporarily suspended.

Pricing: What Does It Actually Cost?

Photoroom’s API pricing is credit-based. As of mid-2026, the structure is roughly:

Each background removal = 1 credit. Adding a background or applying effects in the same call does not cost extra credits — it’s still one operation per image.

Verify current pricing directly at photoroom.com/api before committing to a plan, as these rates are subject to change.

For context: a mid-size e-commerce operator processing 10,000 SKU images per month would land on the Growth plan at ~$99/month — comparable to one hour of freelance retouching work, but running in minutes.

How It Compares to Alternatives

Remove.bg is Photoroom’s closest direct competitor and offers a similar credit model. The quality difference is marginal on clean product shots; Photoroom tends to perform better on complex scenes and human subjects. Adobe Firefly API is in a different league for generative features but requires enterprise agreements and is overkill for straightforward background removal pipelines.

If you’re evaluating purely on background removal accuracy, both Photoroom and Remove.bg are significantly ahead of general-purpose segmentation APIs like AWS Rekognition or Google Vision, which aren’t purpose-built for clean cutouts.

Step 6: Integrate Into Your Existing Workflow

A few common integration patterns:

E-commerce catalog pipeline: Trigger the API call on product image upload via a webhook. Store the result in your CDN alongside the original. Tag processed images in your database to avoid reprocessing.

Shopify / WooCommerce stores: Neither platform has native Photoroom integration, but you can wire it up with a serverless function (AWS Lambda, Vercel Edge Functions) that intercepts image uploads and returns the processed version before it’s written to your media library.

Figma or design tooling: Photoroom has a Figma plugin for individual use, but for team-scale workflows, the API-first approach gives you far more control over output naming, sizing, and format.

CI/CD asset pipeline: If your marketing team commits image assets to a Git repo (common in static site workflows), a GitHub Action can run the API on new image commits and commit the processed versions automatically.

Conclusion

The Photoroom API is a well-documented, production-ready tool that solves a specific problem — automated background removal — better than most general-purpose alternatives. If your workflow involves more than a few hundred product images per month, the economics of automating this step are obvious: the Growth plan at ~$99/month handles 10,000 images, a volume that would cost far more in designer time or per-image retouching services.

My recommendation: Start on the free tier (50 credits) to validate quality on your specific image types before committing. Pay particular attention to your hardest cases — transparent products, complex hair, low-contrast edges. If the output quality meets your bar on those, the API will handle your standard product photography without issue.

The integration lift is low (a working batch script in under 30 lines of Python), the documentation is solid, and the pricing scales reasonably. For e-commerce teams, marketplace platforms, and anyone building image-heavy SaaS products, it’s one of the cleaner API integrations you’ll ship this year.