image-bg-remove

image-bg-remove

Use this skill for all background removal requests on Starchild.

Covers: portrait background removal (ID photos, headshots), product cutouts (e-commerce white-background), group photo background removal, pet/animal cutouts, object isolation, and preparing transparent PNGs for compositing.

Core principle: call the provided script. Do not re-implement proxy/billing plumbing.

Key difference from other image skills: this skill uses a dedicated background removal model (fal-ai/bria/background/remove — Bria RMBG 2.0), not the general-purpose nanopro/gpt models. No prompt is needed — just provide an image.

1. Quick start — local file (most common)

⚠️ Execution context — read this first. The code blocks below are Python, not shell commands. Starchild's bash tool runs /bin/bash -c, which cannot parse exec(open(...)) — pasting them directly into a bash command will fail with syntax error near unexpected token 'open'. Also, exec(open(...)) inside python3 -c fails with NameError: __file__ because the script uses __file__ for path resolution.

Use python3 - <<'EOF' with from exports import when calling via the bash tool:

python3 - <<'EOF'
import sys
sys.path.insert(0, "skills/image-bg-remove")
from exports import remove_bg
result = remove_bg(image_path="uploads/photo.jpg")
print(result)
EOF

The heredoc (<<'EOF') preserves all quotes and newlines — no escaping needed.

exec(open('skills/image-bg-remove/remove_bg.py').read())
result = remove_bg(image_path="uploads/photo.jpg")
# result -> {"success": True, "image": {"local_path": "output/images/..."}, "cost": 0.01, "duration_s": 3.2}

The script reads the local file, base64-encodes it, and sends it to fal.ai as a data URI — no manual URL publishing needed.

2. Quick start — public URL

exec(open('skills/image-bg-remove/remove_bg.py').read())
result = remove_bg(image_url="https://example.com/photo.jpg")

3. Quick start — custom output path

exec(open('skills/image-bg-remove/remove_bg.py').read())
result = remove_bg(
    image_path="uploads/product.jpg",
    output_path="output/images/product_transparent.png",
)

Delivering the result to the user — IMPORTANT

Never hand the user the raw fal.media URL. fal serves files with restrictive CSP headers. The only reliable delivery path is the already-downloaded local file:

1. Use the image's local_path (e.g. output/images/xxx.png) — the script always downloads on success.
2. Tell the user the file is saved to output/images/ and viewable in the workspace file panel.
3. On Web channel, embed inline so the user can preview in chat:

   ![transparent](output/images/<filename>.png)
4. On Telegram / WeChat: send via send_to_telegram(file_path="output/images/...", message_type="image") or send_to_wechat(file_path="output/images/...", message_type="image").

4. Parameters

*At least one of image_path or image_url must be provided. If both are given, image_path takes priority.

No prompt parameter — this is a pure tool skill. The dedicated model handles background removal automatically without any text instruction.

5. When to use this skill

Use image-bg-remove when the user wants to:

6. When NOT to use this skill — use image-edit instead

Key distinction:

• image-bg-remove → removes the background → outputs transparent PNG
• image-edit (replace_bg) → replaces the background with a new scene using a general-purpose model

For background replacement workflows, the recommended approach is:

1. First use image-bg-remove to get a clean transparent cutout
2. Then use image-edit (action="blend") to composite onto a new background

This two-step approach produces better results than a single replace_bg call because the dedicated RMBG model produces cleaner edges.

7. Model details

This is the only image skill that uses a dedicated single-purpose model. All other image skills use nanopro or gpt general-purpose models.

8. Response format

{
    "success": true,
    "image": {
        "url": "https://fal.media/files/...",
        "local_path": "output/images/20250531_153000_bg_removed.png",
        "size_bytes": 245760,
        "request_id": "abc123"
    },
    "cost": 0.01,
    "duration_s": 3.2
}

On error:

{
    "success": false,
    "error": "File not found: uploads/missing.jpg"
}

9. Use case examples

Portrait background removal (ID photo / headshot)

exec(open('skills/image-bg-remove/remove_bg.py').read())
result = remove_bg(image_path="uploads/headshot.jpg")
if result["success"]:
    print(f"Transparent headshot saved: {result['image']['local_path']}")

Product cutout for e-commerce

exec(open('skills/image-bg-remove/remove_bg.py').read())
result = remove_bg(image_path="uploads/product.jpg")
# Output: transparent PNG ready for white-background product listing

Batch processing multiple images

exec(open('skills/image-bg-remove/remove_bg.py').read())
import glob
 
images = glob.glob("uploads/products/*.jpg")
for img in images:
    result = remove_bg(image_path=img)
    if result["success"]:
        print(f"✓ {img} → {result['image']['local_path']}")
    else:
        print(f"✗ {img}: {result['error']}")

Background removal + replacement (two-step workflow)

# Step 1: Remove background with dedicated model (better edges)
exec(open('skills/image-bg-remove/remove_bg.py').read())
result = remove_bg(image_path="uploads/portrait.jpg")
transparent_path = result["image"]["local_path"]
 
# Step 2: Composite onto new background with image-edit
exec(open('skills/image-edit/edit_image.py').read())
final = edit_image(
    image_path=transparent_path,
    prompt="place this person on a tropical beach at sunset",
    action="blend",
)

10. Supported input formats

Maximum file size: 10 MB.

11. Troubleshooting