Background removal API REST quickstart

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.png

A 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.png

Keep 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
fi

Inspect 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 error

Add -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
StatusCodeTypical cause on the command line
400invalid_imageWrong path after @, a non-image file, or a malformed parameter value
401invalid_api_keyEmpty $FAPIHUB_API_KEY variable or a typo in the header name
402insufficient_creditsThe plan's monthly allowance is used up
429rate_limit_exceededA loop sending requests faster than your plan's per-minute limit
5xxvariesTemporary 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.png

Use -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"; }
done

Retry 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 as ApiKey: 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)  # --output

Full 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.