동영상 마스크

동영상 마스크 노드는 말로 설명한 대상을 동영상 전체에서 추적해 흑백 마스크 동영상을 반환합니다. 마스크는 클립과 길이와 프레임 속도가 같습니다. 모든 프레임에서 대상의 모든 픽셀은 흰색이고, 나머지는 모두 검은색입니다. 이 노드는 SAM 3.1 또는 SAM 3으로 실행됩니다.

마스크는 일반 동영상이므로 동영상을 연결할 수 있는 곳이면 어디에나 연결할 수 있습니다. 주로 함께 쓰는 노드는 마스크 합성입니다. 마스크 합성은 이 마스크를 사용해 한 동영상의 대상을 다른 동영상 위에 놓습니다. 마스크는 조명 변경 및 교체의 사용자 지정 — 매트 동영상 모드에서 마스크 동영상 입력에도 쓸 수 있습니다.

사용 시기

• 마스크 합성과 함께 대상을 새 장면으로 옮길 때. 예를 들어 댄서를 해변으로 옮깁니다.
• 클립에서 제품이나 사람 뒤의 배경을 바꿀 때.
• 조명 변경 및 교체의 사용자 지정 — 매트 동영상 모드에 쓸 프레임 단위로 정확한 매트 동영상을 만들 때.
• 마스크 합성의 마스크 반전으로 한 대상을 뺀 나머지를 모두 남길 때.

빠른 시작

입력

출력

흰색이 대상입니다. 정지 이미지를 마스크하는 노드인 마스크 생성도 같은 규칙을 쓰고, 마스크 합성도 이 규칙을 기대합니다.

회전된 휴대폰 클립, 가변 프레임 속도 클립, 긴 변이 1920픽셀을 넘는 클립은 먼저 바로 세운 방향, 일정한 프레임 속도, 최대 1920픽셀로 변환됩니다. 마스크는 그 크기가 됩니다. 마스크 합성은 마스크를 원래 크기의 영상에 맞게 늘이므로 따로 할 일은 없습니다.

마스크에는 어떤 요금제에서도 워터마크가 들어가지 않습니다.

설정

제한

• 길이: 30fps 기준으로 최대 5분 클립입니다.
• 프레임 속도: 모델이 프레임마다 작업하므로, 프레임 속도가 더 높은 클립은 그만큼 더 길게 계산됩니다. 60fps 클립은 실제 길이의 두 배로 계산되므로 최대 2.5분입니다.
• 긴 클립: 30fps 기준으로 60초보다 긴 클립은 60초 단위로 나뉘어 처리되고, 프레임 단위로 다시 이어집니다. 추적은 각 조각의 시작에서 새로 시작합니다. 마스크에는 설명과 일치하는 모든 것이 담기므로 이 경계는 거의 드러나지 않습니다.

Nodaro가 읽을 수 없는 클립이나 한도를 넘는 클립은 요금이 청구되기 전에 거부됩니다. 긴 클립은 먼저 동영상 자르기로 자르세요.

크레딧

요금은 30fps 기준 클립 길이와 모델에 따라 정해집니다. 길이는 초 단위로 올림하며, 그 길이를 포함하는 첫 번째 행의 요금이 청구됩니다.

30fps보다 빠른 클립은 그만큼 더 길게 계산됩니다. 예를 들어 24fps의 12초 클립은 12초로 계산되므로 SAM 3.1에서 160크레딧입니다. 60fps의 10초 클립은 20초로 계산되므로 SAM 3.1에서 314크레딧입니다.

실행 전에 노드는 워크플로가 클립 길이를 알려 줄 때만 그 길이를 압니다. 예를 들면 동영상 자르기의 구간이나 동영상 생성 노드에 설정한 길이입니다. 이때 노드는 그 길이의 30fps 기준 요금을 보여 줍니다. 그렇지 않으면 노드는 범위를 보여 줍니다. SAM 3.1에서는 553,108크레딧, SAM 3에서는 281,555크레딧입니다. 실제 실행에서는 항상 실제 프레임 속도를 포함해 클립을 측정하고, 해당 행의 요금이 청구됩니다.

팁

• 짧은 명사구를 쓰세요. 댄서에 대한 긴 문장보다 “the dancer”(댄서)가 더 잘 맞습니다.
• 일치하는 것이 없으면 임계값을 낮추세요. 설명을 다시 쓰기 전에 0.3을 시도해 보세요.
• 마스크하기 전에 자르세요. 요금은 클립 길이를 따르므로 동영상 자르기로 필요한 순간만 남기세요.
• 크레딧을 아끼려면 SAM 3을 선택하세요. SAM 3은 SAM 3.1의 절반 가격입니다. SAM 3.1은 한 번에 여러 대상을 추적하고 더 빠르게 실행됩니다.
• 화면 밖으로 나간 대상도 다시 찾습니다. 대상이 돌아오면 마스크가 다시 대상을 따라갑니다. 대상이 없는 프레임은 검은색입니다.

문제 해결

실행이 “No region matched the mask prompt on any frame” 메시지와 함께 실패합니다. 동영상에서 설명과 일치하는 것이 없었습니다. 크레딧은 환불됩니다. 설명을 단순한 명사구로 줄이거나 감지 임계값을 낮추세요.

클립이 너무 길다며 거부됩니다. 클립이 30fps 기준으로 5분보다 길거나, 프레임 속도가 더 높은 클립이 그보다 길게 계산되었습니다. 동영상 자르기로 자른 뒤 다시 실행하세요.

셀프 호스팅 설치에서 실행이 실패합니다. 셀프 호스팅 설치에서는 동영상 마스크의 모델을 실행하는 공급자의 키가 필요합니다. 키가 없으면 그 사실을 알려 주는 메시지와 함께 실행이 실패합니다. 공급자 키를 참고하세요.

API에서 사용

POST /v1/video-mask는 videoUrl, prompt(최대 500자, 쉼표로 여러 대상 추적), 선택 사항인 threshold(0.05~0.95, 기본값 0.5), 선택 사항인 provider(sam-3.1(기본값) 또는 sam-3)를 받습니다. 작업을 반환합니다. 완료된 작업의 출력에는 videoUrl(마스크), thumbnailUrl, width, height, frames, chunks, coverage가 담깁니다. 읽을 수 없는 클립이나 한도를 넘는 클립은 요금이 청구되기 전에 400 오류로 거부됩니다.

• SDK: videoMask({ videoUrl, prompt, threshold, provider }). 미디어 및 업로드를 참고하세요.
• MCP: video_mask 도구는 video_url 또는 video_asset_id, prompt, 선택 사항인 threshold와 provider를 받습니다. 이 작업 ID는 mask_composite에 mask_asset_id로 넘길 수 있습니다. MCP 도구 레퍼런스를 참고하세요.
• CLI: nodaro media video-mask <videoUrl> <prompt> [--threshold <n>] [--model sam-3.1|sam-3]. 미디어 및 보이스 명령을 참고하세요.

단일 노드 실행과 작업을 참고하세요.