DEV Community: Oleg Tagobitsky

Turn a dealer's photo feed into studio-background car photos in Python (with retries)

Oleg Tagobitsky — Tue, 03 Nov 2026 14:27:52 +0000

A dealer sends you a photo feed: a CSV with a stock number and an image URL per row, a few hundred rows a day. Your listing pages want every car on the same clean background, with a soft shadow, and preferably without the license plate.

This is the script I'd start with. It reads the feed, sends each URL to a car background removal API, retries only what can succeed later, writes a report of what needs a human look, and then puts each car on a light-grey 4:3 backdrop that listing sites like. About 90 lines of Python, requests and Pillow.

The API call

One photo is one request. The URL goes in a multipart field, the key in a header, and the mode picks the output:

curl -X POST "https://api4ai.cloud/img-bg-removal/v1/cars/results?mode=fg-image-shadow-hideclp" \
  -H "X-API-KEY: $API4AI_KEY" \
  -F "url=https://static.api4.ai/samples/img-bg-removal-cars-2.jpg"

`mode`	Output
`fg-image`	Car on a transparent background
`fg-image-shadow`	With a soft shadow
`fg-image-hideclp`	License plate hidden
`fg-image-shadow-hideclp`	Both
`fg-mask`	Mask only, for your own compositing

GET https://api4ai.cloud/img-bg-removal/v1/modes returns that list at runtime. The result is JSON with the cut-out as a base64 PNG, the same size as the input.

The part that bites: failures are HTTP 200

If the service can't load or process a photo (a dead URL in the feed, a file that isn't an image), you don't get a 4xx. You get a 200 with this:

{"results": [{"status": {"code": "failure", "message": "Can not load file from url https://..."}, "entities": []}]}

So "retry on error" has to mean two different things:

HTTP 429 and 5xx, or a network error: temporary. Wait and try again (1, 2, 4, 8 seconds).
HTTP 200 with status.code == "failure": the photo itself is the problem. Retrying won't help; put it on the "check these" list with the message.

The script

"""Turn a dealer's photo feed (a CSV of image URLs) into studio-background PNGs.

Usage:  API4AI_KEY=... python car_feed.py feed.csv out/
The CSV needs two columns: stock_id, image_url.
"""
import base64, csv, os, sys, time
from concurrent.futures import ThreadPoolExecutor
from pathlib import Path

import requests

URL = "https://api4ai.cloud/img-bg-removal/v1/cars/results"
MODE = "fg-image-shadow-hideclp"   # shadow + plate hidden; see GET /img-bg-removal/v1/modes
KEY = os.environ["API4AI_KEY"]
RETRY_STATUS = {429, 500, 502, 503, 504}


def cut_out(image_url, attempts=4):
    """Return (png_bytes, None) or (None, reason). Retries only what can succeed later."""
    for attempt in range(attempts):
        try:
            r = requests.post(URL, params={"mode": MODE},
                              headers={"X-API-KEY": KEY},
                              files={"url": (None, image_url)}, timeout=90)
        except requests.RequestException as e:
            reason = f"network: {e.__class__.__name__}"
        else:
            if r.status_code in RETRY_STATUS:
                reason = f"HTTP {r.status_code}"
            elif r.status_code != 200:
                return None, f"HTTP {r.status_code}: {r.text[:120]}"
            else:
                result = r.json()["results"][0]
                # A bad photo still comes back as HTTP 200, with status "failure".
                if result["status"]["code"] != "ok":
                    return None, result["status"]["message"]
                picture = next(e for e in result["entities"] if e["kind"] == "image")
                return base64.b64decode(picture["image"]), None
        time.sleep(2 ** attempt)          # 1, 2, 4, 8 s
    return None, f"gave up after {attempts} tries ({reason})"


def process(row, out_dir):
    name = f"{row['stock_id']}-{Path(row['image_url'].split('?')[0]).stem}.png"
    png, error = cut_out(row["image_url"])
    if png:
        (out_dir / name).write_bytes(png)
    return {**row, "output": name if png else "", "error": error or ""}


def main(feed_csv, out_dir):
    out_dir = Path(out_dir)
    out_dir.mkdir(parents=True, exist_ok=True)
    with open(feed_csv, newline="") as f:
        rows = list(csv.DictReader(f))
    with ThreadPoolExecutor(max_workers=8) as pool:
        results = list(pool.map(lambda r: process(r, out_dir), rows))
    with open(out_dir / "report.csv", "w", newline="") as f:
        w = csv.DictWriter(f, fieldnames=["stock_id", "image_url", "output", "error"])
        w.writeheader()
        w.writerows(results)
    failed = [r for r in results if r["error"]]
    print(f"{len(results) - len(failed)} done, {len(failed)} to check (see report.csv)")
    for r in failed:
        print(f"  {r['stock_id']}: {r['image_url']} -> {r['error']}")


if __name__ == "__main__":
    main(*sys.argv[1:3])

Run it:

pip install requests pillow
export API4AI_KEY=...            # from portal.api4.ai
python car_feed.py feed.csv out/

On a four-row test feed with one dead URL, it printed:

3 done, 1 to check (see report.csv)
  A1004: https://static.api4.ai/samples/img-bg-removal-cars-404.jpg -> Can not load file from url https://static.api4.ai/samples/img-bg-removal-cars-404.jpg

Eight workers is a reasonable start for a few hundred photos a day. If you see 429s in the report, lower max_workers; the backoff covers the occasional one.

From cut-out to listing photo

The API gives you a transparent PNG, so the backdrop is yours. This step trims each PNG to the car and its shadow, scales it to fill most of a 1600×1200 (4:3) frame and flattens it onto light grey, which is kinder to white and silver cars than pure white:

"""Put each cut-out on a light-grey studio backdrop, padded to 4:3, as JPEG."""
import sys
from pathlib import Path
from PIL import Image

BACKDROP = (236, 236, 236)        # light grey: kinder to white and silver cars than pure white


def to_listing(png_path, out_path, min_width=1600):
    car = Image.open(png_path).convert("RGBA")
    car = car.crop(car.getchannel("A").getbbox())  # trim to the car and its shadow
    w, h = car.size
    width, height = min_width, round(min_width * 3 / 4)
    scale = min(width / w, height / h) * 0.88     # the car fills most of the frame
    car = car.resize((round(w * scale), round(h * scale)), Image.LANCZOS)
    canvas = Image.new("RGB", (width, height), BACKDROP)
    canvas.paste(car, ((width - car.width) // 2, (height - car.height) // 2), car)
    canvas.save(out_path, "JPEG", quality=90)


if __name__ == "__main__":
    src, dst = Path(sys.argv[1]), Path(sys.argv[2])
    dst.mkdir(parents=True, exist_ok=True)
    for png in sorted(src.glob("*.png")):
        to_listing(png, dst / f"{png.stem}.jpg")
        print(png.name, "->", f"{png.stem}.jpg")

python to_listing.py out/ listing/

Why 4:3 and 1600 px: Google's vehicle ads image guidelines recommend a 4:3 ratio and at least 1500 × 1500 pixels for the best results, and most listing sites crop close to 4:3 anyway. Change min_width and the ratio if your site uses something else.

The "check these" list, beyond failures

report.csv catches what the API rejected. A few things only a person catches, so look at these before you switch the script on for every dealer:

Windows. Glass is see-through, so the old background can show through the side and rear windows. Look at the estate car above: trees from the original photo are still visible through its rear side windows. Side-on shots against a busy background are where it shows most. Today that's the weak spot to check by eye.
Open doors, tailgates, convertibles: more of the scene shows through the car.
Interiors, engine bays, odometer close-ups: no background to replace. If the feed tags photo types, send only exteriors.
Cropped cars: a bumper cut off by the frame stays cut off.
Google's vehicle ads: the guidelines list modified license plates as allowed but possibly hurting performance, so for that feed use fg-image-shadow instead of the -hideclp mode.

A good first run: one dealer's last 100 photos, every result opened, before the script runs on new uploads.

Cost

The car API is $30 per 1,000 images, pay as you go, no subscription. A new account on the API4AI developer portal gets $5 of credit, about 166 car photos, enough to run this on a real feed. Failed photos come back with a reason, so keep an eye on the report. Volume pricing is on request from about 15,000 photos a month.

If you'd rather not write code for a small dealer, the same engine runs in the browser at CarBG, with the same login and balance.

More on the options and what to check: Car background removal API: studio backgrounds at upload.

Moving Off the remove.bg API Before Dec 1: The Code Change in cURL, Python and Node

Oleg Tagobitsky — Wed, 28 Oct 2026 11:24:24 +0000

remove.bg is closing its standalone site on December 1, 2026, at 9:00 CET. Its API docs say background removal moves to Leonardo.Ai (also part of Canva) from that day, and its pricing page says unused credits expire at the same moment. If a script, a shop plugin or a Zapier step of yours calls api.remove.bg/v1.0/removebg, it needs a new home in the next six weeks.

This post is the practical part: what the options cost, what changes in the call, and the code for one of them, ours (we make the API4AI Background Removal API), next to the remove.bg call you have now.

Three ways out

Leonardo.Ai is remove.bg's official successor. It's a new API rather than the same one at a new address: JSON requests with a Bearer key, the image as a URL or base64 instead of a multipart upload, and the result as a link or base64 in JSON. Its migration guide lists what isn't supported, including format=zip and raw image bytes in the response. Background removal costs $0.1047 an image.
Photoroom has built its API to be a drop-in: per its own migration post, you change the endpoint URL and the key, and the main parameters (image_file, crop, bg_color, format, size) carry over. $0.02 an image on its Basic plan.
A different API with a thin adapter. That's the rest of this post. The request changes a little, the response changes more, and an 80-line Python function hides both from the rest of your code.

If you want zero code changes, Photoroom is the honest answer. If you can spend half an hour on an adapter, read on.

What it costs per month

List prices, read on each company's public page on Oct 21, 2026. For remove.bg, the smallest subscription that covers the volume (it stops on Dec 1, so this is what you pay now, not an option).

Images a month	remove.bg (subscription)	Leonardo.Ai	Photoroom (Basic)	API4AI
1,000	$189 (1,200-credit plan)	$104.70	$20	$5
10,000	$989	$1,047	$200	$50
50,000	$3,950	$5,235	$1,000	$250

Photoroom offers volume discounts on its Enterprise plan from 200,000 images a year, and we give a volume price from about 15,000 images a month (write to hello@api4.ai). We're not the cheapest background removal API on the market, and we don't claim to be. What we offer: pay as you go with no subscription, a balance that never expires, no GPU to run, commercial use of the results (see our Terms of Use), and $5 of free credit when you sign up, enough for 1,000 images.

What changes in the call

	remove.bg	API4AI
Endpoint	`POST https://api.remove.bg/v1.0/removebg`	`POST https://api4ai.cloud/img-bg-removal/v1/results`
Key	`X-Api-Key` header	`X-API-KEY` header (header names aren't case-sensitive, so the same line works with the new key)
A file	multipart field `image_file`	multipart field `image`
A link	`image_url`	`url`
Result	image bytes in the body	JSON, with the PNG as base64 in `results[0].entities[]`
A photo it can't process	an HTTP error status	HTTP 200 with `status.code = "failure"` and a reason
Input size	up to 25 megapixels with `size=auto` (its docs)	JPEG or PNG, under 16 MB, up to 4096×4096
`size`, `format`, `crop`, `bg_color`	parameters	the result is always a full-size PNG with a transparent background; crop, color and JPG/WebP are a few lines of Pillow (in the adapter below)
Your own background image	`bg_image_file`, `bg_image_url`	`image-bg`, `url-bg`
Shadows, `type`, `roi`, `scale`, `position`, ZIP output	supported	not available

The last row matters: if you rely on remove.bg's shadows or its car and product modes, check the result on your own photos before you switch. The demo on our Background Removal page takes any JPEG or PNG without an account.

The same call, before and after

cURL

remove.bg:

curl -H "X-Api-Key: $REMOVEBG_KEY" \
     -F "image_file=@car.jpg" \
     -F "size=auto" \
     -f https://api.remove.bg/v1.0/removebg -o no-bg.png

API4AI (the PNG is inside the JSON, so jq picks it out and base64 decodes it):

curl -s -X POST "https://api4ai.cloud/img-bg-removal/v1/results" \
     -H "X-API-KEY: $API4AI_KEY" \
     -F "image=@car.jpg" \
  | jq -r '.results[0].entities[] | select(.kind == "image") | .image' \
  | base64 --decode > no-bg.png

Python

remove.bg:

import requests

r = requests.post(
    "https://api.remove.bg/v1.0/removebg",
    headers={"X-Api-Key": REMOVEBG_KEY},
    files={"image_file": open("car.jpg", "rb")},
    data={"size": "auto"},
)
r.raise_for_status()
open("no-bg.png", "wb").write(r.content)

API4AI:

import base64
import requests

r = requests.post(
    "https://api4ai.cloud/img-bg-removal/v1/results",
    headers={"X-API-KEY": API4AI_KEY},
    files={"image": open("car.jpg", "rb")},
)
r.raise_for_status()
result = r.json()["results"][0]
if result["status"]["code"] != "ok":                # HTTP 200 can still be a failure
    raise RuntimeError(result["status"]["message"])
image = next(e for e in result["entities"] if e["kind"] == "image")
open("no-bg.png", "wb").write(base64.b64decode(image["image"]))

Node (18+)

remove.bg:

import fs from "node:fs";

const form = new FormData();
form.append("size", "auto");
form.append("image_file", await fs.openAsBlob("car.jpg"), "car.jpg");

const res = await fetch("https://api.remove.bg/v1.0/removebg", {
  method: "POST",
  headers: { "X-Api-Key": process.env.REMOVEBG_KEY },
  body: form,
});
if (!res.ok) throw new Error(`${res.status}: ${res.statusText}`);
fs.writeFileSync("no-bg.png", Buffer.from(await res.arrayBuffer()));

API4AI:

import fs from "node:fs";

const form = new FormData();
form.append("image", await fs.openAsBlob("car.jpg"), "car.jpg");

const res = await fetch("https://api4ai.cloud/img-bg-removal/v1/results", {
  method: "POST",
  headers: { "X-API-KEY": process.env.API4AI_KEY },
  body: form,
});
if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);

const result = (await res.json()).results[0];
if (result.status.code !== "ok") throw new Error(result.status.message);
const image = result.entities.find((e) => e.kind === "image");
fs.writeFileSync("no-bg.png", Buffer.from(image.image, "base64"));

The one line not to skip

When our service can't process a photo (it's corrupted, isn't really a JPEG or PNG, or is bigger than 4096×4096), it still answers HTTP 200. The JSON says "failure" and gives the reason, for example "Resolution is too big: 6000x4000. Max allowed resolution: 4096x4096."

remove.bg code usually checks only the HTTP status, because that's how remove.bg reports errors. Port that check as it is and a failed photo looks like a success that wrote nothing. Every sample above checks status.code; keep that line when you paste them into your code.

A stand-in for remove_bg()

If remove.bg calls are spread across your code, it's easier to replace the function than every call. This one takes the main remove.bg arguments, returns image bytes like remove.bg's response body, and does crop, bg_color and JPG/WebP output locally with Pillow. Anything it can't do raises an error that names the argument, so nothing is silently dropped.

"""A stand-in for the remove.bg call, on the API4AI Background Removal API.

    pip install requests pillow
    export API4AI_KEY=...            # from portal.api4.ai

Your code keeps calling remove_bg(...) with the main remove.bg arguments and
gets image bytes back. Anything it can't do raises an error with the name of
the argument, instead of being silently ignored.
"""
import base64
import io
import os
import re
import time

import requests
from PIL import Image, ImageColor

URL = "https://api4ai.cloud/img-bg-removal/v1/results"


class RemoveBgError(Exception):
    pass


def _call(image_file, image_url, tries=4):
    headers = {"X-API-KEY": os.environ["API4AI_KEY"]}
    for attempt in range(tries):
        if image_file:
            with open(image_file, "rb") as f:
                r = requests.post(URL, headers=headers, files={"image": f}, timeout=120)
        else:   # a link goes in as a multipart field too
            r = requests.post(URL, headers=headers, files={"url": (None, image_url)}, timeout=120)
        if r.status_code in (429, 500, 502, 503, 504) and attempt < tries - 1:
            time.sleep(2 ** attempt)                          # 1, 2, 4 s
            continue
        if r.status_code != 200:
            raise RemoveBgError(f"HTTP {r.status_code}: {r.text[:200]}")
        result = r.json()["results"][0]
        # A photo the service can't process still comes back as HTTP 200.
        if result["status"]["code"] != "ok":
            raise RemoveBgError(result["status"]["message"])
        image = next(e for e in result["entities"] if e["kind"] == "image")
        return Image.open(io.BytesIO(base64.b64decode(image["image"])))


def remove_bg(image_file=None, image_url=None, size="auto", format="png",
              bg_color=None, crop=False, **other):
    """Returns the cut-out as bytes, like the body of a remove.bg response."""
    if other:
        raise RemoveBgError("not supported: " + ", ".join(sorted(other)))
    if size not in ("auto", "full"):
        raise RemoveBgError(f"size={size!r}: results come back at full size")
    if bool(image_file) == bool(image_url):
        raise RemoveBgError("pass image_file or image_url")
    if format.lower() not in ("png", "jpg", "webp"):
        raise RemoveBgError(f"format={format!r}: use png, jpg or webp")

    png = _call(image_file, image_url)            # RGBA, background transparent
    if crop:
        png = png.crop(png.getchannel("A").getbbox())
    if bg_color or format.lower() == "jpg":       # JPG has no transparency
        color = bg_color or "ffffff"
        if re.fullmatch(r"[0-9a-fA-F]{6}", color):
            color = "#" + color
        flat = Image.new("RGBA", png.size, ImageColor.getrgb(color))
        png = Image.alpha_composite(flat, png)

    out = io.BytesIO()
    if format.lower() == "jpg":
        png.convert("RGB").save(out, "JPEG", quality=92)
    else:
        png.save(out, format.upper())
    return out.getvalue()


if __name__ == "__main__":
    import sys
    with open("no-bg.png", "wb") as f:
        f.write(remove_bg(image_file=sys.argv[1]))

Use it the way you used remove.bg:

from removebg_adapter import remove_bg, RemoveBgError

png = remove_bg(image_file="car.jpg", size="auto")
jpg = remove_bg(image_url="https://example.com/shoe.jpg", bg_color="ffffff", crop=True, format="jpg")

Three things it decides for you, which you may want to change:

size accepts auto and full only. Our results come back at the size of the input, so the smaller, cheaper remove.bg sizes have no match; the function says so rather than returning a full-size image you didn't ask for.
JPG without bg_color gets a white background, because JPG can't be transparent.
Retries: a 429 or a 5xx waits 1, 2, then 4 seconds. If you call it from many threads at once, keep an eye on 429s.

No-code: Zapier, Make and n8n

If a no-code flow has a remove.bg step, you don't need a new app or template to replace it. Swap that step for the tool's plain HTTP request (Webhooks by Zapier, Make's HTTP module, n8n's HTTP Request node): POST to https://api4ai.cloud/img-bg-removal/v1/results, an X-API-KEY header with your key, and a multipart form field url with a public link to the photo (or image with the file). The cut-out comes back as base64 in results[0].entities[0].image. In n8n, the Convert to File node turns it into a file; in Make, the toBinary() function does; in Zapier you'll need a short Code step.

Before Dec 1

Put five of your hardest photos through the demo: glass, hair, white on white.
Get a key on the API4AI developer portal. No credit card, $5 of free credit, pay as you go after that at $5 per 1,000 images, and the balance never expires.
Swap the call or drop in the adapter, and run a day's photos through both before your remove.bg credits run out.

The full reference is in the docs, and the price table with the sources is on our moving from remove.bg page.

Which remove.bg parameter would you miss most if it went away?

OCR a Folder of Receipts and Invoices in Python, and Flag the Pages to Check

Oleg Tagobitsky — Tue, 20 Oct 2026 13:01:19 +0000

Typing receipts and invoices into a spreadsheet is the kind of job everyone agrees should be automated, and then it isn't, because "automated" has to include knowing which pages came out wrong.

This tutorial builds a small tool around the API4AI OCR API. It reads a whole folder of scans and photos (JPEG, PNG and multi-page PDF), saves the text with the original line structure, keeps every word's position in a CSV, and writes a report that tells a person which pages to open. It's about 150 lines of Python, and the only dependency is requests.

One request

curl -X POST "https://api4ai.cloud/ocr/v1/results?algo=simple-words" \
     -H "X-API-KEY: $API4AI_KEY" \
     -F "image=@receipt.jpg"

The file goes in as multipart form data: in image, or a public link in url. JPEG, PNG or PDF, under 16 MB, at most 4096×4096.

algo picks the mode. The default, simple-text, returns the whole page as one block of text. simple-words returns every word with its own box, and that's the one this script uses. The reason is in the next section.

What comes back

Here's the docs example, a handwritten envelope, in simple-words mode (trimmed to three of its nine words):

{
  "results": [
    {
      "status": { "code": "ok", "message": "Success" },
      "name": "text.jpg",
      "width": 1500,
      "height": 1000,
      "entities": [
        {
          "kind": "objects",
          "name": "words",
          "objects": [
            { "box": [0.2073, 0.301, 0.1187, 0.077],
              "entities": [{ "kind": "text", "name": "text", "text": "Jane" }] },
            { "box": [0.22, 0.453, 0.094, 0.044],
              "entities": [{ "kind": "text", "name": "text", "text": "1095" }] },
            { "box": [0.3793, 0.43, 0.0947, 0.061],
              "entities": [{ "kind": "text", "name": "text", "text": "Main" }] }
          ]
        }
      ]
    }
  ]
}

Each box is [x, y, width, height], as fractions of the image size. For a PDF, results has one entry per page, each with a page number.

Three things the docs tell you that change the code

1. Failures come back as HTTP 200. A file the service can't read (corrupted, not really an image, too large) doesn't raise an HTTP error. It returns 200, with "failure" in status.code and the reason in status.message:

{ "status": { "code": "failure", "message": "Can not load image." },
  "name": "file.txt", "entities": [] }

If you only check the HTTP code, those files silently drop out of your results. The script checks status.code for every page.

2. There's no confidence score. You can't filter on "below 80%". So the script checks the text itself: is the page empty, does it have fewer words than a real document would, and does it contain the things this kind of document always has. For receipts and invoices that's an amount and a date.

3. A PDF is billed per page. Each page is converted to an image and read separately. A 12-page contract is 12 requests. The script counts pages, so the summary line tells you what the run cost.

Rebuilding the lines

We photographed a test receipt (a made-up café, lying slightly crooked on a table) and sent it to the API in both modes. All 51 words came back right. Here's the end of the simple-text block:

1 x Banana bread
3.50
Subtotal
VAT 20% incl.
TOTAL
Card
16.50
2.75
16.50
16.50
Thank you, see you soon!

The labels and the amounts at the bottom came back as two separate runs. Which 16.50 is the total? The text alone doesn't say.

With simple-words you get every word's box, so you can rebuild the lines yourself. The obvious rule is to sort words by their vertical centre and start a new line when the centre jumps by more than half a word's height. On this receipt that rule fails too: the photo is tilted by a couple of degrees, so each amount on the right sits slightly higher than its label on the left, and "TOTAL" and "16.50" land on different lines.

The fix is to measure the tilt first. Neighbouring words on the same line give you a slope; take the median, subtract it, and then group:

def to_lines(words):
    """Rebuild reading order from word boxes, allowing for a slightly tilted photo."""
    mid = lambda w: w[2] + w[4] / 2                      # vertical centre
    # Tilt: how far the centre moves per unit of x between neighbouring words.
    slopes = [(mid(b) - mid(a)) / (b[1] - a[1]) for a in words for b in words
              if 0 < b[1] - (a[1] + a[3]) < 2 * a[4] and abs(mid(b) - mid(a)) < 0.5 * a[4]]
    tilt = statistics.median(slopes) if slopes else 0.0
    level = lambda w: mid(w) - tilt * w[1]
    ...

On the receipt, that gives:

Date 16/10/2026 08:42
Receipt No. 004471
2 x Flat white 7.00
1 x Croissant 2.80
1 x Orange juice 3.20
1 x Banana bread 3.50
Subtotal 16.50
VAT 20% incl. 2.75
TOTAL 16.50
Card 16.50

It's still a simple rule. A label photographed strongly from the side, where the tilt changes across the page, breaks it: on our angled jar label it split "Wildflower Honey" over two lines. That's one more reason the report exists.

The checks

These live at the top of the script, so you can change them per document type:

MIN_WORDS = 5
EXPECT = {
    "amount": r"\d[\d,]*[.,]\d{2}\b",                       # 12.50, 1,204.00
    "date": r"\b\d{1,2}[./-]\d{1,2}[./-]\d{2,4}\b|\b\d{4}-\d{2}-\d{2}\b",
}

A page gets a flag when it has no text, fewer than MIN_WORDS words, or no match for one of the EXPECT patterns. For delivery notes you might expect an order number instead; for shipping labels, a postcode. Thresholds and patterns here are a starting point, not a tuned set.

The whole script

"""OCR a folder of scans and photos, and flag the pages a person should check.

    pip install requests
    export API4AI_KEY=...            # from portal.api4.ai
    python3 ocr_folder.py scans/ text/

For every file you get text/<same path>.txt (pages separated by a form feed),
plus text/words.csv (every word with its box) and text/report.csv (one row per
page: status, word count, and the reasons to look at it).
"""
import csv
import os
import pathlib
import re
import statistics
import sys
import time
from concurrent.futures import ThreadPoolExecutor

import requests

URL = "https://api4ai.cloud/ocr/v1/results?algo=simple-words"
KEY = os.environ["API4AI_KEY"]
FILES = {".jpg", ".jpeg", ".png", ".pdf"}

# What a normal page should contain. Edit these for your own documents.
MIN_WORDS = 5
EXPECT = {
    "amount": r"\d[\d,]*[.,]\d{2}\b",                       # 12.50, 1,204.00
    "date": r"\b\d{1,2}[./-]\d{1,2}[./-]\d{2,4}\b|\b\d{4}-\d{2}-\d{2}\b",
}

src, dst = pathlib.Path(sys.argv[1]), pathlib.Path(sys.argv[2])


def call_api(path, tries=4):
    for attempt in range(tries):
        with path.open("rb") as f:
            r = requests.post(URL, headers={"X-API-KEY": KEY},
                              files={"image": f}, timeout=300)
        if r.status_code in (429, 500, 502, 503, 504) and attempt < tries - 1:
            time.sleep(2 ** attempt)                          # 1, 2, 4 s
            continue
        r.raise_for_status()
        return r.json()["results"]          # one result per page for a PDF


def words_of(page):
    """[(text, x, y, w, h), ...] from one page of the response."""
    out = []
    for entity in page.get("entities", []):
        for obj in entity.get("objects", []):
            text = " ".join(e["text"] for e in obj["entities"] if e["kind"] == "text")
            out.append((text, *obj["box"]))
    return out


def to_lines(words):
    """Rebuild reading order from word boxes, allowing for a slightly tilted photo."""
    mid = lambda w: w[2] + w[4] / 2                      # vertical centre
    # Tilt: how far the centre moves per unit of x between neighbouring words.
    slopes = [(mid(b) - mid(a)) / (b[1] - a[1]) for a in words for b in words
              if 0 < b[1] - (a[1] + a[3]) < 2 * a[4] and abs(mid(b) - mid(a)) < 0.5 * a[4]]
    tilt = statistics.median(slopes) if slopes else 0.0
    level = lambda w: mid(w) - tilt * w[1]
    lines = []
    for w in sorted(words, key=level):                   # same level = same line
        if lines and abs(level(w) - lines[-1][0]) < 0.5 * w[4]:
            lines[-1][1].append(w)
        else:
            lines.append([level(w), [w]])
    text = []
    for _, ws in lines:
        line = ""
        for t, *_ in sorted(ws, key=lambda w: w[1]):      # left to right
            glue = t in ",.;:!?%)" or (line[-1:] == ":" and line[-2:-1].isdigit())
            line += t if not line or glue else " " + t
        text.append(line)
    return "\n".join(text)


def checks(words, text):
    flags = []
    if not words:
        return ["no text"]
    if len(words) < MIN_WORDS:
        flags.append("few words")
    for name, pattern in EXPECT.items():
        if not re.search(pattern, text):
            flags.append("no " + name)
    return flags


def ocr(path):
    rel = path.relative_to(src)
    out = dst / rel.with_suffix(rel.suffix + ".txt")
    if out.exists():
        return rel, None
    rows, texts = [], []
    for n, page in enumerate(call_api(path), start=1):
        number = page.get("page", n)
        # A file the service can't read still comes back as HTTP 200.
        if page["status"]["code"] != "ok":
            rows.append((rel, number, "failed: " + page["status"]["message"], [], []))
            continue
        words = words_of(page)
        text = to_lines(words)
        texts.append(text)
        rows.append((rel, number, "ok", words, checks(words, text)))
    if texts:                                # nothing written means retry next run
        out.parent.mkdir(parents=True, exist_ok=True)
        out.write_text("\f".join(texts), encoding="utf-8")
    return rel, rows


files = sorted(p for p in src.rglob("*") if p.suffix.lower() in FILES)
dst.mkdir(parents=True, exist_ok=True)
pages = failed = flagged = skipped = 0


def open_csv(name, header):
    f = open(dst / name, "a", newline="", encoding="utf-8")
    w = csv.writer(f)
    if f.tell() == 0:
        w.writerow(header)
    return f, w


fr, report = open_csv("report.csv", ["file", "page", "status", "words", "flags"])
fw, wordlist = open_csv("words.csv", ["file", "page", "word", "x", "y", "w", "h"])
with ThreadPoolExecutor(max_workers=4) as pool, fr, fw:
    for rel, rows in pool.map(ocr, files):
        if rows is None:
            skipped += 1
            continue
        for rel, number, status, words, flags in rows:
            pages += 1
            failed += status != "ok"
            flagged += bool(flags)
            report.writerow([rel, number, status, len(words), "; ".join(flags)])
            wordlist.writerows([rel, number, t, *(round(v, 4) for v in box)]
                               for t, *box in words)
            mark = "CHECK " if flags or status != "ok" else "      "
            print(f"{mark}{rel} p{number}: {status}, {len(words)} words {'; '.join(flags)}")

print(f"\n{len(files)} files: {skipped} already done. {pages} pages read "
      f"(each page is billed), {failed} failed, {flagged} flagged for a person")

Run it:

pip install requests
export API4AI_KEY=...
python3 ocr_folder.py scans/ text/

What you get in text/:

test-receipt.jpg.txt for every file: the rebuilt text, pages separated by a form feed. The original extension stays in the name, so invoice.pdf and invoice.jpg can't overwrite each other.
words.csv: one row per word with its page and box, for anything that needs positions later.
report.csv: one row per page.

file,page,status,words,flags
test-receipt.jpg,1,ok,51,
invoice-77.pdf,1,ok,214,
invoice-77.pdf,2,ok,4,few words; no amount; no date
photo-blurry.jpg,1,ok,0,no text
broken.png,1,failed: Can not load image.,0,

(The first row is the test receipt above; the others are examples.) Only the last three need a person.

What else it takes care of:

Originals are never touched. Output goes to a separate folder with the same structure.
Resume. A file with a .txt already in place is skipped, so after a crash or Ctrl-C you run the same command again. Files that failed have no .txt, so they're retried.
Rate limits. A 429 or a 5xx waits 1, 2, then 4 seconds before giving up.
Count pages. The last line says how many pages were read, failed and flagged. Pages, not files, are what you pay for.

Four workers is a starting point. PDFs take longer than single images, so if you see timeouts, lower it before raising the timeout.

What it costs

On the API4AI developer portal the OCR API is pay-as-you-go at $5 per 1,000 requests, with no subscription. One image is one request; a PDF counts per page. New accounts start with $5 of credit, about 1,000 pages. For large volumes, ask for a quote at hello@api4.ai.

Before you write code

Put your worst pages through the demo on the OCR API page first: the faded thermal receipt, the handwritten form, the photo taken at an angle. It takes any JPEG or PNG and shows every word it found. The full reference is in the docs. There's also a separate VIN endpoint that applies VIN rules and returns suggestions, if that's your use case. The less technical version of this post, covering receipts, forms, labels and VINs, is on our blog.

What does your pipeline do with a page it can't read: retry, skip, or send it to a person?

Batch Background Removal in Python, With a Quality Check

Oleg Tagobitsky — Tue, 13 Oct 2026 14:03:08 +0000

Removing the background from one photo is a solved problem. Removing it from a folder of 500 every day, and knowing which of the 500 came out wrong, is the part that takes engineering.

This tutorial builds a small batch tool around the API4AI Background Removal API. It cuts out a whole folder of product photos, writes transparent PNGs next to nothing it shouldn't touch, and produces a report that tells a person which handful of results to open. It's about 100 lines of Python with requests and Pillow.

One request

curl -X POST "https://api4ai.cloud/img-bg-removal/v1/results" \
     -H "X-API-KEY: $API4AI_KEY" \
     -F "image=@shoes.jpg"

The photo goes in as multipart form data: a file in image, or a public link in url. JPEG or PNG, under 16 MB, at most 4096×4096. For photos of people there's a separate People Background Removal API, tuned for them.

Two options worth knowing:

?mode=fg-mask returns a black-and-white mask instead of the cut-out, if you'd rather apply the cut yourself.
An image-bg (or url-bg) field puts your own background behind the object in the same request.

What comes back

The result is JSON, and the cut-out is inside it as base64:

{
  "results": [
    {
      "status": { "code": "ok", "message": "Success" },
      "name": "shoes.jpg",
      "width": 1500,
      "height": 1000,
      "entities": [
        { "kind": "image", "name": "general-fg-image",
          "format": "PNG", "image": "iVBORw0KGgo..." },
        { "kind": "objects", "name": "objects", "objects": [] }
      ]
    }
  ]
}

The image entity is a 4-channel PNG: the object keeps its original pixels, the background is transparent, and pixels along the edge can be partly transparent.

The lesson from the HTTP 200

The single most useful line in this script is the one that checks status.code.

When the service can't process a photo, because it's corrupted, isn't really a JPEG, or is bigger than 4096×4096, it still answers HTTP 200. The JSON says "failure" and gives the reason:

{ "status": { "code": "failure",
              "message": "Resolution is too big: 6000x4000. Max allowed resolution: 4096x4096." } }

Code that only checks raise_for_status() treats that as a success, writes nothing, and moves on. Run that over 500 photos and you lose a few without a trace. In a batch tool, every failure has to end up in the report with its reason, and the counts at the end have to add up.

Flagging the results a person should see

The API returns a cut-out, not a verdict on it. But the alpha channel of that cut-out tells you a lot, and it costs nothing to read. The script checks four things:

Almost nothing kept (under 3% of the frame): the model probably didn't find the subject you expected.
Almost nothing removed (over 90%): the background may have been kept.
The subject touches the edge of the frame: the product was cropped in the photo, or part of the background survived.
Lots of soft edges (semi-transparent pixels over 15% of the object): normal around hair, a warning sign for glass, lace, smoke or blur.

None of these say a result is wrong. They say it's worth a look. The thresholds are a starting point: run a day's photos, look at what gets flagged and what doesn't, and move them.

The script

"""Cut out a folder of photos and flag the ones a person should check.

    pip install requests pillow
    export API4AI_KEY=...            # from portal.api4.ai
    python3 bulk_cutout.py photos/ cutouts/

Originals are never touched. Each result is a transparent PNG at the same relative
path under cutouts/, and cutouts/report.csv says which ones to look at and why.
"""
import base64
import csv
import io
import os
import pathlib
import sys
import time
from concurrent.futures import ThreadPoolExecutor

import requests
from PIL import Image

URL = "https://api4ai.cloud/img-bg-removal/v1/results"
KEY = os.environ["API4AI_KEY"]
PHOTOS = {".jpg", ".jpeg", ".png"}
src, dst = pathlib.Path(sys.argv[1]), pathlib.Path(sys.argv[2])


def call_api(photo, tries=4):
    for attempt in range(tries):
        with photo.open("rb") as f:
            r = requests.post(URL, headers={"X-API-KEY": KEY},
                              files={"image": f}, timeout=120)
        if r.status_code in (429, 500, 502, 503, 504) and attempt < tries - 1:
            time.sleep(2 ** attempt)                          # 1, 2, 4 s
            continue
        r.raise_for_status()
        return r.json()["results"][0]


def checks(png):
    """Cheap signals from the alpha channel. Thresholds are a starting point."""
    alpha = png.getchannel("A")
    w, h = alpha.size
    hist = alpha.histogram()
    total, solid = w * h, sum(hist[128:])
    soft = sum(hist[1:255])
    border = [alpha.getpixel((x, y)) for x in range(w) for y in (0, h - 1)]
    border += [alpha.getpixel((x, y)) for y in range(h) for x in (0, w - 1)]
    flags = []
    if solid < 0.03 * total:
        flags.append("almost nothing kept")
    if solid > 0.90 * total:
        flags.append("almost nothing removed")
    if max(border) > 128:
        flags.append("touches the edge")
    if soft > 0.15 * max(solid, 1):
        flags.append("lots of soft edges")
    return solid / total, flags


def cutout(photo):
    rel = photo.relative_to(src)
    out = dst / rel.with_suffix(".png")
    if out.exists():
        return rel, "skipped", None, []
    result = call_api(photo)
    # A photo the service can't read comes back as HTTP 200 with "failure".
    if result["status"]["code"] != "ok":
        return rel, "failed: " + result["status"]["message"], None, []
    image = next(e for e in result["entities"] if e["kind"] == "image")
    png = Image.open(io.BytesIO(base64.b64decode(image["image"])))
    out.parent.mkdir(parents=True, exist_ok=True)
    png.save(out)
    share, flags = checks(png)
    return rel, "ok", share, flags


photos = sorted(p for p in src.rglob("*") if p.suffix.lower() in PHOTOS)
dst.mkdir(parents=True, exist_ok=True)
counts = {"ok": 0, "skipped": 0, "failed": 0, "to check": 0}

with ThreadPoolExecutor(max_workers=8) as pool, \
        open(dst / "report.csv", "a", newline="") as f:
    writer = csv.writer(f)
    if f.tell() == 0:
        writer.writerow(["file", "status", "foreground", "flags"])
    for rel, status, share, flags in pool.map(cutout, photos):
        counts[status.split(":")[0]] += 1
        if status == "skipped":
            continue
        counts["to check"] += bool(flags)
        writer.writerow([rel, status, f"{share:.2f}" if share is not None else "",
                         "; ".join(flags)])
        print(f"{status:>7}  {'CHECK ' if flags else '      '}{rel}")

print(f"\n{len(photos)} photos in: {counts['ok']} cut out, "
      f"{counts['skipped']} already done, {counts['failed']} failed; "
      f"{counts['to check']} flagged for a person")

Run it:

pip install requests pillow
export API4AI_KEY=...
python3 bulk_cutout.py photos/ cutouts/

The report, cutouts/report.csv:

file,status,foreground,flags
shoes-01.jpg,ok,0.31,
shoes-02.jpg,ok,0.62,touches the edge
model-07.jpg,ok,0.44,lots of soft edges
broken.jpg,failed: Can not load image.,,

What it takes care of:

Originals are never touched. Results go to a separate folder with the same structure: photos/2026-10/shoes.jpg becomes cutouts/2026-10/shoes.png.
Resume. A photo with a result already in place is skipped, so after a crash or Ctrl-C you run the same command again. Failed photos have no result, so they're retried.
Rate limits. A 429 or a 5xx waits 1, 2, then 4 seconds before giving up.
Count in vs out. The last line adds up cut out, already done and failed. If that doesn't match the number of photos, you know before anyone else does.

Eight workers is a starting point, not a tuned number. If you see a lot of 429s, lower it.

What it costs

On the API4AI developer portal the Background Removal API is pay-as-you-go at $5 per 1,000 images, with no subscription; people photos are $15 per 1,000 and cars $30. At 500 product photos a day, about 15,000 a month, that's around $75. Above a few thousand a day, ask for a volume quote at hello@api4.ai.

Before you write code

Put your hardest photos through the demo on the Background Removal page first: the white shirt on white, the glass bottle, the curly hair. It takes any JPEG or PNG. The full reference is in the docs, and the less technical version of this post, about where automation fits in an editing workflow, is on our blog.

What does your batch flag most often: edges, glass, or files that never come back?

Tag a Clothing Catalog in Python: From a Folder of Photos to a CSV

Oleg Tagobitsky — Tue, 06 Oct 2026 09:47:08 +0000

A clothing catalog is mostly photos, and the photos rarely come with good labels. A seller writes "nice outfit". A supplier sends a folder called new_final_2. Somebody then has to look at each picture and type "scarf".

This walkthrough turns that folder into a CSV: one row for every garment and accessory found, with the item type, a confidence score and a bounding box. It uses the API4AI Fashion API, about 80 lines of Python, and no ML setup.

At the end there's a short second script that does the part people skip: deciding which tags to trust and which photos a person should still look at.

One request

curl -X POST "https://api4ai.cloud/fashion/v2/results" \
     -H "X-API-KEY: $API4AI_KEY" \
     -F "image=@outfit.jpg"

The photo goes in as multipart form data: a file in image, or a public link in url. JPEG or PNG, under 16 MB.

What comes back

This is the example from the docs:

{
  "results": [
    {
      "status": { "code": "ok", "message": "Success" },
      "name": "scarf.jpg",
      "md5": "a447c0aa2b2b89aa6ffb488317c0ab1e",
      "width": 1024,
      "height": 768,
      "entities": [
        {
          "kind": "objects",
          "name": "fashion",
          "objects": [
            {
              "box": [0.2627, 0.0462, 0.6867, 0.6496],
              "entities": [
                {
                  "kind": "classes",
                  "name": "classes",
                  "classes": { "scarf": 0.6910 }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Every detected item is one entry in objects:

box is [x, y, width, height] in normalized coordinates, 0 to 1 from the top-left corner. Multiply by the image width and height to get pixels.
classes maps a class name to a confidence between 0 and 1.

Look at the confidence in the docs' own example: 0.69. The scarf was found, but not with certainty. That number is what the second half of this post is about.

One more thing to be clear on: you get the item type and its position. Not color, not material, not size, not brand.

Three things that catch people

A photo the service can't read still returns HTTP 200. status.code is "failure" and status.message says why (wrong file type, corrupted image, a URL that can't be downloaded). If you only call raise_for_status(), those photos vanish from your catalog without a trace.
An outfit photo returns everything in it. A model wearing a shirt, a sweater and a belt gives you three items, and maybe only one is for sale. The boxes help: the item that fills most of the frame is usually the product.
Zero items is a valid answer. A photo with no detections comes back as "ok" with an empty list. Log it, or you can't tell "nothing found" from "never processed".

The script

It walks the folder (subfolders included), sends each photo, and appends rows to a CSV as it goes.

"""Tag a folder of clothing photos with the API4AI Fashion API and write a CSV.

    export API4AI_KEY=...            # from portal.api4.ai
    python3 tag_catalog.py photos/ tags.csv

One row per detected item (or one row per photo with nothing found, or failed).
Run it again after a crash: photos already tagged are skipped, failed ones retried.
"""
import csv
import os
import pathlib
import sys
import time

import requests

URL = "https://api4ai.cloud/fashion/v2/results"
KEY = os.environ["API4AI_KEY"]
PHOTOS = {".jpg", ".jpeg", ".png"}
src, out = pathlib.Path(sys.argv[1]), pathlib.Path(sys.argv[2])


def call_api(photo, tries=4):
    for attempt in range(tries):
        with photo.open("rb") as f:
            r = requests.post(URL, headers={"X-API-KEY": KEY},
                              files={"image": f}, timeout=120)
        if r.status_code in (429, 500, 502, 503, 504) and attempt < tries - 1:
            time.sleep(2 ** attempt)                    # 1, 2, 4 s
            continue
        r.raise_for_status()
        return r.json()["results"][0]


def items(result):
    """Yield (class name, confidence, box) for every detected item."""
    for entity in result["entities"]:
        if entity["kind"] != "objects":
            continue
        for obj in entity["objects"]:
            classes = obj["entities"][0]["classes"]
            name = max(classes, key=classes.get)
            yield name, classes[name], obj["box"]


done = set()
if out.exists():
    with out.open(newline="") as f:
        done = {row["file"] for row in csv.DictReader(f) if row["status"] == "ok"}

photos = sorted(p for p in src.rglob("*") if p.suffix.lower() in PHOTOS)
counts = {"ok": 0, "skipped": 0, "failed": 0}

with out.open("a", newline="") as f:
    writer = csv.writer(f)
    if out.stat().st_size == 0:
        writer.writerow(["file", "status", "item", "confidence", "x", "y", "w", "h"])
    for photo in photos:
        rel = str(photo.relative_to(src))
        if rel in done:
            counts["skipped"] += 1
            continue
        result = call_api(photo)
        # A photo the service can't read comes back as HTTP 200 with "failure".
        if result["status"]["code"] != "ok":
            counts["failed"] += 1
            writer.writerow([rel, "failed: " + result["status"]["message"]])
            continue
        counts["ok"] += 1
        found = list(items(result))
        if not found:
            writer.writerow([rel, "ok", "", "", "", "", "", ""])
        for name, confidence, box in found:
            writer.writerow([rel, "ok", name, f"{confidence:.2f}",
                             *(f"{v:.3f}" for v in box)])
        f.flush()
        print(f"{len(found)} item(s)  {rel}")

print(f"\n{len(photos)} photos: {counts['ok']} tagged, "
      f"{counts['skipped']} already done, {counts['failed']} failed")

Run it:

pip install requests
export API4AI_KEY=...
python3 tag_catalog.py photos/ tags.csv

And the CSV looks like this:

file,status,item,confidence,x,y,w,h
look-01.jpg,ok,scarf,0.99,0.262,0.253,0.115,0.401
look-01.jpg,ok,belt,0.72,0.268,0.577,0.118,0.150
broken.jpg,failed: Can not load image.
flatlay-07.jpg,ok,,,,,,

What it takes care of:

Resume. Photos that are already tagged are skipped, so after a crash or Ctrl-C you run the same command again. Failed photos are tried again; the old "failed" row stays in the file as a log.
Rate limits and hiccups. A 429 or a 5xx waits 1, 2, then 4 seconds before giving up.
Failures you can see. Anything that comes back as "failure" gets a row with the reason.
Empty photos. A photo with nothing found gets a row with an empty item.
The count at the end. Tagged plus already-done plus failed should equal the number of photos.

It sends one photo at a time, which keeps the code short. For a large folder, wrap call_api in a ThreadPoolExecutor and lower the worker count if you start seeing 429s.

The part that matters: which tags to trust

A CSV of detections isn't a catalog yet. Between them sits one decision about confidence:

import csv
from collections import Counter

AUTO, REVIEW = 0.90, 0.60          # your thresholds, not ours

rows = list(csv.DictReader(open("tags.csv")))
items = [r for r in rows if r["status"] == "ok" and r["item"]]

auto   = [r for r in items if float(r["confidence"]) >= AUTO]
review = [r for r in items if REVIEW <= float(r["confidence"]) < AUTO]

print(f"{len(auto)} tags to write automatically, {len(review)} for a person")
print("Catalog by item type:", Counter(r["item"] for r in auto).most_common())

empty  = sorted({r["file"] for r in rows if r["status"] == "ok" and not r["item"]})
tagged = {r["file"] for r in rows if r["status"] == "ok"}
failed = sorted({r["file"] for r in rows if r["status"].startswith("failed")} - tagged)
print(f"{len(empty)} photos with nothing found, {len(failed)} failed")

Above the first threshold, write the tag. Between the two, show the photo to a person with the tag already suggested. Below, ignore it.

The 0.90 and 0.60 here are placeholders. Flat-lay shots on white behave differently from crowded street photos, so run a few hundred of your own images, look at what lands in each band, and move the numbers. Because the raw scores are in the CSV, changing a threshold later costs nothing: you don't call the API again.

Two more uses of the same file:

Map names once. The API says "trousers"; your shop may say "pants". Keep a small dictionary in your code, not in the data.
Crop for visual search. x * width, y * height and so on give you a pixel box for each item, ready to cut out and index.

What it costs

On the API4AI developer portal the Fashion API is pay-as-you-go, with a list price of $300 per 1,000 requests and no subscription. One photo is one request.

That price is for small and occasional use. For a real catalog, ask for a quote: it depends on how many images you process, their resolution and how many items a typical photo contains, and at volume the discount is significant. Write to hello@api4.ai with a rough monthly number and a few sample photos.

Try it before you write any code

The Fashion API page has a demo that takes your own JPEG or PNG and draws the boxes with their scores. If the results look right on your kind of photo, a key on the portal takes a minute and needs no credit card. The full reference is in the docs, and the less technical version of this post, with the use cases, is on our blog.

How are you tagging product photos today: by hand, from the supplier feed, or with a model of your own?

Blurring license plates in 10,000 photos with Python — and knowing which ones to check

Oleg Tagobitsky — Tue, 29 Sep 2026 10:02:09 +0000

Blurring a license plate is one line of OpenCV. Knowing where the plate is — in 10,000 photos, at every angle, on every kind of car — is the actual job. And once it's done, the question nobody plans for arrives: which of those 10,000 should a person actually look at before they go public?

This walkthrough covers both. It uses the API4AI Image Anonymization API, which finds and blurs plates (and faces, if you want) and leaves the rest of the photo untouched. The script at the end runs a whole folder, keeps the folder structure, survives rate limits and failures, and writes a CSV of every plate it hid — which turns out to be the most useful part.

It's for archives, rental fleets, marketplace uploads, street photography, datasets: anywhere the scene has to stay and only the plate has to go. If you're a car dealer who wants the background replaced as well, skip to the end — there's a no-code route for that.

One request

curl -X POST "https://api4ai.cloud/img-anonymization/v1/results?mode=hide-clp" \
     -H "X-API-KEY: $API4AI_KEY" \
     -F "image=@car.jpg"

mode=hide-clp means "hide car license plates". The other mode is hide-face. Leave mode out entirely and the API hides everything it supports — plates and faces, which is worth knowing before you run a folder of photos where faces should stay. Repeat the parameter to be explicit about both: ?mode=hide-clp&mode=hide-face.

The photo goes in as multipart form data: a file in image, or a public link in url.

What comes back

This is the example from the docs, trimmed:

{
  "results": [
    {
      "status": { "code": "ok", "message": "Success" },
      "name": "car.jpg",
      "width": 1024,
      "height": 768,
      "entities": [
        {
          "kind": "image",
          "name": "anonymized-image",
          "format": "PNG",
          "image": "iVBORw0KGgoAAAA...YII="
        },
        {
          "kind": "objects",
          "name": "hidden-objects",
          "objects": [
            {
              "box": [0.7458, 0.6651, 0.1189, 0.0745],
              "entities": [
                {
                  "kind": "classes",
                  "name": "classes",
                  "classes": { "License plate": 0.5641 }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Two entities:

image — the anonymized photo, base64-encoded, in format (the docs say it's usually the same as the input format, so a JPEG in usually comes back as a JPEG).
objects — every object that was hidden, with a bounding box in normalized [x, y, width, height] coordinates and a confidence between 0 and 1.

Look at that confidence in the docs' own example: 0.56. The plate was found and blurred, but the model wasn't sure about it. Hold on to that — it's what makes the review step at the end work.

Four things that catch people

A photo the service can't read still returns HTTP 200. status.code is "failure" and status.message says why. If you only call raise_for_status(), those files silently vanish from your output folder.
Pick entities by kind, not by position. Code that reads entities[0] works until it doesn't.
Limits: JPEG, PNG or PDF, under 16 MB, at most 4096×4096. A PDF is split into pages and each page is processed separately, so results can hold more than one entry.
Faces are included by default. Say mode=hide-clp when you mean plates only.

The script

Eighty-odd lines, standard library plus requests. It walks the source folder recursively, sends eight photos at a time, writes each result to the same relative path under the output folder, and logs every hidden plate to plates.csv.

"""Blur license plates in a folder of photos, keep the scene, log what was hidden.

    export API4AI_KEY=...            # from portal.api4.ai
    python3 blur_plates.py photos/ blurred/

Writes each result under blurred/ with the same relative path, and a
blurred/plates.csv with one row per hidden plate (or per photo with none).
"""
import base64
import csv
import os
import pathlib
import sys
import time
from concurrent.futures import ThreadPoolExecutor

import requests

URL = "https://api4ai.cloud/img-anonymization/v1/results"
KEY = os.environ["API4AI_KEY"]
PHOTOS = {".jpg", ".jpeg", ".png"}
EXT = {"JPEG": ".jpg", "PNG": ".png"}
src, dst = pathlib.Path(sys.argv[1]), pathlib.Path(sys.argv[2])


def call_api(photo, tries=4):
    for attempt in range(tries):
        with photo.open("rb") as f:
            r = requests.post(URL, params={"mode": "hide-clp"},   # plates only
                              headers={"X-API-KEY": KEY},
                              files={"image": f}, timeout=120)
        if r.status_code in (429, 500, 502, 503, 504) and attempt < tries - 1:
            time.sleep(2 ** attempt)                              # 1, 2, 4 s
            continue
        r.raise_for_status()
        return r.json()["results"][0]


def blur(photo):
    rel = photo.relative_to(src)
    done = [p for p in (dst / rel).parent.glob(rel.stem + ".*") if p.suffix != ".csv"]
    if done:
        return rel, "skipped", []

    result = call_api(photo)
    # A photo the service can't read comes back as HTTP 200 with "failure".
    if result["status"]["code"] != "ok":
        return rel, "failed: " + result["status"]["message"], []

    by_kind = {e["kind"]: e for e in result["entities"]}
    image = by_kind["image"]
    out = dst / rel.with_suffix(EXT.get(image["format"], ".png"))
    out.parent.mkdir(parents=True, exist_ok=True)
    out.write_bytes(base64.b64decode(image["image"]))

    plates = [(o["box"], max(o["entities"][0]["classes"].values()))
              for o in by_kind.get("objects", {}).get("objects", [])]
    return rel, "ok", plates


photos = sorted(p for p in src.rglob("*") if p.suffix.lower() in PHOTOS)
dst.mkdir(parents=True, exist_ok=True)
counts = {"ok": 0, "skipped": 0, "failed": 0}

log_path = dst / "plates.csv"
new_log = not log_path.exists()
with ThreadPoolExecutor(max_workers=8) as pool, open(log_path, "a", newline="") as log:
    writer = csv.writer(log)
    if new_log:
        writer.writerow(["file", "status", "plates", "box_xywh", "confidence"])
    for rel, status, plates in pool.map(blur, photos):
        counts[status.split(":")[0]] += 1
        if status == "skipped":
            continue
        if not plates:
            writer.writerow([rel, status, 0, "", ""])
        for box, confidence in plates:
            writer.writerow([rel, status, len(plates),
                             " ".join(f"{v:.3f}" for v in box), f"{confidence:.2f}"])
        print(f"{status:>7}  {len(plates)} plate(s)  {rel}")

print(f"\n{len(photos)} photos: {counts['ok']} blurred, "
      f"{counts['skipped']} already done, {counts['failed']} failed")

Run it:

export API4AI_KEY=...
python3 blur_plates.py photos/ blurred/

What it takes care of:

Resume. A photo that already has an output file is skipped, so after a crash, a failure or a Ctrl-C you just run it again. Failed photos have no output, so they get retried automatically.
Rate limits and hiccups. A 429 or a 5xx waits 1, 2, then 4 seconds and tries again before giving up.
Failures you can see. Anything that comes back as "failure" is counted, printed and logged with its message, not dropped.
Structure. photos/2024/lot-3/car.jpg ends up at blurred/2024/lot-3/car.jpg.
The count at the end. Blurred plus already-done plus failed should equal what went in. If it doesn't, something's wrong, and you know before anyone else does.

Eight workers is a starting point, not a tuned number. If you start seeing a lot of 429s, lower it.

The part that matters: which photos to check

Here's the problem with 10,000 blurred photos: nobody is going to look at 10,000 photos. But you also can't publish them without looking at any.

The CSV gives you a way to pick. Two kinds of rows deserve a human:

Low confidence. The docs' own example came back at 0.56. Nothing is necessarily wrong with a low score — it means the model was less sure, which is exactly where you want a second pair of eyes.
Zero plates in a photo that should have one. A front or rear shot of a car where nothing was hidden is either a car without a visible plate, or a plate that wasn't found. Only a person can tell which.

import csv

rows = list(csv.DictReader(open("blurred/plates.csv")))
check = [r for r in rows
         if r["status"] == "ok"
         and (r["plates"] == "0" or float(r["confidence"] or 1) < 0.6)]

for r in sorted(check, key=lambda r: float(r["confidence"] or 0)):
    print(r["plates"], r["confidence"] or "-", r["file"])
print(f"{len(check)} of {len(rows)} rows to look at")

The 0.6 threshold is arbitrary — pick one, look at what it gives you, and move it. The point is that the review list is now a few hundred files ranked by how unsure the model was, not ten thousand in alphabetical order.

The boxes help too. They're normalized, so x * width and y * height give you pixels, and you can crop a thumbnail of each hidden region into a contact sheet and flick through it in a minute.

What it costs

The API is pay-as-you-go at $25 per 1,000 requests. One photo is one request, so 10,000 photos is $250. Keys and billing are on the API4AI developer portal, and the full reference is in the Image Anonymization docs.

If you don't want to write code

One or two photos: the Image Anonymization API page has a free demo. Upload a photo and see the result.
A dealer's listing photos: if you want the background replaced as well — every car on the same white or brand-color backdrop — CarBG does the cut-out and the plate in one pass, 60 photos at a time or a .zip. The background is removed either way there, so it's the wrong tool if you need to keep the scene.

There's a longer comparison of the three routes in How to Blur License Plates in Car Photos.

What are you anonymizing, and how are you checking the results today — spot checks, a second model, or not at all?

Standardizing 250 car photos a week without Photoshop (a 20-line Python job)

Oleg Tagobitsky — Mon, 21 Sep 2026 11:30:35 +0000

A dealership photographs twelve cars on the lot. Twelve different backgrounds come back: the service bay, a competitor's banner, half a customer's minivan. Individually fine. On a listing page, it looks like twelve different dealerships.

The fix is boring and mechanical, which makes it a good thing to automate: cut the car out, put it on the same backdrop every time. Here's the whole integration.

The endpoint

POST https://api4ai.cloud/img-bg-removal/v1/cars/results?mode=<mode>

Multipart form data. The photo goes in the image field as a file, or in url as a public link. Your key goes in the X-API-KEY header (api_key or key as a query parameter also works).

mode decides what you get back:

Mode	Output
`fg-image`	Car on a transparent background
`fg-image-shadow`	Car with a drop shadow
`fg-image-hideclp`	Car with the license plate hidden
`fg-image-shadow-hideclp`	Both
`fg-mask`	A mask, for compositing yourself

GET /img-bg-removal/v1/modes returns the list at runtime, so you don't have to hardcode it.

There's also an optional backdrop: pass your own image in image-bg (or url-bg) and it's blended under the car, centered. The output keeps the dimensions of the main input image, not the backdrop — worth knowing before you send a 4K backdrop and wonder why the result is 1500 px wide.

The response, and the failure case that isn't a 4xx

{
  "results": [
    {
      "status": { "code": "ok", "message": "Success" },
      "name": "img.jpg",
      "width": 1024,
      "height": 768,
      "entities": [
        {
          "kind": "image",
          "name": "cars-fg-image",
          "image": "iVBORw0KGgoAAAA...YII=",
          "format": "PNG",
          "representation": "base64"
        }
      ]
    }
  ]
}

The finished PNG is base64 in results[].entities[], alongside an objects entity with bounding boxes — so pick the entity by kind == "image" rather than by index.

The gotcha: an image the service can't read still comes back as HTTP 200. status.code is failure and status.message says why. If you only check raise_for_status(), those files quietly vanish from your output folder. Limits that trigger it: anything that isn't JPEG or PNG, over 16 MB, or larger than 4096 × 4096.

The batch script

import base64
import pathlib
import requests

API_KEY = "a4a-..."                # from portal.api4.ai
URL = "https://api4ai.cloud/img-bg-removal/v1/cars/results"
MODE = "fg-image-shadow"           # or fg-image, fg-mask, fg-image-hideclp, ...

src = pathlib.Path("inbox")        # today's lot photos
dst = pathlib.Path("ready")
dst.mkdir(exist_ok=True)

for photo in sorted(src.glob("*.jpg")):
    with photo.open("rb") as f:
        response = requests.post(
            URL,
            params={"mode": MODE},
            headers={"X-API-KEY": API_KEY},
            files={"image": f},
            timeout=60,
        )
    response.raise_for_status()

    result = response.json()["results"][0]
    if result["status"]["code"] != "ok":
        print(f"skipped {photo.name}: {result['status']['message']}")
        continue

    picture = next(e for e in result["entities"] if e["kind"] == "image")
    out = dst / f"{photo.stem}.png"
    out.write_bytes(base64.b64decode(picture["image"]))
    print(f"{photo.name} -> {out.name}")

Requests are independent, so for a few hundred cars wrap the loop body in a ThreadPoolExecutor and run 8–16 at a time.

One domain detail worth knowing

If the output feeds Google's vehicle ads, their image guidelines ask for at least 500 × 500 (1500 × 1500 recommended) at a 4:3 ratio, with no superimposed logos or text, and the whole vehicle in frame. Cluttered backgrounds and modified license plates are both on the "allowed but hurts performance" list.

So the plate-hiding modes are right for your own site and for marketplaces where you'd rather not publish a plate — and the plain modes are right for that feed. Run the batch twice with different modes; at $0.03 a photo it's not a real decision.

If you don't want to write the loop at all

The same engine runs as a browser tool at carbg.api4.ai: drop up to 60 photos or a .zip, pick transparent / white / brand color, optional shadow and plate blur, get one zip back. Prepaid at 3 cents a photo, $5 of credit on a new account (about 166 photos), no card. Useful for the pilot before you decide the automation is worth building.

Full API docs: api4.ai/docs/car-bg-removal. What do you use for image preprocessing in your listing pipeline?