# 動画マスク

> 言葉で説明した被写体を SAM 3.1 または SAM 3 で動画全体にわたって追跡し、白黒のマスク動画を出力します。最長 5 分のクリップに対応します。

Source: https://nodaro.ai/ja/docs/nodes/video/video-mask

**動画マスク**ノードは、言葉で説明した被写体を動画全体にわたって追跡し、白黒のマスク動画を返します。マスクの長さとフレームレートはクリップと同じです。どのフレームでも、被写体のピクセルは白、それ以外はすべて黒になります。このノードは SAM 3.1 または SAM 3 で動作します。

- Found in: Video › Continue & Restyle
- API type: `video-mask`

マスクは普通の動画なので、動画を接続できる場所ならどこにでも接続できます。主な組み合わせ先は[**マスク合成**](https://nodaro.ai/docs/nodes/video/mask-composite)です。マスク合成はこのマスクを使って、ある動画の被写体を別の動画の上に配置します。マスクは、[**リライティングと差し替え**](https://nodaro.ai/docs/nodes/video/relight-and-switch)の**カスタム：マット動画**モードで、**マスク動画**入力にも使えます。

## 使いどころ
- [**マスク合成**](https://nodaro.ai/docs/nodes/video/mask-composite)と組み合わせて、被写体を新しいシーンに移します。たとえば、ダンサーをビーチに移します。
- クリップ内の製品や人物の背景を差し替えます。
- [**リライティングと差し替え**](https://nodaro.ai/docs/nodes/video/relight-and-switch)の**カスタム：マット動画**モード用に、フレーム単位で正確なマット動画を作ります。
- マスク合成の**マスクを反転**を使って、1 つの被写体以外のすべてを残します。

## クイックスタート
### ノードを追加する
キャンバス上で Tab を押し、**動画 › 延長とスタイル変更 › 動画マスク**を選びます。

### 動画を接続する
クリップを**動画**入力に接続します。たとえば、**動画アップロード**ノードから接続します。

### 被写体を説明する
設定パネルを開きます。**マスクする対象を説明**に、短い名詞句を書きます（例：「the dancer」（ダンサー）、「the red car」（赤い車））。

### 実行する
ノードの**実行**をクリックします。マスク動画がノードに表示されます。**マスク**出力を、**マスク合成**ノードの**マスク**入力に接続します。

Workflow: 動画マスクがダンスのクリップの中のダンサーを追跡し、マスク合成がそのマスクを通してダンサーをビーチのクリップの上に配置します。

- 動画アップロード → 動画マスク (動画)
- 動画アップロード → マスク合成 (前景)
- 動画アップロード → マスク合成 (背景)
- 動画マスク → マスク合成 (マスク)

## 入力
| 入力 | 受け付けるもの | 役割 |
| --- | --- | --- |
| **動画** | **動画アップロード**、**動画生成**、**動画のトリミング**などの動画ノード | マスクするクリップです。必須です。 |
| **プロンプト** | **テキスト**などのテキストノード、またはリストの項目 | 被写体の説明です。接続したプロンプトは、設定パネルの説明より優先されます。任意です。 |

## 出力
| 出力 | 内容 |
| --- | --- |
| **マスク** | マスク動画です。クリップと同じ長さとフレームレートの MP4 です。白が被写体、黒がそれ以外のすべてです。 |

白が被写体を表します。静止画をマスクするノードである[**マスク生成**](https://nodaro.ai/docs/nodes/image/generate-mask)も同じ規則を使い、マスク合成もこの規則を前提にしています。

回転したスマートフォンのクリップ、可変フレームレートのクリップ、長辺が 1920 ピクセルを超えるクリップは、まず正しい向き、一定のフレームレート、最大 1920 ピクセルに変換されます。マスクはそのサイズになります。マスク合成はマスクを元のサイズの映像に合わせて引き伸ばすので、何もする必要はありません。

マスクには、どのプランでもウォーターマークが入りません。

## 設定
| 設定 | 役割 |
| --- | --- |
| **マスクする対象を説明** | 追跡する対象です。最大 500 文字です。「the woman in the red coat」（赤いコートの女性）や「the skateboard」（スケートボード）のような短い名詞句が最適です。複数の被写体はカンマで区切ります（例：「person, dog」）。マスクは、いずれかの被写体がある場所で白になります。**プロンプト**にテキストノードを接続していない場合は必須です。 |
| **検出しきい値** | 領域をマークする前に、モデルがどの程度確信している必要があるかを決めます。0.05〜0.95 の範囲で、0.05 刻みです。既定値は 0.5 です。値を下げるほど多くの領域が見つかりますが、精度は下がります。何も一致しないときは 0.3 を試してください。 |
| **モデル** | 既定の **SAM 3.1** は、1 回の処理で複数の対象を追跡し、より速く動作します。**SAM 3** は半額です。 |
| **前後のテキスト** | 説明の前後に常に追加されるテキストです。ワークフローをアプリとして使う人には表示されません。[プロンプトの前後のテキスト](https://nodaro.ai/docs/concepts/prompt-pre-post-text)を参照してください。 |

## 制限
- **長さ：** 30 fps で最長 5 分のクリップです。
- **フレームレート：** モデルはフレームごとに処理するため、フレームレートの高いクリップは、その分だけ長いものとして数えられます。60 fps のクリップは実際の 2 倍の長さとして数えられるので、最長 2.5 分です。
- **長いクリップ：** 30 fps で 60 秒を超えるクリップは、60 秒ずつに分けて処理され、フレーム単位でつなぎ合わされます。追跡は各区切りの先頭からやり直します。マスクには説明に一致するものがすべて含まれるため、この区切りが目立つことはほとんどありません。

Nodaro が読み込めないクリップや、上限を超えるクリップは、料金がかかる前に拒否されます。長いクリップは、先に[**動画のトリミング**](https://nodaro.ai/docs/nodes/video/trim-video)でカットしてください。

## クレジット
料金は、30 fps 換算のクリップの長さとモデルで決まります。長さは秒単位で切り上げられ、その長さが収まる最初の行の料金がかかります。

| クリップの長さ（30 fps 換算） | SAM 3.1 | SAM 3 |
| --- | --- | --- |
| 最長 5 秒 | 55 | 28 |
| 最長 10 秒 | 105 | 53 |
| 最長 15 秒 | 160 | 81 |
| 最長 30 秒 | 314 | 158 |
| 最長 60 秒 | 622 | 312 |
| 最長 90 秒 | 935 | 468 |
| 最長 2 分 | 1,243 | 622 |
| 最長 3 分 | 1,865 | 933 |
| 最長 4 分 | 2,486 | 1,243 |
| 最長 5 分 | 3,108 | 1,555 |

30 fps より速いクリップは、その分だけ長いものとして数えられます。たとえば、24 fps で 12 秒のクリップは 12 秒として数えられるので、SAM 3.1 では 160 クレジットです。60 fps で 10 秒のクリップは 20 秒として数えられるので、SAM 3.1 では 314 クレジットです。

実行前のノードがクリップの長さを知っているのは、ワークフローから長さがわかる場合だけです。たとえば、**動画のトリミング**の範囲や、動画生成ノードに設定した長さです。その場合、ノードはその長さの 30 fps 換算の料金を表示します。それ以外の場合、ノードは範囲を表示します。SAM 3.1 では 55 〜 3,108 クレジット、SAM 3 では 28 〜 1,555 クレジットです。実行時には、実際のフレームレートを含めて必ずクリップを測定し、該当する行の料金がかかります。

## ヒント
- **短い名詞句を使います。** 「the dancer」（ダンサー）のほうが、ダンサーについての長い文よりうまくいきます。
- **何も一致しないときはしきい値を下げます。** 説明を書き直す前に 0.3 を試してください。
- **マスクする前にトリミングします。** 料金はクリップの長さで決まるので、[**動画のトリミング**](https://nodaro.ai/docs/nodes/video/trim-video)で必要な場面だけにカットしてください。
- **クレジットを節約するなら SAM 3 を選びます。** SAM 3 は SAM 3.1 の半額です。SAM 3.1 は 1 回の処理で複数の対象を追跡し、より速く動作します。
- **フレームの外に出た被写体も再び見つかります。** 被写体が戻ってくると、マスクは再び被写体を追います。被写体がいないフレームは黒になります。

## トラブルシューティング
**実行が「No region matched the mask prompt on any frame」で失敗する。** 動画の中に説明と一致するものがありませんでした。クレジットは返還されます。説明を短くわかりやすい名詞句にするか、**検出しきい値**を下げてください。

**クリップが長すぎるとして拒否される。** クリップが 30 fps で 5 分を超えているか、フレームレートの高いクリップがそれより長いものとして数えられています。[**動画のトリミング**](https://nodaro.ai/docs/nodes/video/trim-video)でカットして、もう一度実行してください。

**セルフホスティング環境で実行が失敗する。** セルフホスティング環境では、動画マスクのモデルを動かすプロバイダーのキーが必要です。キーがないと、その旨を示すメッセージとともに実行が失敗します。[プロバイダーキー](https://nodaro.ai/docs/self-hosting/provider-keys)を参照してください。

## API から
`POST /v1/video-mask` は、`videoUrl`、`prompt`（最大 500 文字。カンマで区切ると複数の被写体を追跡）、任意の `threshold`（0.05〜0.95、既定値 0.5）、任意の `provider`（`sam-3.1`（既定）または `sam-3`）を受け取ります。ジョブを返します。完了したジョブの出力には、`videoUrl`（マスク）、`thumbnailUrl`、`width`、`height`、`frames`、`chunks`、`coverage` が含まれます。読み込めないクリップや、上限を超えるクリップは、料金がかかる前に 400 エラーで拒否されます。

- **SDK：** `videoMask({ videoUrl, prompt, threshold, provider })`。[メディアとアップロード](https://nodaro.ai/docs/developers/sdk/media-and-uploads)を参照してください。
- **MCP：** `video_mask` ツールは、`video_url` または `video_asset_id`、`prompt`、任意の `threshold` と `provider` を受け取ります。そのジョブ ID は、`mask_composite` の `mask_asset_id` として渡せます。[MCP ツールリファレンス](https://nodaro.ai/docs/mcp/tools)を参照してください。
- **CLI：** `nodaro media video-mask <videoUrl> <prompt> [--threshold <n>] [--model sam-3.1|sam-3]`。[メディアと音声のコマンド](https://nodaro.ai/docs/developers/cli/media-commands)を参照してください。

[単体のノードを実行する](https://nodaro.ai/docs/developers/api/nodes)と[ジョブ](https://nodaro.ai/docs/developers/api/jobs)を参照してください。

## よくある質問

### 動画マスクノードは何をしますか？

動画マスクは、言葉で説明した被写体を動画全体にわたって追跡します。同じ長さとフレームレートの白黒のマスク動画を返します。どのフレームでも被写体は白、それ以外は黒になります。

### SAM 3.1 と SAM 3 のどちらを選べばよいですか？

既定は SAM 3.1 です。SAM 3.1 は 1 回の処理で複数の対象を追跡し、より速く動作します。SAM 3 は SAM 3.1 の半額です。

### 動画はどのくらいの長さまで使えますか？

30 fps で最長 5 分です。フレームレートの高いクリップは、その分だけ長いものとして数えられます。そのため、60 fps のクリップは最長 2.5 分です。上限を超えるクリップは、料金がかかる前に拒否されます。

### 複数の被写体を追跡できますか？

はい。被写体をカンマで区切って書きます（例：「person, dog」）。マスクは、いずれかの被写体がある場所で白になります。

### プロンプトに何も一致しない場合はどうなりますか？

どのフレームでも何も一致しない場合、実行は「No region matched the mask prompt on any frame」で失敗し、クレジットは返還されます。説明を短くわかりやすくするか、検出しきい値を下げてください。

### マスクした被写体を別の動画に入れるにはどうすればよいですか？

マスク出力をマスク合成ノードのマスク入力に接続します。元の動画を前景入力に、新しいシーンを背景入力に接続します。