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", "foreground extraction" - **Keep or drop something specific (guided)** — "remove the background but keep the mat", "without the dog", "only the chair" - **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`) - **Pull one named thing out of a scene** ("extract the tree", "extract the car") → bria-ai (`POST /v2/image/edit/extract_object`), not this skill — see Routing below. This skill does one thing: **remove backgrounds to produce transparent PNGs and cutouts**, including the guided variant that keeps or drops something specific on request. ### Routing: plain, guided, or extract-object Three different requests sound alike but hit three different routes. "Only the X" can mean either of the last two — don't route on wording alone. Decide by whether X is part of the **obvious foreground**: what a plain background-removal call would already keep as the subject. 1. **X is the obvious foreground, or part of it**: the prompt adds to it, drops part of it, or narrows down to one piece of it: "remove the background but keep the mat", "without the dog", "only the chair" (when the chair is one of the salient subjects a plain cutout would already keep) → **guided remove background** (`POST /v2/image/edit/remove_background/guided`, see below). Still a full background-removal cutout; the prompt only adjusts what counts as foreground. 2. **X is *not* part of the obvious foreground** — a background or peripheral object a plain cutout would never have kept on its own: "extract the tree", "only the sign in the background" → `POST /v2/image/edit/extract_object` (bria-ai skill, not this one). This pulls one specific, named thing out of the scene regardless of what's salient. 3. **Anything else** — "remove the background", "cut out the product", "transparent PNG" → plain **remove background** (`POST /v2/image/edit/remove_background`, below). If a guided call 404s specifically, guided removal is unavailable for the organization right now. See "If the guided route 404s" below; fall back to plain remove background rather than retrying the guided route. Any other failure (auth, validation, server error, timeout) is a real error: surface it, don't treat it as "unavailable." --- ## 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 ``` --- ## Guided Background Removal — Keep, Drop, or Narrow When the user names what to keep or drop relative to the scene (not a plain "remove the background"), use the guided route instead: `POST /v2/image/edit/remove_background/guided`. It starts from the same reliable cut as plain remove background, then adjusts only what the prompt names: add something that would have been dropped, drop something that would have been kept, or narrow down to just one named item. ```bash 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 ``` ### Input - **`image`** — local file path or URL, same as plain remove background. - **`prompt`** (optional): plain English naming what to keep, drop, or narrow to (e.g. "without the dog", "only the chair"). No fixed vocabulary or mode parameter. - An omitted or blank `prompt` returns the plain cut, still billed as a guided call. Send plain requests to plain remove background instead. - Any remove-background option that still applies to a cutout (e.g. output format) carries over unchanged. ### Timing A guided call takes **15-20 seconds**, noticeably longer than plain remove background. The route answers asynchronously by default; `bria_call` submits, reads `status_url` from the response and polls automatically, so no extra code is needed on top of the call above. ### If the guided route 404s A 404 from `/v2/image/edit/remove_background/guided` means guided removal is unavailable for this organization right now, not a bad request. Fall back to plain remove background only for that specific case, and say so in one line, e.g.: > Guided background removal isn't available right now, so here's a plain background removal instead. **Only a 404 means "unavailable."** Anything else, such as a bad token (401), a bad request (422), a server error (5xx) or a timeout, is a real failure and must not be silently swallowed into the same "unavailable" message. Check the error text for `404` specifically before falling back; for every other error, surface it as-is: ```bash 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 ``` --- ## 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