video-remove-background

视频背景移除 — 透明视频和 Alpha 通道片段

移除任意视频的背景，获取带透明（alpha）或纯色背景的片段。由 Bria 的视频编辑流程提供支持，带来适用于商业用途、免版税、可用于生产环境的视频背景移除和主体抠图功能。

何时使用此技能

当用户想要：

• 移除视频背景 — “移除这个视频的背景”、“删除视频背景”
• 创建透明视频 — “无背景视频”、“透明 webm”、“alpha 通道视频”
• 移除绿幕 — “移除绿幕”、“对这个片段进行色度键控”、“抠除背景”
• 提取运动主体 — “隔离视频中的人物”、“从片段中抠出产品”、“视频抠图”
• 将背景替换为纯色 — “将主体放在白色背景上”、“黑色背景版本”
• 准备叠加素材 — “可叠加到我的网站上的透明片段”、“用于合成的视频抠像”
• 透明 GIF — “让这个 GIF 变透明”、“动画抠像”
• 批量移除视频背景 — “移除所有这些片段的背景”

何时不使用此技能

• 图像背景移除 → 使用 remove-background 技能（RMBG 2.0）
• 实时／流式背景移除（网络摄像头、直播）→ 使用 Bria 基于 WebSocket 的流式背景移除
• 生成或编辑图像 → 使用 bria-ai 技能

此技能只做一件事：移除视频文件的背景，生成透明或纯色背景片段。

---

设置 — 身份验证

进行任何 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 密钥，对 bearer 令牌进行内省：

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_video_call 发起 API 调用。它会在一次函数调用中处理本地文件上传（通过 Bria 的视频上传服务）、构建 JSON、调用 API 并进行异步轮询。API 密钥会自动从 ~/.bria/credentials 加载。

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

# Remove background from a local file — get a transparent video
RESULT_URL=$(bria_video_call "/path/to/clip.mp4")
echo "$RESULT_URL"  # → https://...output.webm

# Remove background from a URL
RESULT_URL=$(bria_video_call "https://example.com/clip.mp4")
echo "$RESULT_URL"

就是这样。 只需一次函数调用。视频任务是异步的，耗时比图像任务更长——该辅助函数最长会轮询 10 分钟。

输入

• 本地文件路径——自动通过 Bria 的视频上传服务上传（最大 1 GB），以获取临时 URL。
• 视频 URL——任何可公开访问的视频 URL。会直接传给 API。

支持的容器格式：.mp4、.mov、.webm、.avi、.gif。支持的编解码器：H.264、H.265 (HEVC)、VP9、AV1、PhotoJPEG。最长时长：60 秒。 分辨率最高可达 16K (16000x16000)。

选项

将额外的 JSON 字段作为第二个参数传入：

选项	值	默认值	说明
background_color	Transparent、Black、White、Gray、Red、Green、Blue、Yellow、Cyan、Magenta、Orange	Transparent	仅支持预定义名称——不支持十六进制值
output_container_and_codec	mp4_h264、mp4_h265、webm_vp9、mov_h265、mov_proresks、mkv_h264、mkv_h265、mkv_vp9、gif	webm_vp9	请参阅下方的 Alpha 支持规则
preserve_audio	true / false	—	保留输入视频的音轨

重要——Alpha 支持： 当 background_color: Transparent（默认值）时，输出预设必须支持 Alpha。服务端仅接受 Transparent 搭配 webm_vp9、mkv_vp9 或 mov_proresks；使用任何其他预设都会返回 422 Unprocessable Entity。如果用户要求输出 MP4，请设置纯色 background_color——MP4 不支持透明度。

已知问题（经验证于 2026 年 6 月）： gif 预设即使搭配纯色背景也会在服务端失败并返回 500 错误——请生成 webm_vp9，再使用 ffmpeg 转换（见下方示例）。mov_proresks 可以完成处理并返回 ProRes 4444，但测试中生成的文件缺少 Alpha 平面——依赖此格式前请先验证 Alpha，并优先使用 webm_vp9 / mkv_vp9 实现透明效果。

输出

处理后的视频 URL（默认格式：透明 .webm）。输出会保留输入视频的分辨率、宽高比和帧速率。短视频片段的处理时间约为 30–60 秒。下载结果即可保存到本地：

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

验证透明度： 对于 VP9 输出，即使存在 Alpha，ffprobe 也会报告 pix_fmt=yuv420p——VP9 会将 Alpha 存储在 WebM 侧信道中。请改为检查 ALPHA_MODE 标签，或使用 libvpx 解码：

ffprobe -v error -select_streams v:0 -show_entries stream_tags=alpha_mode -of default=noprint_wrappers=1 output.webm   # TAG:ALPHA_MODE=1 → 存在 Alpha
ffmpeg -c:v libvpx-vp9 -i output.webm -frames:v 1 frame.png   # frame.png 将为 rgba 格式

---

示例

用于网页叠加层的透明视频

source ~/.agents/skills/video-remove-background/references/code-examples/bria_video_client.sh
RESULT_URL=$(bria_video_call "/path/to/presenter.mp4" '"output_container_and_codec":"webm_vp9"')
curl -sL "$RESULT_URL" -o presenter_transparent.webm
echo "Transparent video saved to presenter_transparent.webm"

带纯白背景的 MP4（电子商务 / 社交媒体）

MP4 不支持 Alpha，因此请设置纯色背景：

source ~/.agents/skills/video-remove-background/references/code-examples/bria_video_client.sh
RESULT_URL=$(bria_video_call "/path/to/product_spin.mp4" '"background_color":"White","output_container_and_codec":"mp4_h264","preserve_audio":true')
curl -sL "$RESULT_URL" -o product_white_bg.mp4

用于视频编辑工作流的带 Alpha 的 MKV

source ~/.agents/skills/video-remove-background/references/code-examples/bria_video_client.sh
RESULT_URL=$(bria_video_call "https://example.com/talent.mov" '"output_container_and_codec":"mkv_vp9"')
curl -sL "$RESULT_URL" -o talent_alpha.mkv

透明动画 GIF

API 的 gif 输出预设目前会在服务端失败——请先获取透明 webm，再使用 ffmpeg 在本地转换：

source ~/.agents/skills/video-remove-background/references/code-examples/bria_video_client.sh
RESULT_URL=$(bria_video_call "/path/to/animation.mp4")
curl -sL "$RESULT_URL" -o cutout.webm
ffmpeg -c:v libvpx-vp9 -i cutout.webm \
  -filter_complex "[0:v]split[a][b];[a]palettegen=reserve_transparent=1[p];[b][p]paletteuse=alpha_threshold=128" \
  animation_transparent.gif

批量移除视频背景

source ~/.agents/skills/video-remove-background/references/code-examples/bria_video_client.sh
mkdir -p cutouts
for vid in videos/*.mp4; do
  [ -f "$vid" ] || continue
  name=$(basename "${vid%.*}")
  RESULT_URL=$(bria_video_call "$vid" '"output_container_and_codec":"webm_vp9"')
  if [ -n "$RESULT_URL" ]; then
    curl -sL "$RESULT_URL" -o "cutouts/${name}_transparent.webm"
    echo "Done: $name"
  else
    echo "Failed: $name" >&2
  fi
done

---

工作原理

1. 提供视频（本地文件路径或 URL）；本地文件会通过 Bria 的视频上传服务上传，以获取临时 URL
2. bria_video_call 会将视频发送至 Bria 的视频背景移除端点（POST /v2/video/edit/remove_background）
3. API 返回 HTTP 202 和 status_url；辅助函数每 5 秒轮询一次（最长 10 分钟）
4. 系统会对每一帧进行分割——背景像素会变为透明（或你选择的纯色）
5. 返回处理后的视频 URL，分辨率和帧速率与输入视频一致

常见错误

错误	原因	解决方法
422 Unprocessable Entity	使用非透明预设时，背景为透明	使用 webm_vp9/mkv_vp9/mov_proresks，或设置纯色 background_color
500 "list index out of range"（任务状态为 ERROR）	gif 输出预设（当前服务端存在故障）	输出为 webm_vp9，再用 ffmpeg 转换为 GIF（参见示例）
413 Payload Too Large	输入分辨率超过 16000x16000	降低输入视频的分辨率
带有时长提示的 400 错误	输入时长超过 60 秒	先将视频剪辑至 ≤ 60s
轮询超时	长视频或高分辨率任务仍在处理中	辅助工具会打印 status_url — 手动重新轮询，或提高 BRIA_POLL_ATTEMPTS / BRIA_POLL_INTERVAL

---

其他资源

• API 端点参考 — 完整的端点文档：remove_background、视频上传服务、状态轮询
• Shell 客户端 (bria_video_client.sh) — 辅助工具：bria_video_call（上传 + 调用 + 轮询）和 bria_video_upload（本地文件 → 临时 URL）

相关技能

• remove-background — 使用 RMBG 2.0 移除图像背景（透明 PNG、抠图）
• bria-ai — 完整的 Bria API 访问：生成图像、编辑照片、替换/模糊背景、放大图像，以及其他 20 多个端点
• image-utils — 使用 Python Pillow 对提取的帧进行后处理