remove-background

背景を削除 — RMBG 2.0で透明PNGと切り抜きを作成

あらゆる画像から背景を削除し、透明PNGを取得します。BriaのRMBG 2.0モデルを採用しており、商用利用にも安全で、ロイヤリティフリー、実運用に対応した背景削除と前景セグメンテーションを実現します。

このスキルを使用する場面

ユーザーが次のことを希望している場合に、このスキルを使用します。

• 背景を削除する — 「背景を削除して」「背景を透明にして」「背景を消して」
• 透明PNGを作成する — 「背景なしのPNGをください」「透明バージョン」「切り抜き」
• 切り抜きを作成する — 「人物を切り抜いて」「商品の切り抜き」「写真の切り抜き」「画像の切り抜き」
• 前景の被写体を抽出する — 「商品だけを分離して」「前景を抽出して」
• 特定のものを残す、または削除する（ガイド付き） — 「背景を削除して、マットは残して」「犬なしで」「椅子だけ」
• ECサイト用の商品切り抜き — 「背景が透明な商品写真」「商品画像の切り抜き」「カタログ用の切り抜き画像」
• ポートレートや顔写真の切り抜き — 「顔写真の背景を削除して」「背景なしのポートレート」
• 複数画像の背景を一括削除する — 「これらすべての画像から背景を削除して」「一括処理して」
• 画像をセグメンテーションする — 「前景をセグメント化して」「前景と背景を分離して」「前景のセグメンテーション」
• 合成用の切り抜きを準備する — 「別の画像に貼り付けるための切り抜きが必要です」「レイヤーを分離して」
• 背景消しゴム — 「背景を消して」「背景消しゴムツール」「背景をきれいに削除」

このスキルを使用しない場面

その他の画像操作には、代わりにbria-aiスキルを使用してください。

• 背景を新しいシーンに置き換える → bria-ai（replace_background）
• 背景をぼかす → bria-ai（blur_background）
• テキストから画像を生成する → bria-ai（generate）
• 指示に従って画像を編集する → bria-ai（edit）
• シーンから名前を指定したものを1つ取り出す（「木を抽出して」「車を抽出して」） → このスキルではなくbr ia-ai（POST /v2/image/edit/extract_object）。下記のルーティングを参照してください。

このスキルが行うのは1つだけです。背景を削除して、透明PNGと切り抜きを作成します。リクエストに応じて特定のものを残したり削除したりするガイド付きの方法も含まれます。

ルーティング：通常、ガイド付き、またはオブジェクト抽出

似たようなリクエストでも、ルートは3種類に分かれます。「Xだけ」という表現は、後者のどちらにも当てはまる場合があります。表現だけでルーティングしないでください。Xが明らかな前景、つまり通常の背景削除でもすでに被写体として残るものに含まれるかどうかで判断します。

1. Xが明らかな前景、またはその一部である場合：プロンプトで前景に追加する、一部を削除する、またはその一部に絞り込むリクエストです。「背景を削除して、マットは残して」「犬なしで」「椅子だけ」（椅子が、通常の切り抜きでもすでに残る目立つ被写体の1つである場合） → ガイド付き背景削除（POST /v2/image/edit/remove_background/guided。下記を参照）。背景全体を削除する切り抜きであることに変わりはありません。プロンプトによって、前景とみなすものだけを調整します。
2. Xが明らかな前景に含まれない場合 — 通常の切り抜きでは単独で残らない背景の物体や周辺の物体です。「木を抽出して」「背景の看板だけ」 → POST /v2/image/edit/extract_object（bria-aiスキル。こちらのスキルではありません）。目立つかどうかにかかわらず、シーンから名前を指定した特定のものを1つ取り出します。
3. それ以外の場合 — 「背景を削除して」「商品を切り抜いて」「透明PNG」 → 通常の背景削除（POST /v2/image/edit/remove_background。下記を参照）。

ガイド付きルートで404エラーが発生した場合に限り、現在この組織ではガイド付き削除を利用できません。下記の「ガイド付きルートで404エラーが発生した場合」を参照し、ガイド付きルートを再試行するのではなく、通常の背景削除に切り替えてください。認証、検証、サーバーエラー、タイムアウトなど、その他の失敗は実際のエラーです。「利用不可」として扱わず、エラーを明示してください。

---

セットアップ — 認証

APIを呼び出す前に、有効なBriaアクセストークンが必要です。

Step 1: 既存の認証情報を確認する

if [ -f ~/.bria/credentials ]; then
  BRIA_ACCESS_TOKEN=$(grep '^access_token=' "$HOME/.bria/credentials" | cut -d= -f2-)
  BRIA_API_KEY=$(grep '^api_token=' "$HOME/.bria/credentials" | cut -d= -f2-)
fi
if [ -z "$BRIA_ACCESS_TOKEN" ]; then
  echo "NO_CREDENTIALS"
elif [ -n "$BRIA_API_KEY" ]; then
  echo "READY"
else
  echo "CREDENTIALS_FOUND"
fi

出力が READY の場合は、そのまま API 呼び出しに進んでください。事前の確認は不要です。 出力が CREDENTIALS_FOUND の場合は、Step 3 に進んでください。 出力が NO_CREDENTIALS の場合は、Step 2 に進んでください。

Step 2: デバイス認証で認証する

デバイス認証フローを開始します。

2a. デバイスコードをリクエストします。

DEVICE_RESPONSE=$(curl -s -X POST "https://engine.prod.bria-api.com/v2/auth/device/authorize" \
  -H "Content-Type: application/json")
echo "$DEVICE_RESPONSE"

レスポンスのフィールドを解析します。

• device_code — トークンのポーリングに使用します（保持し、ユーザーには表示しないでください）
• user_code — ユーザーが入力するコードです（例：BRIA-XXXX）
• interval — ポーリング間隔（秒）

2b. サインインリンクを1つだけユーザーに表示します。 必ず次のとおりに伝えてください。余分なことは付け加えないでください。

Bria アカウントに接続： ここをクリックしてサインイン コードは {user_code} です。すでに入力されています。

リンクを2つ表示しないでください。生の URL を別途表示しないでください。API レスポンスの verification_uri は使用しないでください。クリック可能なリンクは1つだけにしてください。

2c. トークンをポーリングします。 ユーザーにコードを表示したら、直ちにポーリングを開始します。指定された間隔（デフォルトは5秒）で、最大60回試行してください。

for i in $(seq 1 60); do
  TOKEN_RESPONSE=$(curl -s -X POST "https://engine.prod.bria-api.com/v2/auth/token" \
    -d "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
    -d "device_code=$DEVICE_CODE")
  ACCESS_TOKEN=$(printf '%s' "$TOKEN_RESPONSE" | sed -n 's/.*"access_token" *: *"\([^"]*\)".*/\1/p')
  if [ -n "$ACCESS_TOKEN" ]; then
    BRIA_ACCESS_TOKEN="$ACCESS_TOKEN"
    REFRESH_TOKEN=$(printf '%s' "$TOKEN_RESPONSE" | sed -n 's/.*"refresh_token" *: *"\([^"]*\)".*/\1/p')
    mkdir -p ~/.bria
    printf 'access_token=%s\nrefresh_token=%s\n' "$BRIA_ACCESS_TOKEN" "$REFRESH_TOKEN" > "$HOME/.bria/credentials"
    echo "AUTHENTICATED"
    break
  fi
  sleep 5
done

出力に AUTHENTICATED が含まれている場合は、Step 3 に進んでください。それ以外の場合はコードの有効期限が切れているため、Step 2a からやり直してください。

認証が確認されるまで、API 呼び出しを行わないでください。

Step 3: 課金状況を確認し、API キーを取得する

Bearer トークンをイントロスペクションして課金状況を確認し、Bria API 呼び出しに使用する実際の API キーを取得します。

INTROSPECT=$(curl -s -X POST "https://engine.prod.bria-api.com/v2/auth/token/introspect" \
  -d "token=$BRIA_ACCESS_TOKEN")
BILLING_STATUS=$(printf '%s' "$INTROSPECT" | sed -n 's/.*"billing_status" *: *"\([^"]*\)".*/\1/p')
if [ "$BILLING_STATUS" = "blocked" ]; then
  BILLING_MSG=$(printf '%s' "$INTROSPECT" | sed -n 's/.*"billing_message" *: *"\([^"]*\)".*/\1/p')
  echo "BILLING_ERROR: $BILLING_MSG"
fi
ACTIVE=$(printf '%s' "$INTROSPECT" | sed -n 's/.*"active" *: *\([^,}]*\).*/\1/p' | tr -d ' ')
if [ "$ACTIVE" = "false" ]; then
  # Clear stale tokens so re-auth starts fresh (credentials file is re-created in Step 2c)
  printf '' > "$HOME/.bria/credentials"
  echo "TOKEN_EXPIRED"
fi
BRIA_API_KEY=$(printf '%s' "$INTROSPECT" | sed -n 's/.*"api_token" *: *"\([^"]*\)".*/\1/p')
if [ -n "$BRIA_API_KEY" ]; then
  grep -v '^api_token=' "$HOME/.bria/credentials" > "$HOME/.bria/credentials.tmp" 2>/dev/null || true
  printf 'api_token=%s\n' "$BRIA_API_KEY" >> "$HOME/.bria/credentials.tmp"
  mv "$HOME/.bria/credentials.tmp" "$HOME/.bria/credentials"
fi

出力を次のように解釈してください。

• BILLING_ERROR: ... が出力された場合は、表示されたメッセージをそのままユーザーに伝え、停止してください。API 呼び出しは行わないでください。
• TOKEN_EXPIRED が出力された場合は、セッションは無効です。セッションの有効期限が切れたことをユーザーに伝え、Step 2 からやり直してください。
• それ以外の場合は、BRIA_API_KEY に実際の API キーが格納され、今後の呼び出し用にキャッシュされています。次のセクションに進んでください。

---

背景を削除する方法

API 呼び出しには bria_call を使用します。URL の受け渡し、ローカルファイルの Base64 エンコード、JSON の構築、API 呼び出し、非同期ポーリングを、1回の関数呼び出しで処理します。API キーは ~/.bria/credentials から自動的に読み込まれます。

source ~/.agents/skills/remove-background/references/code-examples/bria_client.sh

# Remove background from a local file — get transparent PNG cutout
RESULT_URL=$(bria_call /v2/image/edit/remove_background "/path/to/image.png")
echo "$RESULT_URL"  # → https://...transparent.png

# Remove background from a URL — get transparent PNG cutout
RESULT_URL=$(bria_call /v2/image/edit/remove_background "https://example.com/photo.jpg")
echo "$RESULT_URL"  # → https://...transparent.png

これで完了です。 関数を1回呼び出すだけです。結果として、背景が削除された透明な PNG の URL が返されます。

入力

• ローカルファイルのパス — 任意の画像ファイル（JPEG、PNG、WEBP）。自動的に Base64 エンコードされ、アップロードされます。
• 画像 URL — 公開アクセス可能な任意の画像 URL。API に直接渡されます。

対応形式：JPEG、PNG、WEBP。CMYK および RGBA の入力に対応しています。

出力

透明部分を含む PNG の URLです。背景が完全に削除され、アルファチャンネル付きの前景の被写体だけが残ります。

結果をダウンロードしてローカルに保存します。

curl -sL "$RESULT_URL" -o output.png

---

ガイド付き背景削除 — 残す、取り除く、または絞り込む

ユーザーがシーン内の対象について、単に「背景を削除」するのではなく、何を残すか、何を取り除くかを指定した場合は、代わりにガイド付きルート POST /v2/image/edit/remove_background/guided を使用します。通常の背景削除と同じ信頼性の高い切り抜きをベースに、プロンプトで指定された内容だけを調整します。通常なら削除されるものを追加する、通常なら残るものを削除する、または指定した項目だけに絞り込むことができます。

source ~/.agents/skills/remove-background/references/code-examples/bria_client.sh

# "Remove the background but keep the mat and the plant"
RESULT_URL=$(bria_call /v2/image/edit/remove_background/guided "/path/to/yoga.jpg" '"prompt":"the person with the mat and the plant"')
echo "$RESULT_URL"  # → https://...transparent.png

入力

• image — 通常の背景削除と同じく、ローカルファイルのパスまたは URL です。
• prompt（任意）：残すもの、取り除くもの、または絞り込む対象を指定する平易な英語の文言です（例：「犬を除いて」「椅子だけ」）。固定された語彙やモードパラメーターはありません。
• prompt を省略または空欄にすると、通常の切り抜きが返されますが、ガイド付き呼び出しとして課金されます。通常のリクエストには、通常の背景削除を使用してください。
• 切り抜きにも適用できる背景削除オプション（出力形式など）は、変更されずに引き継がれます。

処理時間

ガイド付きの呼び出しには15～20秒かかり、通常の背景削除よりも明らかに時間がかかります。このエンドポイントはデフォルトで非同期に応答します。bria_call がリクエストを送信し、レスポンスから status_url を読み取って自動的にポーリングするため、上記の呼び出しにコードを追加する必要はありません。

ガイド付きエンドポイントが404を返す場合

/v2/image/edit/remove_background/guided が404を返す場合は、この組織では現時点でガイド付きの背景削除を利用できないことを意味し、不正なリクエストではありません。その場合に限って通常の背景削除に切り替え、次のように1行で伝えてください。

現時点ではガイド付きの背景削除を利用できないため、通常の背景削除を実行します。

「利用不可」を意味するのは404だけです。 無効なトークン（401）、不正なリクエスト（422）、サーバーエラー（5xx）、タイムアウトなど、それ以外の問題は実際のエラーであり、同じ「利用不可」というメッセージで黙って処理してはいけません。フォールバックする前にエラーテキストに 404 が含まれているかを確認し、それ以外のエラーはすべてそのまま表示してください。

source ~/.agents/skills/remove-background/references/code-examples/bria_client.sh
RESULT_URL=$(bria_call /v2/image/edit/remove_background/guided "/path/to/yoga.jpg" '"prompt":"the person with the mat and the plant"' 2>/tmp/guided_err.txt)
if [ $? -ne 0 ]; then
  if grep -q "^ERROR 404" /tmp/guided_err.txt; then
    # Only a 404 means guided removal is unavailable for this org: fall back, don't retry.
    RESULT_URL=$(bria_call /v2/image/edit/remove_background "/path/to/yoga.jpg")
  else
    # Any other error (401, 422, 5xx, timeout) is real: surface it, don't call it "unavailable."
    cat /tmp/guided_err.txt >&2
    exit 1
  fi
fi

---

使用例

EC向けの商品切り抜き

オンラインストア、カタログ、マーケットプレイス向けに、背景を透明にした商品画像を作成します。

source ~/.agents/skills/remove-background/references/code-examples/bria_client.sh
RESULT_URL=$(bria_call /v2/image/edit/remove_background "/path/to/product.jpg")
curl -sL "$RESULT_URL" -o product_cutout.png
echo "Transparent product cutout saved to product_cutout.png"

ポートレートや顔写真の背景削除

チームページ、ソーシャルプロフィール、合成画像向けに、顔写真やポートレートの背景を削除します。

source ~/.agents/skills/remove-background/references/code-examples/bria_client.sh
RESULT_URL=$(bria_call /v2/image/edit/remove_background "https://example.com/headshot.jpg")
curl -sL "$RESULT_URL" -o headshot_cutout.png

一括背景削除

ディレクトリ全体を処理し、ECカタログやアセットのパイプライン向けに背景を一括削除します。

source ~/.agents/skills/remove-background/references/code-examples/bria_client.sh
mkdir -p cutouts
for img in images/*.{jpg,png,webp}; do
  [ -f "$img" ] || continue
  name=$(basename "${img%.*}")
  RESULT_URL=$(bria_call /v2/image/edit/remove_background "$img")
  if [ -n "$RESULT_URL" ] && [ "$RESULT_URL" != "ERROR"* ]; then
    curl -sL "$RESULT_URL" -o "cutouts/${name}_cutout.png"
    echo "Done: $name"
  else
    echo "Failed: $name" >&2
  fi
done

合成用に前景の被写体を抽出

任意の写真から前景をセグメント化して抽出し、レイヤーや合成に使える切り抜きを作成します。

source ~/.agents/skills/remove-background/references/code-examples/bria_client.sh
RESULT_URL=$(bria_call /v2/image/edit/remove_background "/path/to/scene.jpg")
curl -sL "$RESULT_URL" -o foreground_cutout.png

ガイド付きの背景削除 — 特定の対象を残す、または削除する

ユーザーがシーン内で残す対象や削除する対象を指定すると、通常の背景削除ではなく、ガイド付きエンドポイントにリクエストを送信します。

source ~/.agents/skills/remove-background/references/code-examples/bria_client.sh
RESULT_URL=$(bria_call /v2/image/edit/remove_background/guided "/path/to/photo.jpg" '"prompt":"the woman at her desk without the lamp"' 2>/tmp/guided_err.txt)
if [ $? -ne 0 ]; then
  if grep -q "^ERROR 404" /tmp/guided_err.txt; then
    RESULT_URL=$(bria_call /v2/image/edit/remove_background "/path/to/photo.jpg")
    echo "Guided removal isn't available right now, so plain background removal was used instead."
  else
    cat /tmp/guided_err.txt >&2
    exit 1
  fi
fi
curl -sL "$RESULT_URL" -o guided_cutout.png

---

RMBG 2.0 の仕組み

1. 画像（ローカルファイルのパスまたは URL）を指定します
2. bria_call が Bria の RMBG 2.0 背景削除エンドポイントに画像を送信します
3. RMBG モデルがピクセル単位の精度で前景と背景をセグメント化します
4. 背景のピクセルが透明になります（alpha = 0）
5. 完全な透過情報を含む PNG の URL が返され、きれいに切り抜かれた画像を取得できます

RMBG 2.0 は、複雑な輪郭も実運用レベルの精度で処理します。

• 髪や毛皮 — 細い毛や繊細な輪郭を保持します
• 透明・半透明のオブジェクト — ガラス、ベール、煙
• 複雑な背景 — 物が多いシーン、グラデーション、被写体と似た色
• 複数の被写体 — 人物のグループ、商品を並べた画像
• 細部 — ジュエリー、レース、精巧な模様

---

追加リソース

• API エンドポイントのリファレンス — リクエストとレスポンスの形式を含む、エンドポイントの全ドキュメント
• シェルクライアント（bria_client.sh） — 単一関数のヘルパー：bria_call が認証、base64、JSON、ポーリングを処理します

関連スキル

• ad-delayer — テキストをテキストのまま維持しながら、平面的な広告全体を編集可能なレイヤーに分解します。「被写体を切り抜く」ではなく「この広告をレイヤーに分解する」場合は、このスキルの代わりに使用してください
• bria-ai — Bria API のすべての機能を利用できます。画像の生成、写真の編集、背景の置換・ぼかし、アップスケール、スタイル変更、商品写真の作成など、20以上のエンドポイントに対応しています
• image-utils — Python Pillow による後処理：サイズ変更、トリミング、合成、ウォーターマークの追加、形式変換