video-remove-background

Video Remove Background — 透明な動画とアルファチャンネル付きクリップ

動画の背景を削除して、透明（アルファ）または単色の背景を持つクリップを作成します。Bria の動画編集パイプラインを活用した、商用利用にも安心なロイヤリティフリーの、本番環境向け動画背景削除と被写体のマッティングです。

このスキルを使用する場面

ユーザーが次のことを希望する場合に、このスキルを使用してください。

• 動画から背景を削除する — 「この動画の背景を削除して」「動画の背景を消して」
• 透明な動画を作成する — 「背景なしの動画」「透明な WebM」「アルファチャンネル付き動画」
• グリーンスクリーンを削除する — 「グリーンスクリーンを削除して」「このクリップをクロマキー処理して」「背景をキーアウトして」
• 動く被写体を切り抜く — 「動画内の人物を分離して」「クリップから商品を切り抜いて」「動画のマッティング」
• 背景を単色に置き換える — 「被写体を白い背景に配置して」「黒背景版」
• オーバーレイを準備する — 「ウェブサイトに重ねる透明なクリップ」「合成用の動画の切り抜き」
• 透明な 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. サインインリンクを 1 つだけユーザーに表示します。 以下の内容だけを伝えてください。ほかの情報は加えないでください。

Bria アカウントを接続： ここをクリックしてサインイン あなたのコードは {user_code} です。すでに入力されています。

リンクを 2 つ表示しないでください。URL をそのまま別に表示しないでください。API レスポンスの verification_uri を使用しないでください。クリック可能なリンクは 1 つだけにしてください。

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 キーが保存され、以降の呼び出し用にキャッシュされています。次のセクションに進んでください。

---

動画の背景を削除する方法

API の呼び出しには bria_video_call を使用します。ローカルファイルのアップロード（Bria の動画アップロードサービス経由）、JSON の構築、API の呼び出し、非同期ポーリングを、1 回の関数呼び出しですべて処理します。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"

以上です。 関数を 1 回呼び出すだけです。動画ジョブは非同期で、画像ジョブより時間がかかるため、ヘルパーは最大 10 分間ポーリングします。

入力

• ローカルファイルのパス — Bria の動画アップロードサービス経由で自動的にアップロードされ、一時 URL が取得されます（最大 1 GB）。
• 動画 URL — 公開アクセス可能な任意の動画 URL。API に直接渡されます。

対応コンテナ：.mp4、.mov、.webm、.avi、.gif。対応コーデック：H.264、H.265（HEVC）、VP9、AV1、PhotoJPEG。最大長：60 秒。 解像度は最大 16K（16000x16000）です。

オプション

追加の JSON フィールドは第 2 引数として渡します。

オプション	値	デフォルト	備考
background_color	Transparent、Black、White、Gray、Red、Green、Blue、Yellow、Cyan、Magenta、Orange	Transparent	定義済みの名前のみ使用できます。16 進数値には対応していません
output_container_and_codec	mp4_h264、mp4_h265、webm_vp9、mov_h265、mov_proresks、mkv_h264、mkv_h265、mkv_vp9、gif	webm_vp9	以下のアルファサポートに関するルールを参照してください
preserve_audio	true / false	—	入力動画の音声トラックを保持します

重要 — アルファサポート： background_color: Transparent（デフォルト）を指定する場合、出力プリセットはアルファに対応している必要があります。サーバーが 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 を返しますが、テストではファイルにアルファプレーンがありませんでした。使用する前にアルファを確認し、透明度が必要な場合は webm_vp9／mkv_vp9 を優先してください。

出力

処理済み動画の URL が返されます（デフォルトは透明な .webm）。出力の解像度、アスペクト比、フレームレートは入力と同じです。短いクリップの処理には、およそ 30～60 秒かかります。結果をローカルに保存するには、ダウンロードしてください。

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

透明度の確認： VP9 出力では、アルファが存在する場合でも ffprobe は pix_fmt=yuv420p と報告します。VP9 はアルファを 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 → アルファあり
ffmpeg -c:v libvpx-vp9 -i output.webm -frames:v 1 frame.png   # frame.png は rgba になります

---

例

Web オーバーレイ用の透明な動画

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（E コマース／ソーシャルメディア用）

MP4 はアルファに対応していないため、背景色を単色に設定します。

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

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 は status_url とともに HTTP 202 を返し、ヘルパーは 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秒を超えています	まず動画を60秒以下にトリミングします
ポーリングのタイムアウト	長時間または高解像度のジョブを処理中です	ヘルパーに表示されるstatus_urlを手動で再ポーリングするか、BRIA_POLL_ATTEMPTS／BRIA_POLL_INTERVALを増やします

---

追加リソース

• API エンドポイントリファレンス — エンドポイントの完全なドキュメント：remove_background、動画アップロードサービス、ステータスのポーリング
• シェルクライアント（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で後処理