remove-background

# Remove Background — Transparent PNGs & Cutouts with RMBG 2.0 Remove the background from any image and get a transparent PNG. Powered by Bria's RMBG 2.0 model — commercially safe, royalty-free, production-ready background removal and foreground segmentation. ## When to Use This Skill Use this skill when the user wants to: - **Remove a background** — "remove the background", "make the background transparent", "delete the background" - **Create a transparent PNG** — "give me a PNG with no background", "transparent version", "cutout" - **Create a cutout** — "cut out the person", "cutout of the product", "photo cutout", "image cutout" - **Extract the foreground subject** — "isolate the product", "extract the object", "foreground extraction" - **Product cutout for e-commerce** — "product photo with transparent background", "packshot cutout", "catalog cutout image" - **Portrait and headshot cutout** — "remove background from headshot", "portrait with no background" - **Batch background removal** — "remove backgrounds from all these images", "process in bulk" - **Image segmentation** — "segment the foreground", "separate foreground and background", "foreground segmentation" - **Prepare cutouts for compositing** — "I need a cutout to paste onto another image", "layer separation" - **Background eraser** — "erase the background", "background eraser tool", "clean background removal" ### When NOT to Use This Skill For other image operations, use the **bria-ai** skill instead: - **Replace** background with a new scene → bria-ai (`replace_background`) - **Blur** background → bria-ai (`blur_background`) - **Generate** images from text → bria-ai (`generate`) - **Edit** images with instructions → bria-ai (`edit`) This skill does one thing: **remove backgrounds to produce transparent PNGs and cutouts**. --- ## Setup — Authentication Before making any API call, you need a valid Bria access token. ### Step 1: Check for existing credentials ```bash 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 ``` If the output is `READY`, skip straight to making API calls — no introspection needed. If the output is `CREDENTIALS_FOUND`, skip to Step 3. If the output is `NO_CREDENTIALS`, proceed to Step 2. ### Step 2: Authenticate via device authorization Start the device authorization flow: **2a. Request a device code:** ```bash DEVICE_RESPONSE=$(curl -s -X POST "https://engine.prod.bria-api.com/v2/auth/device/authorize" \ -H "Content-Type: application/json") echo "$DEVICE_RESPONSE" ``` Parse the response fields: - `device_code` — used to poll for the token (keep this, don't show to user) - `user_code` — the code the user must enter (e.g. `BRIA-XXXX`) - `interval` — seconds between poll attempts **2b. Show the user a single sign-in link.** Tell them exactly this — nothing more: > **Connect your Bria account:** [Click here to sign in](https://platform.bria.ai/device/verify?user_code={user_code}) > Your code is **{user_code}** — it's already filled in. Do NOT show two links. Do NOT show the raw URL separately. Do NOT use `verification_uri` from the API response. Keep it to one clickable link. **2c. Poll for the token.** After showing the user the code, immediately start polling. Try up to 60 times with the given interval (default 5 seconds): ```bash 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 ``` If the output contains `AUTHENTICATED`, proceed to Step 3. Otherwise the code expired — start over from Step 2a. **Do not proceed with any API call until authentication is confirmed.** ### Step 3: Verify billing status and resolve API key Introspect the bearer token to check billing status and obtain the real API key for Bria API calls: ```bash 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 ``` Interpret the output: - If it prints `BILLING_ERROR: ...` — relay the message to the user exactly as shown and **stop**. Do not make any API calls. - If it prints `TOKEN_EXPIRED` — the session is no longer valid. Tell the user their session expired and restart from Step 2. - Otherwise, `BRIA_API_KEY` now contains the real API key and is cached for future calls. Proceed to the next section. --- ## How to Remove a Background Use `bria_call` for the API call. It handles URL passthrough, local file base64 encoding, JSON construction, the API call, and async polling — all in a single function call. The API key is auto-loaded from `~/.bria/credentials`. ```bash 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 ``` **That's it.** One function call. The result is a URL to a transparent PNG with the background removed. ### Input - **Local file path** — any image file (JPEG, PNG, WEBP). Automatically base64-encoded and uploaded. - **Image URL** — any publicly accessible image URL. Passed directly to the API. Supported formats: JPEG, PNG, WEBP. Supports CMYK and RGBA input. ### Output A URL to a **PNG with transparency** — the background is fully removed, leaving only the foreground subject with an alpha channel. Download the result to save it locally: ```bash curl -sL "$RESULT_URL" -o output.png ``` --- ## Examples ### Product cutout for e-commerce Create a transparent product cutout for online stores, catalogs, and marketplaces: ```bash 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" ``` ### Portrait and headshot background removal Remove backgrounds from headshots and portraits for team pages, social profiles, and compositing: ```bash 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 ``` ### Batch background removal Process entire directories — remove backgrounds in bulk for e-commerce catalogs and asset pipelines: ```bash 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 ``` ### Extract foreground subject for compositing Segment and extract the foreground from any photo to create a cutout for layering and compositing: ```bash 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 ``` --- ## How RMBG 2.0 Works 1. You provide an image (local file path or URL) 2. `bria_call` sends it to Bria's RMBG 2.0 background removal endpoint 3. The RMBG model performs foreground-background segmentation with pixel-level accuracy 4. Background pixels become transparent (alpha = 0) 5. You get back a PNG URL with full transparency — a clean cutout RMBG 2.0 handles complex edges with production-grade accuracy: - **Hair and fur** — fine strands and wispy edges preserved - **Transparent and semi-transparent objects** — glass, veils, smoke - **Complex backgrounds** — busy scenes, gradients, similar colors - **Multiple subjects** — groups of people, product arrangements - **Fine details** — jewelry, lace, intricate patterns --- ## Additional Resources - **[API Endpoints Reference](references/api-endpoints.md)** — Full endpoint documentation with request/response format - **[Shell Client (bria_client.sh)](references/code-examples/bria_client.sh)** — Single-function helper: `bria_call` handles auth, base64, JSON, polling ## Related Skills - **bria-ai** — Full Bria API access: generate images, edit photos, replace/blur backgrounds, upscale, restyle, product photography, and 20+ more endpoints - **image-utils** — Post-processing with Python Pillow: resize, crop, composite, watermarks, format conversion