Máscara de vídeo

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.

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, 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 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.
• 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.
• Manter tudo, exceto um objeto, com Inverter máscara no nó Composição por máscara.

Início rápido

Entradas

Saídas

O branco indica o objeto. O Gerar máscara, 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

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 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.

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.
• 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 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.

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.
• 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.
• CLI: nodaro media video-mask <videoUrl> <prompt> [--threshold <n>] [--model sam-3.1|sam-3]. Veja Comandos de mídia e voz.

Veja Executar um único nó e Tarefas.