Background Remover Skill

Remove backgrounds from images using FAL.ai's BiRefNet v2 model. Uses Bun for fast TypeScript execution with inline scripts.

Prerequisites

This skill requires:

• Bun - Fast JavaScript runtime
• FAL_KEY - FAL.ai API key set as environment variable

Checking for Bun

Before running scripts, verify Bun is installed:

which bun

If Bun is not installed, ask the user for permission before installing:

npm install -g bun

Setting up FAL.ai

1. Get an API key from https://fal.ai/dashboard/keys
2. Set the environment variable: export FAL_KEY="your-key-here"

Basic Usage

Remove background from an image using a heredoc script:

bun run - << 'EOF'
import { fal } from "@fal-ai/client";
import { readFileSync, writeFileSync } from "fs";
import { basename, dirname, join } from "path";

const imagePath = "INPUT_IMAGE_PATH";
const imageBuffer = readFileSync(imagePath);
const fileName = basename(imagePath);
const mimeType = imagePath.endsWith(".png") ? "image/png" : "image/jpeg";

// Upload to FAL storage
const file = new File([imageBuffer], fileName, { type: mimeType });
const imageUrl = await fal.storage.upload(file);
console.log("Uploaded:", imageUrl);

// Remove background
const result = await fal.subscribe("fal-ai/birefnet/v2", {
  input: {
    image_url: imageUrl,
    model: "General Use (Light)",
    operating_resolution: "1024x1024",
    output_format: "png"
  },
  logs: true,
  onQueueUpdate: (update) => {
    if (update.status === "IN_PROGRESS" && update.logs) {
      update.logs.map((log) => log.message).forEach(console.log);
    }
  },
});

// Download and save result
const outputUrl = result.data.image.url;
const response = await fetch(outputUrl);
const buffer = Buffer.from(await response.arrayBuffer());

const dir = dirname(imagePath);
const nameWithoutExt = basename(imagePath, basename(imagePath).match(/\.[^.]+$/)?.[0] || "");
const outputPath = join(dir, `${nameWithoutExt}-nobg.png`);

writeFileSync(outputPath, buffer);
console.log("Saved:", outputPath);
EOF

Replace INPUT_IMAGE_PATH with the actual path to the image.

Model Options

The BiRefNet model supports different configurations:

Model Variants

• "General Use (Light)" - Fast, good for most images (default)
• "General Use (Heavy)" - Higher quality, slower processing
• "Portrait" - Optimized for human subjects
• "Matting" - Best for complex edges like hair

Operating Resolutions

• "1024x1024" - Standard quality (default)
• "2048x2048" - Higher detail for large images

Additional Options

• refine_foreground: true - Improve edge quality
• output_format: "png" - Always use PNG for transparency

Configuration Example

For high-quality portrait extraction:

bun run - << 'EOF'
import { fal } from "@fal-ai/client";
import { readFileSync, writeFileSync } from "fs";
import { basename, dirname, join } from "path";

const imagePath = "INPUT_IMAGE_PATH";
const imageBuffer = readFileSync(imagePath);
const fileName = basename(imagePath);
const mimeType = imagePath.endsWith(".png") ? "image/png" : "image/jpeg";

const file = new File([imageBuffer], fileName, { type: mimeType });
const imageUrl = await fal.storage.upload(file);

const result = await fal.subscribe("fal-ai/birefnet/v2", {
  input: {
    image_url: imageUrl,
    model: "Portrait",
    operating_resolution: "2048x2048",
    refine_foreground: true,
    output_format: "png"
  },
  logs: true,
  onQueueUpdate: (update) => {
    if (update.status === "IN_PROGRESS" && update.logs) {
      update.logs.map((log) => log.message).forEach(console.log);
    }
  },
});

const response = await fetch(result.data.image.url);
const buffer = Buffer.from(await response.arrayBuffer());

const dir = dirname(imagePath);
const nameWithoutExt = basename(imagePath, basename(imagePath).match(/\.[^.]+$/)?.[0] || "");
const outputPath = join(dir, `${nameWithoutExt}-nobg.png`);

writeFileSync(outputPath, buffer);
console.log("Saved:", outputPath);
EOF

Key Principles

1. Check prerequisites: Always verify Bun is installed before running
2. Ask before installing: Get user permission before npm install -g bun
3. Use heredocs: Run inline scripts for one-off operations
4. Preserve location: Save output next to input with -nobg suffix
5. Always PNG: Output format must be PNG for transparency

Workflow

1. Verify Bun is installed (offer to install if not)
2. Verify FAL_KEY is set
3. Run the script with the input image path
4. Check the output - view the saved PNG with transparent background

Error Recovery

If a script fails:

1. Check FAL_KEY is set: echo $FAL_KEY
2. Verify image path exists and is readable
3. Check FAL.ai dashboard for quota/billing issues
4. Try a smaller image if upload fails

API Response Format

The BiRefNet model returns:

{
  "image": {
    "url": "https://...",
    "width": 1024,
    "height": 1024,
    "content_type": "image/png",
    "file_name": "birefnet-output.png"
  }
}

Advanced Usage

For batch processing, URL-based inputs, or integration with other tools, see references/guide.md.