# Composição por máscara > Coloque um vídeo de primeiro plano sobre um fundo através de um vídeo de máscara, com inversão, suavização e áudio. Funciona em todas as edições, sem chave. Source: https://nodaro.ai/pt-BR/docs/nodes/video/mask-composite O nó **Composição por máscara** coloca um vídeo de primeiro plano sobre um vídeo de fundo através de um vídeo de máscara. Onde a máscara é branca, você vê o primeiro plano. Onde a máscara é preta, você vê o fundo, e o cinza mistura os dois. O Composição por máscara não executa nenhum modelo de IA, então as mesmas entradas sempre dão o mesmo resultado. - Found in: Video › Cut & Assemble - API type: `mask-composite` O parceiro natural é o nó [**Máscara de vídeo**](https://nodaro.ai/docs/nodes/video/video-mask). Mascare um objeto no próprio material com o Máscara de vídeo e depois use esse material como primeiro plano e qualquer outro vídeo como fundo. O objeto então aparece na nova cena. O Composição por máscara não precisa de chave de provedor, então funciona em todas as edições, incluindo uma instalação da Community Edition sem nenhuma chave. ## Quando usar - Mover um objeto para uma nova cena, por exemplo uma dançarina para uma praia. - Trocar o fundo atrás de um produto ou de um apresentador. - Manter tudo, exceto o objeto, com **Inverter máscara**, e colocar um novo objeto no lugar dele. - Combinar dois clipes através de um matte em preto e branco feito em outra ferramenta. ## Início rápido ### Adicione o nó Pressione Tab no canvas e escolha **Vídeo › Corte e montagem › Composição por máscara**. ### Conecte os três vídeos Conecte o material com o objeto a **Primeiro plano**, a nova cena a **Fundo** e o vídeo de máscara a **Máscara**, por exemplo a saída **Máscara** de um nó [**Máscara de vídeo**](https://nodaro.ai/docs/nodes/video/video-mask). ### Ajuste a borda Abra o painel de configurações. Mantenha a **Suavização** em 2 pixels para uma borda suave, e coloque **Expandir / reduzir** abaixo de 0 se uma linha fina do fundo antigo aparecer em volta do objeto. ### Execute Clique em **Executar** no nó. O vídeo composto aparece no nó. Workflow: O Máscara de vídeo contorna a dançarina, e o Composição por máscara mostra a dançarina onde a máscara é branca e a praia em todo o resto. - 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 | | --- | --- | --- | | **Primeiro plano** | Nós de vídeo, como **Enviar vídeo** e **Gerar vídeo** | O material cuja região branca na máscara é mantida. O resultado tem o tamanho, a taxa de quadros e a duração dele. Obrigatória. | | **Fundo** | Nós de vídeo | O vídeo mostrado onde a máscara é preta. Obrigatória. | | **Máscara** | Nós de vídeo, como **Máscara de vídeo** | O vídeo de máscara. O branco mostra o primeiro plano, e o preto mostra o fundo. Obrigatória. | O fundo é ajustado ao quadro do primeiro plano, conforme a configuração **Ajuste do fundo**, e entra em loop quando é mais curto que o primeiro plano. A máscara é esticada até o quadro do primeiro plano e mantém o último quadro quando é mais curta. Quase preto conta como fundo total e quase branco como primeiro plano total, então o ruído de compressão nunca deixa um fantasma fraco. ## Saídas | Saída | O que contém | | --- | --- | | **Vídeo** | O vídeo composto, um MP4 com o tamanho, a taxa de quadros e a duração do primeiro plano. Ele tem som quando a configuração **Áudio** mantém uma faixa. | O resultado nunca recebe marca d'água. ## Configurações | Configuração | O que faz | | --- | --- | | **Inverter máscara** | Troca os lados: o branco mostra o fundo e o preto mostra o primeiro plano. Use para manter tudo, exceto o objeto. Desligada por padrão. | | **Suavização** | Suaviza a borda da máscara, de 0 a 20 pixels. O padrão é 2. Com 0, a borda fica nítida. Alguns pixels escondem os degraus na borda de uma máscara acompanhada. | | **Expandir / reduzir** | Expande (valor positivo) ou reduz (valor negativo) a área branca, de −10 a 10 pixels, antes de a borda ser suavizada. O padrão é 0. Um valor negativo apara uma linha fina do fundo antigo em volta do objeto. | | **Ajuste do fundo** | Como o fundo preenche o quadro do primeiro plano. **Preencher (cortar para preencher)**, o padrão, preenche o quadro e corta o que sobra. **Conter (com faixas)** mostra o fundo inteiro com faixas pretas. **Esticar** estica o fundo até o quadro. | | **Áudio** | Qual som o resultado tem. **Áudio do primeiro plano** é o padrão. As outras opções são **Áudio do fundo**, **Mixar os dois**, no mesmo nível, e **Sem áudio**. Quando a faixa escolhida não existe, o resultado fica sem som. **Mixar os dois** com só uma faixa usa essa faixa. | ## Limites - **Duração:** um primeiro plano de até 300 segundos. Um primeiro plano que o Nodaro não consegue ler, ou um com mais de 300 segundos, é recusado antes de qualquer cobrança. ## Créditos O Composição por máscara custa 11 créditos a cada 5 segundos iniciados do resultado. O resultado tem a duração do primeiro plano. Uma execução conta pelo menos uma etapa de 5 segundos: um resultado de 3 segundos conta uma etapa, um de 10 segundos conta duas, e um de 61 segundos conta 13. Antes de uma execução, o nó só sabe a duração do primeiro plano quando o workflow informa. Caso contrário, o nó mostra uma faixa, do preço de uma etapa de 5 segundos até o preço de um resultado de 300 segundos. A execução mede o primeiro plano antes de qualquer cobrança, e você paga pela duração real. ## Dicas - **Corte o primeiro plano antes.** O resultado tem a duração do primeiro plano, então corte-o até o momento de que você precisa com o [**Cortar vídeo**](https://nodaro.ai/docs/nodes/video/trim-video). - **Use um fundo pelo menos tão longo quanto o primeiro plano.** Um fundo mais curto entra em loop, o que pode mostrar um salto visível. - **Apare halos com um valor negativo.** Coloque **Expandir / reduzir** em um valor negativo pequeno quando uma linha fina do fundo antigo aparecer em volta do objeto. - **Mantenha um pouco de suavização.** Alguns pixels de **Suavização** escondem os degraus na borda de uma máscara acompanhada. - **Qualquer matte funciona.** Um vídeo em preto e branco ou em tons de cinza de outra ferramenta, como uma animação de formas renderizada, funciona como máscara. ## Solução de problemas **O objeto fica com um contorno fino do fundo antigo.** Coloque **Expandir / reduzir** em um valor negativo pequeno e mantenha um pouco de **Suavização**. **O fundo aparece onde o objeto deveria estar.** A máscara tem a polaridade oposta. Ative **Inverter máscara**. **O resultado não tem som.** A faixa escolhida em **Áudio** não existe nesse vídeo. Escolha o áudio do outro vídeo, ou **Mixar os dois**. **O fundo tem faixas pretas ou está cortado.** Mude o **Ajuste do fundo**. **Preencher (cortar para preencher)** corta, **Conter (com faixas)** adiciona faixas, e **Esticar** preenche o quadro sem nenhum dos dois. ## Pela API O `POST /v1/mask-composite` recebe `foregroundUrl`, `backgroundUrl` e `maskUrl`, com `invertMask`, `feather` (0 a 20), `grow` (−10 a 10), `backgroundFit` (`cover`, `contain` ou `stretch`) e `audioSource` (`foreground`, `background`, `mix` ou `none`) opcionais. Ele retorna uma tarefa. A saída da tarefa concluída traz `videoUrl`, `thumbnailUrl`, `width`, `height` e `durationSec`. Um primeiro plano com mais de 300 segundos é recusado com um erro 400 antes de qualquer cobrança. - **SDK:** `maskComposite({ foregroundUrl, backgroundUrl, maskUrl, invertMask, feather, grow, backgroundFit, audioSource })`. Veja [Mídia e uploads](https://nodaro.ai/docs/developers/sdk/media-and-uploads). - **MCP:** a ferramenta `mask_composite` recebe cada um dos três vídeos como `_url` ou `_asset_id` (`foreground`, `background`, `mask`), então o id de uma tarefa `video_mask` pode ser o `mask_asset_id`. As configurações são `invert_mask`, `feather`, `grow`, `background_fit` e `audio_source`. Veja a [Referência das ferramentas MCP](https://nodaro.ai/docs/mcp/tools). - **CLI:** `nodaro media mask-composite [--invert] [--feather ] [--grow ] [--background-fit cover|contain|stretch] [--audio foreground|background|mix|none]`. 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ó Composição por máscara faz? O Composição por máscara junta três vídeos em um. Onde a máscara é branca, você vê o vídeo de primeiro plano. Onde a máscara é preta, você vê o vídeo de fundo, e o cinza mistura os dois. ### De onde vem o vídeo de máscara? A origem mais comum é um nó Máscara de vídeo, que acompanha ao longo do vídeo de primeiro plano o objeto que você descreve. Qualquer vídeo em preto e branco ou em tons de cinza funciona como máscara, por exemplo um matte feito em outra ferramenta. ### E se o fundo for mais curto ou tiver outro tamanho? O resultado segue o tamanho, a taxa de quadros e a duração do primeiro plano. O fundo é ajustado ao quadro do primeiro plano e entra em loop quando é mais curto. A máscara é esticada até o quadro e mantém o último quadro quando é mais curta. ### Quanto custa o Composição por máscara? O Composição por máscara custa 11 créditos a cada 5 segundos iniciados do resultado, que tem a duração do primeiro plano. Um primeiro plano pode ter até 300 segundos. ### O Composição por máscara precisa de uma chave de API em uma instalação auto-hospedada? Não. O Composição por máscara não executa nenhum modelo de IA e não precisa de chave de provedor, então funciona em todas as edições, incluindo a Community Edition sem nenhuma chave.