# Video Mask > Describe a subject in plain words and get a black-and-white mask video that tracks it through the clip, with SAM 3.1 or SAM 3, for clips up to 5 minutes. Source: https://nodaro.ai/docs/nodes/video/video-mask The **Video Mask** node tracks a subject that you describe in plain words through a video, and returns a black-and-white mask video. The mask has the same length and frame rate as the clip. It is white on every pixel of the subject in every frame, and black everywhere else. The node runs SAM 3.1 or SAM 3. - Found in: Video › Continue & Restyle - API type: `video-mask` The mask is an ordinary video, so you can connect it anywhere a video goes. Its main partner is [Mask Composite](https://nodaro.ai/docs/nodes/video/mask-composite), which uses the mask to place the subject from one video over another video. The mask also feeds the **Mask video** input of [Relight & Switch](https://nodaro.ai/docs/nodes/video/relight-and-switch) in **Custom** mode. ## When to use it - Move a subject into a new scene, for example a dancer onto a beach, together with [Mask Composite](https://nodaro.ai/docs/nodes/video/mask-composite). - Replace the background behind a product or a person in a clip. - Make a frame-accurate matte video for the **Custom** mode of [Relight & Switch](https://nodaro.ai/docs/nodes/video/relight-and-switch). - Keep everything except one subject, with **Invert mask** on Mask Composite. ## Quick start ### Add the node Press Tab on the canvas and choose **Video › Continue & Restyle › Video Mask**. ### Connect the video Wire the clip into the **Video** input, for example from an Upload Video node. ### Describe the subject Open the settings panel. Under **Describe what to mask**, write a short noun phrase, such as `the dancer` or `the red car`. ### Run it Click **Run** on the node. The mask video appears on the node. Wire its **Mask** output into the **Mask** input of a Mask Composite node. Workflow: Video Mask traces the dancer in the dance clip, and Mask Composite places the dancer over the beach clip through that mask. - Upload Video → Video Mask (video) - Upload Video → Mask Composite (foreground) - Upload Video → Mask Composite (background) - Video Mask → Mask Composite (mask) ## Inputs | Input | Accepts | What it does | | --- | --- | --- | | **Video** | Video nodes, such as Upload Video, Generate Video and Trim Video | The clip to mask. Required. | | **Prompt** | Text nodes, such as Text or a list item | A description of the subject. A wired prompt replaces the description in the settings panel. Optional. | ## Outputs | Output | What it carries | | --- | --- | | **Mask** | The mask video, an MP4 of the same length and frame rate as the clip. White is the subject, black is everything else. | White means the subject. [Generate Mask](https://nodaro.ai/docs/nodes/image/generate-mask), the node that masks a still image, uses the same rule, and Mask Composite expects it. A rotated phone clip, a clip with a variable frame rate, or a clip larger than 1920 pixels on its long side is first converted upright, at a constant frame rate and at most 1920 pixels. The mask has that size. Mask Composite stretches the mask over the full-size footage, so you do not need to do anything. The mask is never watermarked, on any plan. ## Settings | Setting | What it does | | --- | --- | | **Describe what to mask** | What to track, up to 500 characters. A short noun phrase works best, such as `the woman in the red coat` or `the skateboard`. Separate several subjects with commas, for example `person, dog`: the mask is white wherever any of them is. Required, unless a text node is wired into **Prompt**. | | **Detection threshold** | How sure the model must be before it marks a region, from 0.05 to 0.95 in steps of 0.05. The default is 0.5. A lower value finds more regions, with less precision. Try 0.3 when nothing matches. | | **Model** | **SAM 3.1**, the default, tracks several objects in one pass and runs faster. **SAM 3** costs half the price. | | **Pre & post text** | Text that is always added before and after the description. It is hidden from people who use your workflow as an app. See [Prompt pre and post text](https://nodaro.ai/docs/concepts/prompt-pre-post-text). | ## Limits - **Length:** clips up to 5 minutes at 30 fps. - **Frame rate:** a faster clip counts proportionally longer, because the model works frame by frame. A 60 fps clip counts as twice its length, so it can be up to 2.5 minutes long. - **Long clips:** a clip longer than 60 seconds at 30 fps is processed in 60-second pieces, and the pieces are joined frame by frame. Tracking starts again at the start of each piece. The mask holds everything the description matches, so this rarely shows. A clip that Nodaro cannot read, or a clip over the limit, is refused before anything is charged. Cut a long clip with [Trim Video](https://nodaro.ai/docs/nodes/video/trim-video) first. ## Credits The price follows the length of the clip, counted at 30 fps, and the model. The length is rounded up to a whole second, and the run is charged the first row that covers it. | Clip length (at 30 fps) | SAM 3.1 | SAM 3 | | --- | --- | --- | | Up to 5 seconds | 55 | 28 | | Up to 10 seconds | 105 | 53 | | Up to 15 seconds | 160 | 81 | | Up to 30 seconds | 314 | 158 | | Up to 60 seconds | 622 | 312 | | Up to 90 seconds | 935 | 468 | | Up to 2 minutes | 1,243 | 622 | | Up to 3 minutes | 1,865 | 933 | | Up to 4 minutes | 2,486 | 1,243 | | Up to 5 minutes | 3,108 | 1,555 | A clip faster than 30 fps counts proportionally longer. For example, a 12-second clip at 24 fps counts as 12 seconds, so on SAM 3.1 it costs 160 credits. A 10-second clip at 60 fps counts as 20 seconds, so on SAM 3.1 it costs 314 credits. Before a run, the node knows the clip's length only when the workflow tells it, for example from a Trim Video window or the duration set on a video generation node. The node then shows the price of that length at 30 fps. Otherwise the node shows a range, from 55 to 3,108 credits on SAM 3.1, and from 28 to 1,555 credits on SAM 3. The run itself always measures the clip, including its real frame rate, and is charged that row. ## Tips - **Use a short noun phrase.** `the dancer` works better than a long sentence about the dancer. - **Lower the threshold when nothing matches.** Try 0.3 before you rewrite the description. - **Trim before you mask.** The price follows the clip's length, so cut the clip to the moment you need with [Trim Video](https://nodaro.ai/docs/nodes/video/trim-video). - **Choose SAM 3 to save credits.** SAM 3 costs half the price of SAM 3.1. SAM 3.1 tracks several objects in one pass and runs faster. - **A subject that leaves the frame is found again.** When the subject comes back, the mask follows it again. The frames where it is absent are black. ## Troubleshooting **The run fails with "No region matched the mask prompt on any frame".** Nothing in the video matched your description. Your credits are refunded. Shorten the description to a plain noun phrase, or lower the **Detection threshold**. **The clip is refused as too long.** The clip is longer than 5 minutes at 30 fps, or a faster clip counts as longer than that. Cut it with [Trim Video](https://nodaro.ai/docs/nodes/video/trim-video) and run again. **The run fails on a self-hosted install.** On a self-hosted install, Video Mask needs a key for the provider that runs its models. Without the key, the run fails with a message that says so. See [Provider keys](https://nodaro.ai/docs/self-hosting/provider-keys). ## From the API `POST /v1/video-mask` takes `videoUrl`, `prompt` (up to 500 characters; commas track several subjects), an optional `threshold` from 0.05 to 0.95 (default 0.5) and an optional `provider`, `sam-3.1` (the default) or `sam-3`. It returns a job. The finished job's output carries `videoUrl` (the mask), `thumbnailUrl`, `width`, `height`, `frames`, `chunks` and `coverage`. A clip that cannot be read, or a clip over the limit, is refused with a 400 error before anything is charged. - **SDK:** `videoMask({ videoUrl, prompt, threshold, provider })`. See [Media and uploads](https://nodaro.ai/docs/developers/sdk/media-and-uploads). - **MCP:** the `video_mask` tool takes `video_url` or `video_asset_id`, `prompt`, and optional `threshold` and `provider`. Its job id chains into `mask_composite` as `mask_asset_id`. See the [MCP tools](https://nodaro.ai/docs/mcp/tools). - **CLI:** `nodaro media video-mask [--threshold ] [--model sam-3.1|sam-3]`. See [Media and voice commands](https://nodaro.ai/docs/developers/cli/media-commands). See [Run a single node](https://nodaro.ai/docs/developers/api/nodes) and [Jobs](https://nodaro.ai/docs/developers/api/jobs). ## Frequently asked questions ### What does the Video Mask node do? Video Mask tracks a subject that you describe in plain words through a video. It returns a black-and-white mask video of the same length and frame rate, white on the subject in every frame and black everywhere else. ### Which model should I choose, SAM 3.1 or SAM 3? SAM 3.1 is the default. It tracks several objects in one pass and runs faster. SAM 3 costs half the price of SAM 3.1. ### How long can the video be? Up to 5 minutes at 30 fps. A faster clip counts proportionally longer, so a 60 fps clip can be up to 2.5 minutes long. A clip over the limit is refused before anything is charged. ### Can I track more than one subject? Yes. Separate the subjects with commas, for example "person, dog". The mask is white wherever any of them is. ### What happens when the prompt matches nothing? When nothing matches on any frame, the run fails with "No region matched the mask prompt on any frame" and your credits are refunded. Use a shorter, plainer description, or lower the Detection threshold. ### How do I put the masked subject into another video? Wire the Mask output into the Mask input of a Mask Composite node. Wire the original video into its Foreground input and the new scene into its Background input.