video-remove-background

# Video Remove Background — Transparent Videos & Alpha-Channel Clips Remove the background from any video and get a clip with a transparent (alpha) or solid-color background. Powered by Bria's video editing pipeline — commercially safe, royalty-free, production-ready video background removal and subject matting. ## When to Use This Skill Use this skill when the user wants to: - **Remove a background from a video** — "remove the background from this video", "delete the video background" - **Create a transparent video** — "video with no background", "transparent webm", "alpha channel video" - **Green screen removal** — "remove the green screen", "chroma-key this clip", "key out the background" - **Extract a moving subject** — "isolate the person in the video", "cut out the product from the clip", "video matting" - **Replace background with a solid color** — "put the subject on a white background", "black background version" - **Prepare overlays** — "transparent clip to layer over my website", "video cutout for compositing" - **Transparent GIFs** — "make this GIF transparent", "animated cutout" - **Batch video background removal** — "remove backgrounds from all these clips" ### When NOT to Use This Skill - **Image** background removal → use the **remove-background** skill (RMBG 2.0) - **Real-time / streaming** background removal (webcam, live feeds) → Bria's WebSocket-based [Streaming Background Removal](https://docs.bria.ai/streaming-rmbg) - **Generate or edit images** → use the **bria-ai** skill This skill does one thing: **remove backgrounds from video files to produce transparent or solid-color clips**. --- ## 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 Video Background Use `bria_video_call` for the API call. It handles local file upload (via Bria's video upload service), 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/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" ``` **That's it.** One function call. Video jobs are asynchronous and take longer than image jobs — the helper polls for up to 10 minutes. ### Input - **Local file path** — automatically uploaded via Bria's video upload service (max 1 GB) to get a temporary URL. - **Video URL** — any publicly accessible video URL. Passed directly to the API. Supported containers: `.mp4`, `.mov`, `.webm`, `.avi`, `.gif`. Supported codecs: H.264, H.265 (HEVC), VP9, AV1, PhotoJPEG. **Max duration: 60 seconds.** Resolution up to 16K (16000x16000). ### Options Pass extra JSON fields as a second argument: | Option | Values | Default | Notes | |--------|--------|---------|-------| | `background_color` | `Transparent`, `Black`, `White`, `Gray`, `Red`, `Green`, `Blue`, `Yellow`, `Cyan`, `Magenta`, `Orange` | `Transparent` | Predefined names only — hex values are not supported | | `output_container_and_codec` | `mp4_h264`, `mp4_h265`, `webm_vp9`, `mov_h265`, `mov_proresks`, `mkv_h264`, `mkv_h265`, `mkv_vp9`, `gif` | `webm_vp9` | See alpha-support rule below | | `preserve_audio` | `true` / `false` | — | Retain the input's audio track | > **Important — alpha support:** With `background_color: Transparent` (the default), the output preset must support alpha. The server accepts only **`webm_vp9`, `mkv_vp9`, or `mov_proresks`** with Transparent — any other preset returns **422 Unprocessable Entity**. When the user asks for an MP4 output, set a solid `background_color` — MP4 cannot hold transparency. > **Known issues (verified June 2026):** the `gif` preset fails server-side with a 500 error even with a solid background — produce `webm_vp9` and convert with ffmpeg instead (example below). `mov_proresks` completes and returns ProRes 4444, but in testing the file lacked an alpha plane — verify alpha before relying on it, and prefer `webm_vp9`/`mkv_vp9` for transparency. ### Output A URL to the processed video (default: transparent `.webm`). Output keeps the input's resolution, aspect ratio, and frame rate. Short clips process in roughly 30–60 seconds. Download the result to save it locally: ```bash curl -sL "$RESULT_URL" -o output.webm ``` > **Verifying transparency:** for VP9 outputs, `ffprobe` reports `pix_fmt=yuv420p` even when alpha is present — VP9 stores alpha in a WebM side channel. Check the `ALPHA_MODE` tag instead, or decode with libvpx: > ```bash > ffprobe -v error -select_streams v:0 -show_entries stream_tags=alpha_mode -of default=noprint_wrappers=1 output.webm # TAG:ALPHA_MODE=1 → has alpha > ffmpeg -c:v libvpx-vp9 -i output.webm -frames:v 1 frame.png # frame.png will be rgba > ``` --- ## Examples ### Transparent video for web overlays ```bash 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" ``` ### Solid white background MP4 (e-commerce / social) MP4 doesn't support alpha, so set a solid background color: ```bash 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 ``` ### MKV with alpha for video editing pipelines ```bash 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 ``` ### Transparent animated GIF The API's `gif` output preset currently fails server-side — get a transparent webm and convert locally with ffmpeg: ```bash 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 ``` ### Batch video background removal ```bash 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"