image-bg-remove

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

在Starchild上处理所有背景移除请求时，请使用此skill。

适用场景包括：人像背景移除（证件照、头像照）、产品抠图（电商白底图）、合影背景移除、宠物/动物抠图、物体分离，以及为图像合成准备透明PNG。

核心原则： 调用提供的脚本，不要重新实现代理/计费相关逻辑。

与其他图像skill的关键区别： 本skill使用专用背景移除模型（

fal-ai/bria/background/remove

—— Bria RMBG 2.0），而非通用的nanopro/gpt模型。无需提供提示词——只需传入图像即可。

1. Quick start — local file (most common)

1. 快速开始——本地文件（最常用）

python

exec(open('skills/image-bg-remove/remove_bg.py').read())
result = remove_bg(image_path="uploads/photo.jpg")

python

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.


该脚本会读取本地文件，将其Base64编码后以数据URI形式发送至fal.ai——无需手动发布URL。

2. Quick start — public URL

2. 快速开始——公共URL

python

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

python

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

3. 快速开始——自定义输出路径

python

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",
)

python

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:
markdown
```
![transparent](output/images/<filename>.png)
```

On Telegram / WeChat: send via

send_to_telegram(file_path="output/images/...", message_type="image")

send_to_wechat(file_path="output/images/...", message_type="image")

切勿直接将原始fal.media URL提供给用户。 fal提供的文件带有严格的CSP头，唯一可靠的交付方式是已下载的本地文件：

使用图像的
```
local_path
```
（例如
```
output/images/xxx.png
```
）——脚本在处理成功后总会自动下载文件。
告知用户文件已保存至
```
output/images/
```
，可在工作区文件面板中查看。
在Web渠道中，可将图像嵌入聊天内容让用户预览：
markdown
```
![transparent](output/images/<filename>.png)
```

在Telegram/微信渠道：使用

send_to_telegram(file_path="output/images/...", message_type="image")

或

send_to_wechat(file_path="output/images/...", message_type="image")

发送文件。

4. Parameters

4. 参数说明

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

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.

参数	是否必填	默认值	描述
`image_path`	是*	—	源图像在工作区中的本地文件路径
`image_url`	是*	—	源图像的公开HTTPS URL
`output_path`	否	自动生成	自定义输出文件路径。若未设置，将保存至 `output/images/` 并带有时间戳。

*必须提供

image_path

或

image_url

中的至少一个。若两者都提供，

image_path

优先级更高。

无提示词参数——这是一个纯工具类skill。专用模型会自动处理背景移除，无需任何文本指令。

5. When to use this skill

5. 何时使用本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

当用户有以下需求时，请使用image-bg-remove：

用户需求	是否使用本skill
"remove the background" / "去背景" / "抠图"	✅ 是
"make it transparent" / "透明背景"	✅ 是
"create a cutout" / "cut out the person"	✅ 是
"product photo with white background" / "白底图"	✅ 是
"extract the foreground" / "isolate the subject"	✅ 是
"remove background from headshot" / "证件照去背景"	✅ 是
"transparent PNG" / "PNG cutout"	✅ 是
"remove background from pet photo"	✅ 是
"batch remove backgrounds"（多张图像）	✅ 是——循环调用 `remove_bg()` 即可

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

6. 何时不使用本skill——改用image-edit

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.

用户需求	改用其他skill
"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

关键区别：

image-bg-remove → 移除背景 → 输出透明PNG
image-edit（
```
replace_bg
```
）→ 使用通用模型将背景替换为新场景

对于背景替换工作流，推荐的步骤是：

首先使用image-bg-remove获得干净的透明抠图
然后使用image-edit（
```
action="blend"
```
）将其合成到新背景上

这种两步法比直接调用

replace_bg

的效果更好，因为专用的RMBG模型能生成更清晰的边缘。

7. Model details

7. 模型详情

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.

属性	值
模型	`fal-ai/bria/background/remove` （Bria RMBG 2.0）
速度	约3秒
成本	约0.01美元/张图像
输出	透明PNG（RGBA格式）
输入格式	JPEG、PNG、WEBP、BMP
最大输入大小	10 MB

这是唯一使用专用单用途模型的图像skill，其他所有图像skill均使用nanopro或gpt通用模型。

8. Response format

8. 响应格式

json

{
    "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:

json

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

json

{
    "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
}

错误响应：

json

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

9. Use case examples

9. 用例示例

Portrait background removal (ID photo / headshot)

人像背景移除（证件照/头像照）

python

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']}")

python

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

电商产品抠图

python

exec(open('skills/image-bg-remove/remove_bg.py').read())
result = remove_bg(image_path="uploads/product.jpg")

python

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

输出：可用于电商白底商品列表的透明PNG

undefined

undefined

Batch processing multiple images

批量处理多张图像

python

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']}")

python

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)

背景移除+替换（两步工作流）

python

undefined

python

undefined

Step 1: Remove background with dedicated model (better edges)

步骤1：使用专用模型移除背景（边缘效果更好）

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

步骤2：使用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", )

---

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

10. 支持的输入格式

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.

格式	扩展名	说明
JPEG	`.jpg` , `.jpeg`	最常用的输入格式
PNG	`.png`	支持现有alpha通道
WebP	`.webp`	现代网络格式
BMP	`.bmp`	旧格式

最大文件大小：10 MB。

11. Troubleshooting

11. 故障排除

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.

问题	解决方案
"File not found"	检查文件路径是否相对于工作区根目录
"Unsupported image format"	先转换为JPEG/PNG/WebP格式
"Image too large"	先调整图像大小至10 MB以下
"Submit failed: 401"	检查本地环境变量FAL_KEY或生产环境的sc-proxy配置
超时	罕见情况——模型通常约3秒完成。重试一次即可。