remove.bg

Promptfree, for everyone, and the only version there is

Copy the prompt for Claude CodeCopy the prompt for CodexCopy the prompt for Cursor

Copy

Build me background removal that replaces remove.bg: an API and a page that return a cutout, running on my own machine.

The model is the product here, and the good news is that capable ones are open and free. What you take on is running them.

STACK
- Node 20+ with Fastify
- SQLite through better-sqlite3 for jobs and history
- An open segmentation model through ONNX Runtime — the U^2-Net family and its successors are what the open tools use
- sharp for the compositing and the output
- Caddy in front

THE DATA MODEL
- jobs: id, token, status, input_path, output_path, sha256, bytes_in, bytes_out, width, height, model_version, ms, error, created_at, expires_at
- api_keys: id, name, hash, rate_per_minute, monthly_limit, revoked_at
- Files expire — an hour by default — with a sweeper that deletes from disk as well as the row. Somebody's photograph is not yours to keep

THE PIPELINE
- Decode, resize to the model's input size, run the model, get a mask back
- **The mask is the whole quality question.** A raw model mask has hard, jagged edges; the difference between a usable cutout and an obvious one is what you do next
- Feather the edge by a pixel or two, and matte properly: composite with the alpha rather than simply masking, or every semi-transparent pixel keeps a halo of the old background
- Hair and fur are where every model struggles. A trimap-based refinement pass over the uncertain band helps a great deal and costs a little
- **Decontaminate the colour**: pixels at the edge have the old background mixed into them, and leaving that is why a cutout looks wrong on a new background even when the shape is right
- Return the full-resolution result, not the model's input size. Run the model small, upscale the mask, apply it to the original

THE API
- POST an image or a URL, get a PNG with alpha, or a composite over a colour or another image
- Synchronous under a deadline, asynchronous with a webhook above it
- Idempotency by a hash of the input and the options, so the same picture twice is one run
- Errors that say which stage failed
- A size cap, a rate limit per key, and a refusal to follow a URL into a private address range — this is a server fetching what a caller chose

RUNNING THE MODEL
- On a processor it takes a second or two per image, which is fine for a queue and slow for a page. With a graphics card it is milliseconds
- A worker with a concurrency cap. Model inference is memory-hungry and unbounded parallelism takes the machine down
- The model loaded once and kept warm, never per request
- Record the model version on every job, so a change in output is explicable rather than mysterious

WHAT TO BE HONEST ABOUT
- An open model is very good on a clear subject and noticeably worse on fine hair, glass, motion blur and a subject the same colour as its background. The paid service is better on exactly those
- So offer a preview before the credit is spent, and let a person reject a bad cutout rather than discovering it downstream

OPERATIONS
- .env: DATABASE_PATH, STORAGE_PATH, BASE_URL, MODEL_PATH, MAX_UPLOAD_BYTES, RETENTION_MINUTES
- Migrations on boot, each once; disk watchdog and a working sweeper
- Health endpoint that cuts out a fixture through the real path

WHAT MATTERS MOST
Edge quality, not segmentation. The model gives you a mask in an afternoon; feathering, matting and colour decontamination are what make the result usable, and they are the difference between this and the paid one.