動画マスク

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

マスクは普通の動画なので、動画を接続できる場所ならどこにでも接続できます。主な組み合わせ先はマスク合成です。マスク合成はこのマスクを使って、ある動画の被写体を別の動画の上に配置します。マスクは、リライティングと差し替えのカスタム：マット動画モードで、マスク動画入力にも使えます。

使いどころ

• マスク合成と組み合わせて、被写体を新しいシーンに移します。たとえば、ダンサーをビーチに移します。
• クリップ内の製品や人物の背景を差し替えます。
• リライティングと差し替えのカスタム：マット動画モード用に、フレーム単位で正確なマット動画を作ります。
• マスク合成のマスクを反転を使って、1 つの被写体以外のすべてを残します。

クイックスタート

入力

出力

白が被写体を表します。静止画をマスクするノードであるマスク生成も同じ規則を使い、マスク合成もこの規則を前提にしています。

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

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

設定

制限

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

Nodaro が読み込めないクリップや、上限を超えるクリップは、料金がかかる前に拒否されます。長いクリップは、先に動画のトリミングでカットしてください。

クレジット

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

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 を試してください。
• マスクする前にトリミングします。 料金はクリップの長さで決まるので、動画のトリミングで必要な場面だけにカットしてください。
• クレジットを節約するなら SAM 3 を選びます。 SAM 3 は SAM 3.1 の半額です。SAM 3.1 は 1 回の処理で複数の対象を追跡し、より速く動作します。
• フレームの外に出た被写体も再び見つかります。 被写体が戻ってくると、マスクは再び被写体を追います。被写体がいないフレームは黒になります。

トラブルシューティング

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

クリップが長すぎるとして拒否される。 クリップが 30 fps で 5 分を超えているか、フレームレートの高いクリップがそれより長いものとして数えられています。動画のトリミングでカットして、もう一度実行してください。

セルフホスティング環境で実行が失敗する。 セルフホスティング環境では、動画マスクのモデルを動かすプロバイダーのキーが必要です。キーがないと、その旨を示すメッセージとともに実行が失敗します。プロバイダーキーを参照してください。

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 })。メディアとアップロードを参照してください。
• MCP： video_mask ツールは、video_url または video_asset_id、prompt、任意の threshold と provider を受け取ります。そのジョブ ID は、mask_composite の mask_asset_id として渡せます。MCP ツールリファレンスを参照してください。
• CLI： nodaro media video-mask <videoUrl> <prompt> [--threshold <n>] [--model sam-3.1|sam-3]。メディアと音声のコマンドを参照してください。

単体のノードを実行するとジョブを参照してください。