A Free Background Removal API for GitHub Projects: What Is Actually Free, Plus a GitHub Action

Preview-size results: size=preview returns cutouts up to 800 px on the long edge, free, unlimited, without a card and without a watermark. For docs screenshots, avatars, thumbnails, test fixtures and demo apps that is usually the size you need anyway.

Ten full-resolution credits: the first key on an account comes with 10 credits, each good for one native-resolution image up to 4 MP synchronously (larger via jobs).

A free plan on RapidAPI: the same API is listed on RapidAPI with a BASIC plan at $0 and a small request quota, billed and metered by RapidAPI — handy if your project already uses RapidAPI keys.

The web tool: bgclear.ai itself is free and HD for humans; contributors who need one image do not need a key at all.

Beyond that, full-resolution images are one credit each — $9 for 100, $39 for 500, $129 for 2,000 — with no subscription and no expiry (pricing). There is no formal open-source programme today; if you maintain a project people actually use that integrates the API, say so through the feedback form in the site footer — that is how such programmes start.

The API key looks like bgc_live_…. Never commit it. Read it from an environment variable (BGCLEAR_API_KEY), keep .env in .gitignore, and give contributors a documented way to run without one — in this project the preview endpoint still needs a key, so the sensible default is a mock in tests and the real call behind an env check:

import os, requests

def remove_background(data: bytes, size: str = "preview") -> bytes:
    key = os.environ.get("BGCLEAR_API_KEY")
    if not key:
        raise RuntimeError("Set BGCLEAR_API_KEY (get one at https://www.bgclear.ai/api-keys/)")
    r = requests.post("https://www.bgclear.ai/api/v1/remove",
                      headers={"Authorization": f"Bearer {key}"},
                      files={"image_file": ("image.png", data)},
                      data={"size": size, "format": "png"}, timeout=60)
    if r.status_code != 200:
        raise RuntimeError(r.json()["error"]["message"])
    return r.content

If a key ever lands in a commit, rotate it from the dashboard — revoking the old key is immediate — and treat the git history as public regardless of how fast you force-push.

This workflow removes backgrounds from any image added under assets/raw/. On pull requests it uses size=preview (free) so reviewers see the cutout; on pushes to main it uses size=full and spends a credit per new image. The key lives in a repository secret and is never exposed to forks, because GitHub does not pass secrets to pull-request workflows from forked repositories.

# .github/workflows/cutouts.yml
name: cutouts
on:
  pull_request:
    paths: ["assets/raw/**"]
  push:
    branches: [main]
    paths: ["assets/raw/**"]

jobs:
  cutout:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 2 }
      - name: Remove backgrounds
        env:
          BGCLEAR_API_KEY: ${{ secrets.BGCLEAR_API_KEY }}
          SIZE: ${{ github.event_name == 'push' && 'full' || 'preview' }}
        run: |
          set -euo pipefail
          mkdir -p assets/cutouts
          for f in $(git diff --name-only --diff-filter=AM HEAD~1 -- 'assets/raw/*.jpg' 'assets/raw/*.png'); do
            out="assets/cutouts/$(basename "${f%.*}").png"
            code=$(curl -s -o "$out" -w '%{http_code}' -X POST https://www.bgclear.ai/api/v1/remove \
              -H "Authorization: Bearer $BGCLEAR_API_KEY" \
              -H "Idempotency-Key: $(sha256sum "$f" | cut -c1-64)" \
              -F "image_file=@$f" -F "size=$SIZE" -F "format=png")
            if [ "$code" != "200" ]; then echo "::error::$f -> HTTP $code: $(cat "$out")"; rm -f "$out"; exit 1; fi
            echo "$f -> $out ($SIZE)"
          done
      - name: Commit cutouts
        if: github.event_name == 'push'
        run: |
          git config user.name "cutouts-bot"
          git config user.email "[email protected]"
          git add assets/cutouts && git diff --cached --quiet || git commit -m "chore: regenerate cutouts [skip ci]"
          git push

The Idempotency-Key (the file's SHA-256) means a re-run of the workflow on the same image returns the cached result without a second charge. Add -F "bg_color=ffffff" for white backgrounds, or switch format to webp for smaller assets. Fork PRs will fail at the curl step because the secret is absent — that is the safe default; a maintainer can re-run the job after review.

Preview (≤800 px, free) is enough for README images, GitHub social previews, avatars, icons, chat bots and most web UI. Full resolution (one credit) matters for print, marketplaces, wallpapers and anything a user downloads as the final product. Budget at the top of the funnel: a project that generates 2,000 avatars a month at preview size pays nothing; the same project offering an "HD download" spends one credit per download and can pass that on. The Python and Node tutorials cover the client code in full, and the remove.bg alternative page shows the field mapping if your project was built on remove.bg's 50-call free tier, which ends with its shutdown on 1 December 2026.