BiRefNet Sandbox

Authorship. Fully AI-generated. The original scripts were produced by an AI assistant from a short prompt and iterated within one chat session; the refactor into the current shape, this README, and SKILL.md were generated in a second session. I did not write or edit any of it by hand — I only directed the work and tested the outputs.

uv venv && uv pip install -r requirements.txt                      # one-time setup

uv run python remove_bg.py example_inputs/0.jpg                    # auto
uv run python remove_bg.py example_inputs/0.jpg --prompt hardware  # text-prompted

uv run python server.py                                            # browser UI, localhost only
uv run python server.py --public                                   # public *.gradio.live URL with random auth

First run downloads model weights (~900 MB auto, ~1.5 GB prompted) into ~/.cache/huggingface. Then offline.

Website

How it works, by audience

• Just curious: finds the thing in the photo, makes the rest see-through. Output is a PNG with transparency.
• You write code: a vision model returns per-pixel "is this foreground?" probabilities. That tensor becomes the alpha channel of an RGBA PNG.
• You do this for a living: auto path is BiRefNet at 1024² (DIS-style salient-object net, ZhengPeng7's checkpoint). Prompted path is GroundingDINO-tiny → boxes filtered by box/text thresholds → SAM-ViT-Large → union mask. fp32 with PYTORCH_ENABLE_MPS_FALLBACK=1. Deps live in requirements.txt; uv venv + uv pip install -r requirements.txt builds an isolated venv that uv run reuses thereafter.

Composability

remove_bg.py is three things at once: a CLI, a uv-runnable script, and a plain Python module.

from remove_bg import cutout
cutout(img, prompt="earth").save("out.png")

uv run python remove_bg.py *.jpg -o out/              # batch — model loads once
cat in.jpg | uv run python remove_bg.py - > out.png   # stdin → stdout PNG

Don't fan out N processes. Each one re-loads ~900 MB of weights, so cold-start dwarfs inference. For throughput, loop in one process or POST to server.py. The model is the cost; everything else is free.

Hugging Face access

The defaults — ZhengPeng7/BiRefNet, IDEA-Research/grounding-dino-tiny, facebook/sam-vit-large — are ungated and public. No API key, no auth, no metering. Inference runs locally on your machine; Hugging Face only serves the weights once, then you're offline.

The one gated option exposed by --auto-model is briaai/RMBG-2.0. To use it, accept the license at https://huggingface.co/briaai/RMBG-2.0 and either run huggingface-cli login once or set HF_TOKEN=hf_xxx before invoking. The defaults stay clear of it.

System requirements

I couldn't find published minimum requirements. On a $4 VPS it hung silently — no htop spike, no error output, just stalled — so plan on something with real RAM and ideally a GPU.

See SKILL.md for hosting recipes and the full Python/CLI/server cookbook.