image-bg-remove

image-bg-remove

このスキルは、Starchild におけるすべての背景除去リクエストに使用します。

対象: ポートレートの背景除去(証明写真、ヘッドショット)、商品の切り抜き(EC 向け白背景)、集合写真の背景除去、ペット・動物の切り抜き、オブジェクトの分離、合成用の透明 PNG の作成。

基本原則: 提供されたスクリプトを呼び出してください。プロキシや課金の仕組みを再実装しないでください。

他の画像スキルとの主な違い: このスキルは、汎用の nanopro/gpt モデルではなく、専用の背景除去モデル(fal-ai/bria/background/remove — Bria RMBG 2.0)を使用します。プロンプトは不要です — 画像を提供するだけです。

---

1. クイックスタート — ローカルファイル(最も一般的)

⚠️ 実行コンテキスト — 最初にこれを読んでください。 以下のコードブロックはPythonであり、シェルコマンドではありません。Starchild の bash ツールは /bin/bash -c を実行するため、exec(open(...)) を解析できません — これらを直接 bash コマンドに貼り付けると、syntax error near unexpected token 'open' で失敗します。 また、python3 -c 内の exec(open(...)) は、スクリプトがパス解決に __file__ を 使用しているため、NameError: __file__ で失敗します。

bash ツール経由で呼び出す場合は、from exports import を併用して python3 - <<'EOF' を使用してください:

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

ヒアドキュメント(<<'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 を使用します:

ユーザーの発言	このスキルを使用
「背景を削除」/「去背景」/「抠图」	✅ はい
「透明にする」/「透明背景」	✅ はい
「切り抜きを作成」/「人物を切り抜く」	✅ はい
「白背景の商品写真」/「白底图」	✅ はい
「前景を抽出」/「被写体を分離」	✅ はい
「ヘッドショットの背景を削除」/「证件照去背景」	✅ はい
「透明 PNG」/「PNG 切り抜き」	✅ はい
「ペット写真の背景を削除」	✅ はい
「背景を一括削除」(複数画像)	✅ はい — ループで 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") を使用して、新しい背景に合成します

この 2 ステップのアプローチは、単一の replace_bg 呼び出しよりも優れた結果を生み出します。専用の RMBG モデルがよりクリーンなエッジを生成するためです。

---

7. モデルの詳細

プロパティ	値
モデル	fal-ai/bria/background/remove (Bria RMBG 2.0)
速度	約 3 秒
コスト	1 画像あたり約 $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']}")

E コマース向けの商品切り抜き

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

背景削除 + 置き換え (2 ステップワークフロー)

# 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	既存のアルファチャンネルをサポート
WebP	.webp	モダンな Web 形式
BMP	.bmp	レガシー形式

最大ファイルサイズ: 10 MB。

---

11. トラブルシューティング

問題	解決策
「ファイルが見つかりません」	ファイルパスがワークスペースルートからの相対パスであることを確認してください
「サポートされていない画像形式です」	まず JPEG/PNG/WebP に変換してください
「画像が大きすぎます」	処理前に 10 MB 未満にリサイズしてください
「送信に失敗しました: 401」	FAL_KEY 環境変数 (ローカル) または sc-proxy 設定 (本番) を確認してください
タイムアウト	まれです — モデルは通常約 3 秒で完了します。一度再試行してください。