bria-ai/bria-skill/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.

1. 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.

1. 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

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:

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

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):

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:

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.

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:

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.

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: