# Máscara de vídeo

> Descreva um objeto e receba um vídeo de máscara em preto e branco que o acompanha ao longo do clipe, com SAM 3.1 ou SAM 3, em clipes de até 5 minutos.

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

O nó **Máscara de vídeo** acompanha ao longo de um vídeo o objeto que você descreve com palavras e retorna um vídeo de máscara em preto e branco. A máscara tem a mesma duração e a mesma taxa de quadros do clipe. Ela é branca em cada pixel do objeto, em cada quadro, e preta em todo o resto. O nó executa o SAM 3.1 ou o SAM 3.

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

A máscara é um vídeo comum, então você pode conectá-la a qualquer lugar que aceite um vídeo. O parceiro principal é o nó [**Composição por máscara**](https://nodaro.ai/docs/nodes/video/mask-composite), que usa a máscara para colocar o objeto de um vídeo sobre outro vídeo. A máscara também alimenta a entrada **Vídeo de máscara** do [**Reiluminar e trocar**](https://nodaro.ai/docs/nodes/video/relight-and-switch) no modo **Personalizado — vídeo matte**.

## Quando usar
- Mover um objeto para uma nova cena, por exemplo uma dançarina para uma praia, junto com o nó [**Composição por máscara**](https://nodaro.ai/docs/nodes/video/mask-composite).
- Trocar o fundo atrás de um produto ou de uma pessoa em um clipe.
- Fazer um vídeo matte preciso quadro a quadro para o modo **Personalizado — vídeo matte** do [**Reiluminar e trocar**](https://nodaro.ai/docs/nodes/video/relight-and-switch).
- Manter tudo, exceto um objeto, com **Inverter máscara** no nó Composição por máscara.

## Início rápido
### Adicione o nó
Pressione Tab no canvas e escolha **Vídeo › Continuação e novo estilo › Máscara de vídeo**.

### Conecte o vídeo
Conecte o clipe à entrada **Vídeo**, por exemplo a partir de um nó **Enviar vídeo**.

### Descreva o objeto
Abra o painel de configurações. Em **Descreva o que mascarar**, escreva uma expressão curta, como “the dancer” (a dançarina) ou “the red car” (o carro vermelho).

### Execute
Clique em **Executar** no nó. O vídeo de máscara aparece no nó. Conecte a saída **Máscara** à entrada **Máscara** de um nó **Composição por máscara**.

Workflow: O Máscara de vídeo contorna a dançarina no clipe de dança, e o Composição por máscara coloca a dançarina sobre o clipe da praia através dessa máscara.

- Enviar vídeo → Máscara de vídeo (Vídeo)
- Enviar vídeo → Composição por máscara (Primeiro plano)
- Enviar vídeo → Composição por máscara (Fundo)
- Máscara de vídeo → Composição por máscara (Máscara)

## Entradas
| Entrada | Aceita | O que faz |
| --- | --- | --- |
| **Vídeo** | Nós de vídeo, como **Enviar vídeo**, **Gerar vídeo** e **Cortar vídeo** | O clipe a mascarar. Obrigatória. |
| **Prompt** | Nós de texto, como **Texto**, ou um item de lista | Uma descrição do objeto. Um prompt conectado substitui a descrição do painel de configurações. Opcional. |

## Saídas
| Saída | O que contém |
| --- | --- |
| **Máscara** | O vídeo de máscara, um MP4 com a mesma duração e taxa de quadros do clipe. O branco é o objeto, e o preto é todo o resto. |

O branco indica o objeto. O [**Gerar máscara**](https://nodaro.ai/docs/nodes/image/generate-mask), o nó que mascara uma imagem fixa, usa a mesma regra, e o nó Composição por máscara espera essa regra.

Um clipe de celular girado, um clipe com taxa de quadros variável ou um clipe com mais de 1920 pixels no lado maior é primeiro convertido para a posição correta, com taxa de quadros constante e no máximo 1920 pixels. A máscara fica com esse tamanho. O nó Composição por máscara estica a máscara sobre o material em tamanho original, então você não precisa fazer nada.

A máscara nunca recebe marca d'água, em nenhum plano.

## Configurações
| Configuração | O que faz |
| --- | --- |
| **Descreva o que mascarar** | O que acompanhar, com até 500 caracteres. Uma expressão curta funciona melhor, como “the woman in the red coat” (a mulher de casaco vermelho) ou “the skateboard” (o skate). Separe vários objetos com vírgulas, por exemplo “person, dog”: a máscara fica branca onde qualquer um deles estiver. Obrigatória, a menos que um nó de texto esteja conectado a **Prompt**. |
| **Limite de detecção** | Quanta certeza o modelo precisa ter antes de marcar uma região, de 0,05 a 0,95, em passos de 0,05. O padrão é 0,5. Um valor menor encontra mais regiões, com menos precisão. Tente 0,3 quando nada corresponder. |
| **Modelo** | O **SAM 3.1**, o padrão, acompanha vários objetos em uma única passada e é mais rápido. O **SAM 3** custa metade do preço. |
| **Texto antes e depois** | Texto que sempre entra antes e depois da descrição. Ele fica oculto para quem usa o seu workflow como app. Veja [Texto antes e depois do prompt](https://nodaro.ai/docs/concepts/prompt-pre-post-text). |

## Limites
- **Duração:** clipes de até 5 minutos a 30 fps.
- **Taxa de quadros:** um clipe mais rápido conta proporcionalmente mais longo, porque o modelo trabalha quadro a quadro. Um clipe a 60 fps conta como o dobro da duração, então pode ter até 2,5 minutos.
- **Clipes longos:** um clipe com mais de 60 segundos a 30 fps é processado em partes de 60 segundos, e as partes são unidas quadro a quadro. O acompanhamento recomeça no início de cada parte. A máscara inclui tudo o que a descrição encontra, então isso raramente aparece.

Um clipe que o Nodaro não consegue ler, ou um clipe acima do limite, é recusado antes de qualquer cobrança. Corte um clipe longo com o [**Cortar vídeo**](https://nodaro.ai/docs/nodes/video/trim-video) primeiro.

## Créditos
O preço depende da duração do clipe, contada a 30 fps, e do modelo. A duração é arredondada para cima até o segundo inteiro, e a execução cobra a primeira linha que a cobre.

| Duração do clipe (a 30 fps) | SAM 3.1 | SAM 3 |
| --- | --- | --- |
| Até 5 segundos | 55 | 28 |
| Até 10 segundos | 105 | 53 |
| Até 15 segundos | 160 | 81 |
| Até 30 segundos | 314 | 158 |
| Até 60 segundos | 622 | 312 |
| Até 90 segundos | 935 | 468 |
| Até 2 minutos | 1.243 | 622 |
| Até 3 minutos | 1.865 | 933 |
| Até 4 minutos | 2.486 | 1.243 |
| Até 5 minutos | 3.108 | 1.555 |

Um clipe mais rápido que 30 fps conta proporcionalmente mais longo. Por exemplo, um clipe de 12 segundos a 24 fps conta como 12 segundos, então no SAM 3.1 custa 160 créditos. Um clipe de 10 segundos a 60 fps conta como 20 segundos, então no SAM 3.1 custa 314 créditos.

Antes de uma execução, o nó só sabe a duração do clipe quando o workflow informa, por exemplo pela janela de um **Cortar vídeo** ou pela duração definida em um nó de geração de vídeo. O nó então mostra o preço dessa duração a 30 fps. Caso contrário, o nó mostra uma faixa: de 55 a 3.108 créditos no SAM 3.1, e de 28 a 1.555 créditos no SAM 3. A execução sempre mede o clipe, incluindo a taxa de quadros real, e cobra essa linha.

## Dicas
- **Use uma expressão curta.** “the dancer” (a dançarina) funciona melhor que uma frase longa sobre a dançarina.
- **Diminua o limite quando nada corresponder.** Tente 0,3 antes de reescrever a descrição.
- **Corte antes de mascarar.** O preço depende da duração do clipe, então corte o clipe até o momento de que você precisa com o [**Cortar vídeo**](https://nodaro.ai/docs/nodes/video/trim-video).
- **Escolha o SAM 3 para economizar créditos.** O SAM 3 custa metade do preço do SAM 3.1. O SAM 3.1 acompanha vários objetos em uma única passada e é mais rápido.
- **Um objeto que sai do quadro é encontrado de novo.** Quando o objeto volta, a máscara volta a acompanhá-lo. Os quadros em que ele não aparece ficam pretos.

## Solução de problemas
**A execução falha com “No region matched the mask prompt on any frame”.** Nada no vídeo correspondeu à sua descrição. Os créditos são reembolsados. Encurte a descrição para uma expressão simples, ou diminua o **Limite de detecção**.

**O clipe é recusado por ser longo demais.** O clipe tem mais de 5 minutos a 30 fps, ou um clipe mais rápido conta como mais longo que isso. Corte-o com o [**Cortar vídeo**](https://nodaro.ai/docs/nodes/video/trim-video) e execute de novo.

**A execução falha em uma instalação auto-hospedada.** Em uma instalação auto-hospedada, o Máscara de vídeo precisa de uma chave do provedor que executa os modelos dele. Sem a chave, a execução falha com uma mensagem que explica isso. Veja [Chaves de provedor](https://nodaro.ai/docs/self-hosting/provider-keys).

## Pela API
O `POST /v1/video-mask` recebe `videoUrl`, `prompt` (até 500 caracteres; vírgulas acompanham vários objetos), um `threshold` opcional de 0,05 a 0,95 (padrão 0,5) e um `provider` opcional, `sam-3.1` (o padrão) ou `sam-3`. Ele retorna uma tarefa. A saída da tarefa concluída traz `videoUrl` (a máscara), `thumbnailUrl`, `width`, `height`, `frames`, `chunks` e `coverage`. Um clipe que não pode ser lido, ou um clipe acima do limite, é recusado com um erro 400 antes de qualquer cobrança.

- **SDK:** `videoMask({ videoUrl, prompt, threshold, provider })`. Veja [Mídia e uploads](https://nodaro.ai/docs/developers/sdk/media-and-uploads).
- **MCP:** a ferramenta `video_mask` recebe `video_url` ou `video_asset_id`, `prompt` e, opcionalmente, `threshold` e `provider`. O id da tarefa dela entra em `mask_composite` como `mask_asset_id`. Veja a [Referência das ferramentas MCP](https://nodaro.ai/docs/mcp/tools).
- **CLI:** `nodaro media video-mask <videoUrl> <prompt> [--threshold <n>] [--model sam-3.1|sam-3]`. Veja [Comandos de mídia e voz](https://nodaro.ai/docs/developers/cli/media-commands).

Veja [Executar um único nó](https://nodaro.ai/docs/developers/api/nodes) e [Tarefas](https://nodaro.ai/docs/developers/api/jobs).

## Perguntas frequentes

### O que o nó Máscara de vídeo faz?

O Máscara de vídeo acompanha ao longo de um vídeo o objeto que você descreve com palavras. Ele retorna um vídeo de máscara em preto e branco com a mesma duração e taxa de quadros: branco no objeto em cada quadro e preto em todo o resto.

### Qual modelo escolher, SAM 3.1 ou SAM 3?

O SAM 3.1 é o padrão. Ele acompanha vários objetos em uma única passada e é mais rápido. O SAM 3 custa metade do preço do SAM 3.1.

### Qual é a duração máxima do vídeo?

Até 5 minutos a 30 fps. Um clipe mais rápido conta proporcionalmente mais longo, então um clipe a 60 fps pode ter até 2,5 minutos. Um clipe acima do limite é recusado antes de qualquer cobrança.

### Posso acompanhar mais de um objeto?

Sim. Separe os objetos com vírgulas, por exemplo “person, dog”. A máscara fica branca onde qualquer um deles estiver.

### O que acontece quando o prompt não encontra nada?

Quando nada corresponde em nenhum quadro, a execução falha com “No region matched the mask prompt on any frame” e os créditos são reembolsados. Use uma descrição mais curta e simples, ou diminua o Limite de detecção.

### Como coloco o objeto mascarado em outro vídeo?

Conecte a saída Máscara à entrada Máscara de um nó Composição por máscara. Conecte o vídeo original à entrada Primeiro plano e a nova cena à entrada Fundo.