Image Background Remover API Documentation

Image Background Remover API Documentation

Playground

Powerful AI background remover that outputs high-quality transparent PNGs for e-commerce, graphics, and design. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

Remove backgrounds from any image instantly with WaveSpeed AI’s Background Remover. This fast, precise tool automatically detects subjects and cleanly separates them from their backgrounds — perfect for e-commerce, portraits, product photography, and creative projects.

Why It Works Well

• Automatic detection: Intelligently identifies subjects without manual selection or masking.
• Clean edges: Produces smooth, professional cutouts even with complex details like hair.
• One-click simplicity: Just upload an image — no parameters to configure.
• Fast processing: Get results in seconds for rapid workflow integration.
• Ultra-affordable: Professional background removal at just $0.01 per image.

Parameters

How to Use

1. Upload your image — drag and drop or paste a public URL.
2. Run — click the button to process.
3. Download — save your image with transparent background.

Pricing

Flat rate per image.

Best Use Cases

• E-commerce & Product Photos — Create clean product images on white or transparent backgrounds.
• Portrait Photography — Isolate subjects for compositing or new background placement.
• Marketing & Advertising — Prepare assets for designs, banners, and promotional materials.
• Social Media Content — Create cutouts for collages, stickers, and creative posts.
• Batch Processing — Process large volumes of images affordably for catalogs and listings.

Pro Tips for Best Results

• Use images with clear distinction between subject and background for cleanest results.
• Good lighting and contrast help the AI detect edges more accurately.
• Works well with people, products, animals, and objects.
• For complex subjects like hair or fur, ensure the original image has good resolution.
• Output includes transparency — save as PNG to preserve the transparent background.

Notes

• If using a URL, ensure it is publicly accessible. A preview thumbnail confirms successful loading.
• Output is returned with transparent background (alpha channel).
• Processing is optimized for speed — suitable for real-time workflows.
• Works with various image formats and sizes.

Authentication

For authentication details, please refer to the Authentication Guide.

API Endpoints

Submit Task & Query Result

set -euo pipefail

export WAVESPEED_API_KEY="your-api-key"

REQUEST_BODY=$(cat <<'JSON'
{
  "image": "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg"
}
JSON
)

# 1. Submit the prediction once. Never retry this request automatically:
# a retry after an unclear failure can create a second, billed task.
CHECK='The task may already exist. Check History or the predictions list before submitting again.'
if ! SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --connect-timeout 10 --max-time 60 \
  -X POST "https://api.wavespeed.ai/api/v3/wavespeed-ai/image-background-remover" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}"); then
  printf 'Submit failed. %s\n' "${CHECK}" >&2
  exit 1
fi

TASK=$(printf '%s' "${SUBMIT_RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "${TASK}" | jq -r '.id // empty')
if [ -z "${PREDICTION_ID}" ]; then
  printf 'Submission response did not contain a prediction id. %s\n' "${CHECK}" >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction reaches a final status.
BODY_FILE=$(mktemp)
trap 'rm -f "${BODY_FILE}"' EXIT
while true; do
  # Transient errors (429, 5xx) are retried, honoring Retry-After.
  HTTP_CODE=$(curl --silent --show-error --fail-with-body \
    --connect-timeout 10 --max-time 60 --retry 5 --retry-delay 2 \
    --output "${BODY_FILE}" --write-out '%{http_code}' \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}" || true)
  case "${HTTP_CODE}" in
    2??) ;;
    000|429|5??)  # dropped connection or temporary error: keep polling
      printf 'Task %s: HTTP %s, polling again in 10s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      sleep 10; continue ;;
    *) printf 'Task %s: HTTP %s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      cat "${BODY_FILE}" >&2; exit 1 ;;
  esac
  RESULT=$(jq 'if type == "object" and has("data") then .data else . end' "${BODY_FILE}")
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout|deleted)
      printf 'Task %s ended with status %s\n' "${PREDICTION_ID}" "${STATUS}" >&2
      printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    *) sleep 2 ;;
  esac
done

Parameters

Task Submission Parameters

Request Parameters

Every model also accepts the global request options enable_sync_mode and enable_base64_output; see their pages for details.

Response Parameters

Result Request Parameters

Result Response Parameters