cURL is the fastest way to verify an image API before adding an SDK or application code. This quickstart sends a local image to FAPIhub and writes the transparent PNG response to disk.
Make the first request
curl -X POST https://fapihub.com/v2/rembg/ \
-H "ApiKey: YOUR_API_KEY" \
-F "image=@product.jpg" \
--output product-no-background.pngA successful response is binary image data, so use --output instead of printing the response in your terminal.
Select a model
When an image needs a different segmentation behavior, pass the model as another multipart field. The background removal and mask endpoints accept falcon (the default), aurora, and ghost. Start with the default model, then compare results on your own image set before choosing a production default.
curl -X POST https://fapihub.com/v2/rembg/ \
-H "ApiKey: YOUR_API_KEY" \
-F "image=@portrait.jpg" \
-F "model=aurora" \
--output portrait-cutout.pngKeep errors visible
During testing, add --fail-with-body (curl 7.76 or newer) and write headers to a separate file. curl then exits with a non-zero status on an HTTP error, which makes authentication, validation, and rate-limit errors easy to detect. The error body is still written to the output file, so print it and delete the file when the request fails.
if ! curl --fail-with-body -sS -X POST https://fapihub.com/v2/rembg/ \
-H "ApiKey: $FAPIHUB_API_KEY" \
-F "image=@input.jpg" \
-D response-headers.txt \
--output output.png; then
cat output.png && rm output.png
fiInspect the status code and content type
Because the body is binary, the quickest health check is curl's --write-out option. It prints the status code and content type after the transfer, while the image itself still goes to the output file. A successful call returns 200 and an image content type; an error returns JSON.
curl -sS -X POST https://fapihub.com/v2/rembg/ \
-H "ApiKey: $FAPIHUB_API_KEY" \
-F "image=@product.jpg" \
--output result.bin \
--write-out "status=%{http_code} type=%{content_type} time=%{time_total}s\n"
file result.bin # confirms whether you received a PNG or a JSON errorAdd -v when you need to see the request headers and multipart boundary. It is the fastest way to confirm that the ApiKey header is actually being sent, which is the usual cause of a 401 when copying commands between shells.
Read error responses
Errors use a consistent JSON shape, so they are easy to parse with jq:
# Example error body
# {"error": {"code": "invalid_api_key", "message": "...", "request_id": "..."}}
jq -r '.error | "\(.code): \(.message) (request \(.request_id))"' output.png| Status | Code | Typical cause on the command line |
|---|---|---|
| 400 | invalid_image | Wrong path after @, a non-image file, or a malformed parameter value |
| 401 | invalid_api_key | Empty $FAPIHUB_API_KEY variable or a typo in the header name |
| 402 | insufficient_credits | The plan's monthly allowance is used up |
| 429 | rate_limit_exceeded | A loop sending requests faster than your plan's per-minute limit |
| 5xx | varies | Temporary server-side problem; safe to retry and not counted against quota |
A frequent 400 is caused by forgetting the @ prefix: -F "image=product.jpg" sends the literal text product.jpg instead of the file. Keep the @, and quote paths that contain spaces.
Try the other endpoints
Every endpoint takes the same image field and ApiKey header. Colors are RGBA tuple strings, so quote them on the command line.
# Black-and-white subject mask (accepts the same model option)
curl -X POST https://fapihub.com/v2/rembg/mask/ \
-H "ApiKey: $FAPIHUB_API_KEY" -F "image=@portrait.jpg" --output mask.png
# Blur the background; radius is required, maximum 50
curl -X POST https://fapihub.com/v2/rembg/blur/ \
-H "ApiKey: $FAPIHUB_API_KEY" -F "image=@portrait.jpg" -F "radius=20" --output blurred.png
# Solid white background
curl -X POST https://fapihub.com/v2/rembg/color/ \
-H "ApiKey: $FAPIHUB_API_KEY" -F "image=@product.jpg" \
-F "bgcolor=(255, 255, 255, 255)" --output white.png
# Vertical gradient
curl -X POST https://fapihub.com/v2/rembg/gradient/ \
-H "ApiKey: $FAPIHUB_API_KEY" -F "image=@product.jpg" \
-F "top_color=(255, 255, 255, 255)" -F "bottom_color=(220, 225, 235, 255)" \
--output gradient.png
# Drop shadow
curl -X POST https://fapihub.com/v2/rembg/shadow/ \
-H "ApiKey: $FAPIHUB_API_KEY" -F "image=@product.jpg" \
-F "shadow_color=(0, 0, 0, 150)" -F "offset=(10, 10)" -F "blur_radius=15" \
--output shadow.pngUse -F for every parameter, not -d. Mixing them switches the request away from multipart encoding and the image is not sent. For background on when a mask is more useful than a cutout, read our image mask API guide.
Use it in a shell loop
For a small local batch in bash, process files one at a time and preserve the original basename. For larger workloads, use a queue and bounded concurrency as described in our production pipeline guide.
mkdir -p processed
for image in raw/*.{jpg,jpeg,png,webp}; do
[ -f "$image" ] || continue
name="$(basename "${image%.*}")"
curl --fail-with-body -sS -X POST https://fapihub.com/v2/rembg/ \
-H "ApiKey: $FAPIHUB_API_KEY" \
-F "image=@$image" \
--output "processed/$name.png" \
|| { echo "Failed: $image"; rm -f "processed/$name.png"; }
doneRetry rate limits and server errors in a script
The loop above gives up on the first failure. For unattended scripts, wrap the call in a function that retries only 429, 5xx, and network failures, and honors the Retry-After header on rate-limit responses.
remove_bg() {
local input="$1" output="$2" headers status wait attempt
headers="$(mktemp)"
for attempt in 1 2 3 4; do
status="$(curl -sS -X POST https://fapihub.com/v2/rembg/ \
-H "ApiKey: $FAPIHUB_API_KEY" \
-F "image=@$input" \
-D "$headers" --output "$output" \
--write-out "%{http_code}")"
case "$status" in
200) rm -f "$headers"; return 0 ;;
429) wait="$(awk -F': ' 'tolower($1)=="retry-after" {print $2+0}' "$headers")" ;;
000|5??) wait=$((2 ** attempt)) ;;
*) echo "Failed $input ($status): $(cat "$output")" >&2
rm -f "$output" "$headers"; return 1 ;;
esac
sleep "${wait:-1}"
done
echo "Gave up on $input after $attempt attempts" >&2
rm -f "$output" "$headers"; return 1
}Status 000 means curl never got an HTTP response, usually a network problem or timeout, so it is treated like a server error. Retrying 5xx responses does not use up quota, while 4xx responses do count, which is why the function stops immediately on anything other than 429.
Run a small parallel batch
With the function defined, xargs -P runs a fixed number of requests at once. Keep the number low, since every plan has a per-minute rate limit and the retry function will slow down automatically if you hit it.
export -f remove_bg
export FAPIHUB_API_KEY
mkdir -p processed
find raw -type f \( -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.png' -o -iname '*.webp' \) -print0 |
xargs -0 -P 4 -I{} bash -c 'n="$(basename "${1%.*}")"; remove_bg "$1" "processed/$n.png"' _ {}Keep the API key out of your shell history
Typing the key directly into a command stores it in your history file and can expose it in process listings. Two safer options:
- Read it into an environment variable without echoing:
read -rs FAPIHUB_API_KEY && export FAPIHUB_API_KEY. - Put the full header line in a file with restricted permissions and pass it with
-H @fapihub-header.txt(curl 7.55 or newer). The file contains a single line such asApiKey: YOUR_API_KEY.
Create and rotate keys from your dashboard, and use a separate key for local testing so you can revoke it without affecting production.
Translate the request into application code
Once the cURL call works, porting it is mechanical. Each -H becomes a request header, each -F becomes a multipart form field, and @file becomes a file upload. The response body is the image, so write it as bytes.
import os
import requests
with open("product.jpg", "rb") as f:
response = requests.post(
"https://fapihub.com/v2/rembg/",
headers={"ApiKey": os.environ["FAPIHUB_API_KEY"]}, # -H
files={"image": f}, # -F "image=@product.jpg"
data={"model": "aurora"}, # -F "model=aurora"
timeout=30,
)
response.raise_for_status()
open("product-no-background.png", "wb").write(response.content) # --outputFull walkthroughs are available for Python and Node.js.
Frequently asked questions
Why does my terminal show garbled characters after the request?
The response is binary PNG data. Without --output, curl prints it to the terminal. Add --output result.png; recent curl versions also warn before printing binary output.
Which file types can I upload with cURL?
JPEG, PNG, WebP, BMP, and GIF, up to 10 MB per image. The output from the removal endpoint is a PNG with transparency.
Do I need to set the Content-Type header?
No. Using -F makes curl send multipart/form-data with the correct boundary automatically. Setting the header by hand can break the boundary.
How do I test without a paid plan?
The free Basic plan includes 100 requests per month with no credit card, which is plenty for trying each endpoint and model. You can also test images visually in the playground first.