image-bg-remove

image-bg-remove

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

适用场景：人像背景移除（证件照、头像照）、商品抠图（电商白底图）、合照背景移除、宠物／动物抠图、物体隔离，以及准备可用于合成的透明 PNG。

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

与其他图像技能的主要区别：此技能使用专用背景移除模型（fal-ai/bria/background/remove — Bria RMBG 2.0），而非通用的 nanopro/gpt 模型。无需提示词——只需提供图像。

---

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

执行环境 — 请先阅读。 下面的代码块是 Python，不是 Shell 命令。Starchild 的 bash 工具 运行 /bin/bash -c，无法解析 exec(open(...))——直接将其粘贴到 bash 命令中 会导致 syntax error near unexpected token 'open'。 此外，在 python3 -c 中使用 exec(open(...)) 会因脚本使用 __file__ 解析路径而导致 NameError: __file__。

通过 bash 工具调用时，请使用 python3 - <<'EOF' 和 from exports import：

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

此处的 heredoc（<<'EOF'）会保留所有引号和换行——无需转义。

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}

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

2. 快速开始 — 公共 URL

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

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

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

向用户交付结果 — 重要

切勿将 fal.media 原始 URL 发给用户。fal 提供的文件带有限制性 CSP 标头。唯一可靠的交付方式是使用已下载到本地的文件：

1. 使用图像的 local_path（例如 output/images/xxx.png）——脚本成功后总会下载文件。
2. 告知用户文件已保存到 output/images/，可在工作区文件面板中查看。
3. 在 Web 频道中，将图像内嵌，以便用户在聊天中预览：

   ![transparent](output/images/<filename>.png)
   

4. 在 Telegram／WeChat 中：通过 send_to_telegram(file_path="output/images/...", message_type="image") 或 send_to_wechat(file_path="output/images/...", message_type="image") 发送。

---

4. 参数

参数	必填	默认值	说明
image_path	是*	—	源图像的本地工作区文件路径
image_url	是*	—	源图像的公共 HTTPS URL
output_path	否	自动	自定义输出文件路径。若未设置，则使用时间戳保存到 output/images/。

*必须提供 image_path 或 image_url 中的至少一个。如果两者都提供，则优先使用 image_path。

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

---

5. 何时使用此技能

当用户想要以下操作时，请使用 image-bg-remove：

用户说	使用此技能
“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. 何时不应使用此技能 — 请改用 image-edit

用户说	改用
“将背景替换成海滩” / “换背景”	image-edit（action="replace_bg"）
“虚化背景” / “背景虚化”	image-edit（action="edit"）
“将背景颜色改成蓝色”	image-edit（action="replace_bg"）
“编辑图像” / “增强照片”	image-edit
“根据文本生成图像”	image-create

关键区别：

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

对于背景替换工作流，建议采用以下方法：

1. 先使用 image-bg-remove 获取干净的透明抠图
2. 再使用 image-edit（action="blend"）合成到新背景上

与单次调用 replace_bg 相比，这种两步方法效果更好，因为专用 RMBG 模型能生成更干净的边缘。

---

7. 模型详情

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

这是唯一使用专用单用途模型的图像技能。所有其他图像技能都使用 nanopro 或 gpt 通用模型。

---

8. 响应格式

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

出错时：

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

---

9. 使用案例示例

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

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

电商产品抠图

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

批量处理多张图像

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

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

# 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. 支持的输入格式

格式	扩展名	说明
JPEG	.jpg、.jpeg	最常见的输入格式
PNG	.png	支持现有的 alpha 通道
WebP	.webp	现代 Web 格式
BMP	.bmp	旧式格式

最大文件大小：10 MB。

---

11. 故障排除

问题	解决方案
“找不到文件”	检查文件路径是否相对于工作区根目录
“不支持的图像格式”	请先转换为 JPEG/PNG/WebP
“图像过大”	处理前将图像大小调整至 10 MB 以下
“提交失败：401”	检查 FAL_KEY 环境变量（本地）或 sc-proxy 配置（生产环境）
超时	很少发生 — 模型通常会在约 3 秒内完成。请重试一次。