マスク合成

マスク合成ノードは、マスク動画を通して、前景の動画を背景の動画の上に重ねます。マスクが白い部分には前景が、黒い部分には背景が表示され、グレーの部分では両方が混ざります。マスク合成は AI モデルを使わないため、同じ入力からは常に同じ結果が得られます。

主な組み合わせ先は動画マスクです。動画マスクで被写体を元の映像の中でマスクし、その映像を前景に、別の動画を背景に使います。すると、被写体が新しいシーンの中に現れます。

マスク合成はプロバイダーキーを必要としないため、キーをまったく設定していない Community エディションを含む、すべてのエディションで動作します。

使いどころ

• 被写体を新しいシーンに移します。たとえば、ダンサーをビーチに移します。
• 製品やプレゼンターの背景を差し替えます。
• マスクを反転を使って被写体以外のすべてを残し、その場所に新しい被写体を入れます。
• 別のツールで作った白黒のマットを通して、2 本のクリップを合成します。

クイックスタート

入力

背景は、背景のフィットの設定に従って前景のフレームに合わせて調整され、前景より短い場合はループします。マスクは前景のフレームに合わせて引き伸ばされ、短い場合は最後のフレームのまま止まります。ほぼ黒は完全に背景、ほぼ白は完全に前景として扱われるため、圧縮によるノイズで薄い残像が出ることはありません。

出力

出力にウォーターマークが入ることはありません。

設定

制限

• 長さ： 前景は最長 300 秒です。

Nodaro が読み込めない前景や、300 秒を超える前景は、料金がかかる前に拒否されます。

クレジット

マスク合成は、出力の 5 秒ごと（開始した区間ごと）に 11 クレジットです。出力の長さは前景と同じです。1 回の実行は少なくとも 5 秒 1 区間として数えられます。3 秒の出力は 1 区間、10 秒の出力は 2 区間、61 秒の出力は 13 区間です。

実行前のノードが前景の長さを知っているのは、ワークフローから長さがわかる場合だけです。それ以外の場合、ノードは 5 秒 1 区間の料金から 300 秒の出力の料金までの範囲を表示します。実行時には、料金がかかる前に前景を測定し、実際の長さの分だけ支払います。

ヒント

• 先に前景をトリミングします。 出力の長さは前景と同じなので、動画のトリミングで必要な場面だけにカットしてください。
• 背景は前景と同じ長さ以上にします。 短い背景はループするため、つなぎ目が見えることがあります。
• 負の値で縁を削ります。 被写体のまわりに元の背景の細い線が見える場合は、拡大／縮小を小さな負の値にします。
• ぼかしを少し残します。 ぼかしを数ピクセルにすると、追跡したマスクの境界のギザギザが目立たなくなります。
• どんなマットでも使えます。 レンダリングした図形のアニメーションなど、別のツールで作った白黒またはグレースケールの動画もマスクとして使えます。

トラブルシューティング

被写体のまわりに元の背景の細い輪郭が残る。 拡大／縮小を小さな負の値にし、ぼかしを少し残してください。

被写体があるはずの場所に背景が表示される。 マスクの白黒が逆になっています。マスクを反転をオンにしてください。

出力に音声がない。 音声で選んだトラックが、その動画にありません。もう一方の動画の音声か、両方をミックスを選んでください。

背景に黒帯が入る、または切り抜かれる。 背景のフィットを変えてください。カバー（切り抜いて埋める）は切り抜き、全体を表示（レターボックス）は黒帯を付け、引き伸ばしはどちらもせずにフレームを埋めます。

API から

POST /v1/mask-composite は、foregroundUrl、backgroundUrl、maskUrl と、任意の invertMask、feather（0〜20）、grow（−10〜10）、backgroundFit（cover、contain、stretch のいずれか）、audioSource（foreground、background、mix、none のいずれか）を受け取ります。ジョブを返します。完了したジョブの出力には、videoUrl、thumbnailUrl、width、height、durationSec が含まれます。300 秒を超える前景は、料金がかかる前に 400 エラーで拒否されます。

• SDK： maskComposite({ foregroundUrl, backgroundUrl, maskUrl, invertMask, feather, grow, backgroundFit, audioSource })。メディアとアップロードを参照してください。
• MCP： mask_composite ツールは、3 本の動画をそれぞれ <name>_url または <name>_asset_id（foreground、background、mask）として受け取ります。そのため、video_mask のジョブ ID を mask_asset_id に使えます。設定は invert_mask、feather、grow、background_fit、audio_source です。MCP ツールリファレンスを参照してください。
• CLI： nodaro media mask-composite <foregroundUrl> <backgroundUrl> <maskUrl> [--invert] [--feather <px>] [--grow <px>] [--background-fit cover|contain|stretch] [--audio foreground|background|mix|none]。メディアと音声のコマンドを参照してください。

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