image-bg-remove

Q: How do I install image-bg-remove?

Run npx skills add https://github.com/starchild-ai-agent/official-skills --skill image-bg-remove in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/image-bg-remove/ (personal) or .claude/skills/image-bg-remove/ (project).

by starchild-ai-agentMedia & Creative

Background removal: transparent PNGs, cutouts, product photos, portraits, pets, group photos. Uses dedicated Bria RMBG 2.0 model — no prompt needed, fast (3s), cheap ($0.01). Use when removing backgrounds, creating transparent PNGs, making cutouts, extracting foreground subjects, or preparing images for compositing.

Installs: 1.8K
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/starchild-ai-agent/official-skills --skill image-bg-remove

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads image-bg-remove automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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:

Use the image's local_path (e.g. output/images/xxx.png) — the script always downloads on success.
Tell the user the file is saved to output/images/ and viewable in the workspace file panel.
On Web channel, embed inline so the user can preview in chat:
```
![transparent](output/images/<filename>.png)
```
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

Parameter	Required	Default	Description
`image_path`	yes*	—	Local workspace file path to the source image
`image_url`	yes*	—	Public HTTPS URL of the source image
`output_path`	no	auto	Custom output file path. If not set, saves to `output/images/` with timestamp.

*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:

User says	Use this skill
"remove the background" / "去背景" / "抠图"	✅ Yes
"make it transparent" / "透明背景"	✅ Yes
"create a cutout" / "cut out the person"	✅ Yes
"product photo with white background" / "白底图"	✅ Yes
"extract the foreground" / "isolate the subject"	✅ Yes
"remove background from headshot" / "证件照去背景"	✅ Yes
"transparent PNG" / "PNG cutout"	✅ Yes
"remove background from pet photo"	✅ Yes
"batch remove backgrounds" (multiple images)	✅ Yes — call `remove_bg()` in a loop

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

User says	Use instead
"replace background with a beach" / "换背景"	image-edit (`action="replace_bg"`)
"blur the background" / "背景虚化"	image-edit (`action="edit"`)
"change background color to blue"	image-edit (`action="replace_bg"`)
"edit the image" / "enhance the photo"	image-edit
"generate an image from text"	image-create

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:

First use image-bg-remove to get a clean transparent cutout
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

Property	Value
Model	`fal-ai/bria/background/remove` (Bria RMBG 2.0)
Speed	~3 seconds
Cost	~$0.01 per image
Output	Transparent PNG (RGBA)
Input formats	JPEG, PNG, WEBP, BMP
Max input size	10 MB

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

Format	Extension	Notes
JPEG	`.jpg`, `.jpeg`	Most common input
PNG	`.png`	Supports existing alpha channel
WebP	`.webp`	Modern web format
BMP	`.bmp`	Legacy format

Maximum file size: 10 MB.

11. Troubleshooting

Issue	Solution
"File not found"	Check the file path is relative to workspace root
"Unsupported image format"	Convert to JPEG/PNG/WebP first
"Image too large"	Resize to under 10 MB before processing
"Submit failed: 401"	Check FAL_KEY env var (local) or sc-proxy config (production)
Timeout	Rare — the model usually completes in ~3s. Retry once.

FAQ

What does the image-bg-remove skill do?

How do I install image-bg-remove?

Run npx skills add https://github.com/starchild-ai-agent/official-skills --skill image-bg-remove in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/image-bg-remove/ (personal) or .claude/skills/image-bg-remove/ (project).

Which AI agents can use image-bg-remove?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is image-bg-remove safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains image-bg-remove?

It is published by starchild-ai-agent in starchild-ai-agent/official-skills. It has 1,829 recorded installs.