remove-background

移除背景 — 使用 RMBG 2.0 创建透明 PNG 和抠图

移除任意图像的背景，获取透明 PNG。由 Bria 的 RMBG 2.0 模型提供支持，可商用、免版税、适用于生产环境的背景移除和前景分割。

何时使用此技能

用户想要以下操作时，请使用此技能：

• 移除背景 — “移除背景”“将背景设为透明”“删除背景”
• 创建透明 PNG — “给我一张没有背景的 PNG”“透明版本”“抠图”
• 创建抠图 — “把这个人抠出来”“抠出产品”“照片抠图”“图像抠图”
• 提取前景主体 — “分离出产品”“提取前景”
• 保留或移除特定对象（引导式） — “移除背景，但保留垫子”“不要狗”“只要椅子”
• 用于电商的产品抠图 — “背景透明的产品照片”“商品抠图”“目录用抠图”
• 人像和头像抠图 — “移除头像背景”“无背景人像”
• 批量移除背景 — “移除这些图像的背景”“批量处理”
• 图像分割 — “分割前景”“分离前景和背景”“前景分割”
• 准备合成用的抠图 — “我需要一张抠图，以便粘贴到另一张图像上”“图层分离”
• 背景橡皮擦 — “擦除背景”“背景橡皮擦工具”“干净地移除背景”

何时不使用此技能

对于其他图像操作，请改用 bria-ai 技能：

• 替换背景为新场景 → bria-ai（replace_background）
• 模糊背景 → bria-ai（blur_background）
• 根据文本生成图像 → bria-ai（generate）
• 根据指令编辑图像 → bria-ai（edit）
• 从场景中提取一个指定对象（“提取树”“提取汽车”）→ bria-ai（POST /v2/image/edit/extract_object），不要使用此技能 — 请参阅下文的路由说明。

此技能只做一件事：移除背景，生成透明 PNG 和抠图，包括根据请求保留或移除特定对象的引导式变体。

路由：普通、引导式或提取对象

三种不同的请求听起来相似，却会走三种不同的路由。“只要 X”可能指后两种情况之一 — 不要只根据措辞来选择路由。请判断 X 是否属于明显的前景：也就是普通背景移除请求本来就会保留为主体的内容。

1. X 是明显的前景，或属于前景的一部分：提示词要求在其基础上添加内容、移除其中一部分，或将范围缩小到其中一部分：“移除背景，但保留垫子”“不要狗”“只要椅子”（当椅子是普通抠图本来就会保留的显著主体之一时）→ 引导式移除背景（POST /v2/image/edit/remove_background/guided，见下文）。这仍然是完整的背景移除抠图；提示词只调整哪些内容算作前景。
2. X 不属于明显的前景 — 即普通抠图不会单独保留的背景或边缘对象：“提取树”“只要背景中的标志” → POST /v2/image/edit/extract_object（使用 bria-ai 技能，不是此技能）。这会从场景中提取一个指定对象，不受显著性影响。
3. 其他任何情况 — “移除背景”“抠出产品”“透明 PNG” → 普通的移除背景（POST /v2/image/edit/remove_background，见下文）。

如果引导式请求明确返回 404，说明当前组织暂时无法使用引导式移除。请参阅下文的“如果引导式路由返回 404”，改用普通的移除背景，不要重试引导式路由。其他任何失败（身份验证、验证、服务器错误、超时）都是真实错误：应报告该错误，不要将其视为“不可用”。

---

设置 — 身份验证

进行任何 API 调用之前，你需要有效的 Bria 访问令牌。

第 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，跳至第 3 步。 如果输出为 NO_CREDENTIALS，继续第 2 步。

第 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. 向用户展示一个登录链接。 仅向用户准确告知以下内容，不要添加其他信息：

连接你的 Bria 账户：点击此处登录 你的代码是 {user_code}——已自动填入。

不要展示两个链接。不要单独展示原始 URL。不要使用 API 响应中的 verification_uri。只保留一个可点击链接。

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，继续第 3 步。否则，代码已过期；从第 2a 步重新开始。

在确认身份验证成功之前，不要进行任何 API 调用。

第 3 步：验证账单状态并获取 API 密钥

检查承载令牌的账单状态，并获取用于调用 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，表示会话已失效。告知用户会话已过期，并从第 2 步重新开始。
• 否则，BRIA_API_KEY 现在包含真实 API 密钥，并已缓存以供后续调用。继续下一节。

---

如何移除背景

使用 bria_call 发起 API 调用。它会在一次函数调用中处理 URL 透传、本地文件的 base64 编码、JSON 构建、API 调用和异步轮询。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

就这么简单。 只需调用一次函数。结果是一个移除背景后的透明 PNG URL。

输入

• 本地文件路径 — 任意图像文件（JPEG、PNG、WEBP）。系统会自动进行 base64 编码并上传。
• 图像 URL — 任意可公开访问的图像 URL。会直接传递给 API。

支持的格式：JPEG、PNG、WEBP。支持 CMYK 和 RGBA 输入。

输出

一个指向透明 PNG 的 URL——背景已完全移除，只留下带有 alpha 通道的前景主体。

下载结果并保存到本地：

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（可选）：用英语明确说明要保留、移除或缩小范围保留的内容（例如 “without the dog”（不要狗）或 “only the chair”（只要椅子））。无需使用固定词汇或模式参数。
• 如果省略或留空 prompt，则返回普通抠图结果，但仍按引导式调用计费。普通请求应使用普通背景移除接口。
• 仍适用于抠图的任何背景移除选项（例如输出格式）都会原样沿用。

耗时

引导式调用需要 15-20 秒，明显比普通背景移除耗时更长。该路由默认异步响应；bria_call 会提交请求、从响应中读取 status_url 并自动轮询，因此无需在上述调用基础上编写额外代码。

如果引导式路由返回 404

/v2/image/edit/remove_background/guided 返回 404，意味着当前组织暂时无法使用引导式移除，而不是请求有误。仅在这种特定情况下，才回退到普通背景移除，并用一句话说明，例如：

当前暂时无法使用引导式背景移除，因此改为普通背景移除。

只有 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

---

示例

电商商品抠图

为网店、目录和市场平台创建透明背景的商品抠图：

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

批量移除背景

处理整个目录——为电商目录和素材管线批量移除背景：

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 端点参考——完整的端点文档，包含请求/响应格式
• Shell 客户端 (bria_client.sh)——单函数辅助工具：bria_call 处理身份验证、Base64、JSON 和轮询

相关技能

• ad-delayer——将完整的扁平广告拆分为可编辑图层，并保留文本为文本。当用户要求“把这则广告拆分为图层”，而非“抠出主体”时，请使用它代替此技能
• bria-ai——完整的 Bria API 访问：生成图像、编辑照片、替换/模糊背景、放大、重设风格、商品摄影，以及 20 多个其他端点
• image-utils——使用 Python Pillow 进行后期处理：调整大小、裁剪、合成、添加水印、转换格式