Most background-removal problems begin in the input image rather than the API request. A few checks before processing can reduce halos, missing details, and inconsistent edges.
Start with a clean source
- Use the largest sharp original available instead of a compressed thumbnail.
- Make sure the subject is well lit and separated from the background.
- Avoid heavy motion blur and aggressive sharpening around the subject.
- Keep the full subject inside the frame with a small margin around the edges.
Diagnose the problem by symptom
When a result looks wrong, name the symptom first. Each one has a different likely cause, and the fix is usually in the input or in post-processing rather than in repeating the same request.
| Symptom | Likely cause | What to try |
|---|---|---|
| Light or dark outline around the subject (halo) | Background color blended into semi-transparent edge pixels | Shoot against a background that contrasts with the subject; defringe the edge (see below) |
| Parts of the subject missing | Subject color close to the background, or deep shadows | Increase contrast and lighting; compare models on that image |
| Pieces of background left behind | Objects touching the subject, or a cluttered scene | Reframe with more separation; crop tighter before upload |
| Jagged or stair-stepped edges | Low-resolution or heavily compressed source | Use the original file instead of a thumbnail or screenshot |
| Soft, mushy edges | Motion blur or out-of-focus subject | Reshoot with a faster shutter or better focus; no post-processing fully fixes this |
| Glass or plastic looks solid or vanishes | Transparent materials show the background through them | Use a plain backdrop and route these items to manual review |
Fix orientation and size before upload
Phone photos often store rotation in an EXIF tag rather than in the pixels. To avoid depending on how each tool interprets that tag, rotate the pixels yourself before sending. While you are there, make sure the file is within the 10 MB limit by downscaling very large originals rather than recompressing them aggressively, which adds the block artifacts that make edges harder to segment.
from io import BytesIO
from PIL import Image, ImageOps
MAX_BYTES = 10 * 1024 * 1024
def prepare_for_upload(path, max_side=4000):
img = ImageOps.exif_transpose(Image.open(path)) # bake rotation into pixels
if max(img.size) > max_side:
img.thumbnail((max_side, max_side), Image.LANCZOS)
buffer = BytesIO()
if img.mode in ("RGBA", "LA", "P"):
img.save(buffer, "PNG")
else:
img.convert("RGB").save(buffer, "JPEG", quality=95)
if buffer.tell() > MAX_BYTES:
raise ValueError("Still larger than 10 MB; lower max_side")
return buffer.getvalue()Inspect difficult edges
Hair, fur, thin cables, glass, and white objects against bright backgrounds are harder to segment. Review the output at 100% zoom on both a dark and light checkerboard. An edge that looks correct on one background can reveal a light or dark fringe on another.
Compare models on representative images
Do not choose a model based on one ideal sample. Build a small evaluation set containing portraits, products, fine detail, and low-contrast images. Compare the same input across available models and select the model that performs consistently for your catalog.
Run a side-by-side model comparison
The removal and mask endpoints accept three models: falcon (the default), aurora, and ghost. The evaluation set described above becomes useful once you can generate every model's output in one pass and review them together. This script writes one cutout per image per model.
import os
from pathlib import Path
import requests
MODELS = ["falcon", "aurora", "ghost"]
API_KEY = os.environ["FAPIHUB_API_KEY"]
def compare(sample_dir="samples", out_dir="comparison"):
Path(out_dir).mkdir(exist_ok=True)
for image in sorted(Path(sample_dir).glob("*.*")):
for model in MODELS:
target = Path(out_dir) / f"{image.stem}__{model}.png"
if target.exists():
continue # do not pay twice for the same comparison
with image.open("rb") as f:
response = requests.post(
"https://fapihub.com/v2/rembg/",
headers={"ApiKey": API_KEY},
files={"image": f},
data={"model": model},
timeout=60,
)
if response.ok:
target.write_bytes(response.content)
else:
print(image.name, model, response.status_code, response.text)
compare()Each image costs three requests, one per model. A 30-image evaluation set uses 90 requests, which fits within the free Basic plan's 100 requests per month. Try each model on your own images and keep the one that looks best across the whole set, not just on the easiest examples. For one-off checks, the playground lets you compare results visually without writing code.
Defringe a halo after processing
If a cutout is otherwise good but carries a thin outline from the old background, shrinking the alpha channel by a pixel often removes it. This is a trade-off: it also trims fine detail such as individual hairs, so apply it to products with solid edges rather than to portraits.
from PIL import Image, ImageFilter
def defringe(cutout_path, output_path, pixels=1):
img = Image.open(cutout_path).convert("RGBA")
r, g, b, alpha = img.split()
for _ in range(pixels):
alpha = alpha.filter(ImageFilter.MinFilter(3)) # erode edge by 1 px
img.putalpha(alpha)
img.save(output_path)
defringe("bottle.png", "bottle-clean.png")Use the mask for finer control
When you need more control than a finished cutout offers, request a mask from /v2/rembg/mask/ and apply it to your full-resolution original yourself. Working from the mask lets you feather or tighten the edge, apply different treatment to hair and to hard product edges, and regenerate variants without another request. Our mask API guide shows how to apply a mask with Pillow.
Keep transparency until the final step
Do not flatten the cutout onto white before you know where it will be used. Keeping a transparent PNG lets you inspect the edge, apply a controlled background, and create separate versions for marketplaces and campaigns. See our transparent versus white background guide for the output decision.
Build a review path
Automated processing should handle the common case, while difficult categories (hair, glass, low-contrast shots) or visually sensitive assets can be sent to a review queue. Save the original, result, model, and processing timestamp together so an editor can make a decision without repeating the entire workflow.
Measure quality with a sample set
Track the percentage of images accepted without edits, the most common correction type, and failures by source. This gives you a practical quality signal and shows whether changing lighting, camera setup, or model selection is actually helping.
Quality checklist before publishing
- Review edges at 100% zoom on a dark and a light background.
- Composite onto the actual destination background (white, brand color, or theme) and check again.
- Confirm nothing is cropped: handles, straps, cables, and shadows that belong to the product.
- Check that framing and fill are consistent with the rest of the catalog.
- Record the model and any post-processing applied, so the result can be reproduced.
Frequently asked questions
Why does my cutout have a white outline on a dark background?
The edge pixels still contain some of the original light background. Shoot against a backdrop that contrasts with the subject, try another model on that image, or erode the alpha channel by one pixel for products with solid edges.
Does a higher-resolution upload always give better results?
A sharp, well-lit original helps more than raw pixel count. Upscaling a small or blurry image does not add real detail. Upload the best original you have, within the 10 MB limit.
Which model should I use?
There is no single answer for every catalog. Run the same representative images through falcon, aurora, and ghost, and keep the one that performs consistently on your images.
Do re-processed images count against my quota?
Yes. Each successful request counts, so store results and only reprocess when the input, model, or settings change. 5xx errors are never counted. For studio workflows, see the photography use case.