# 동영상 마스크

> 말로 설명한 대상을 SAM 3.1 또는 SAM 3으로 클립 전체에서 추적해 흑백 마스크 동영상을 만듭니다. 최대 5분 클립까지 지원합니다.

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

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

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

마스크는 일반 동영상이므로 동영상을 연결할 수 있는 곳이면 어디에나 연결할 수 있습니다. 주로 함께 쓰는 노드는 [마스크 합성](https://nodaro.ai/docs/nodes/video/mask-composite)입니다. 마스크 합성은 이 마스크를 사용해 한 동영상의 대상을 다른 동영상 위에 놓습니다. 마스크는 [조명 변경 및 교체](https://nodaro.ai/docs/nodes/video/relight-and-switch)의 **사용자 지정 — 매트 동영상** 모드에서 **마스크 동영상** 입력에도 쓸 수 있습니다.

## 사용 시기
- [마스크 합성](https://nodaro.ai/docs/nodes/video/mask-composite)과 함께 대상을 새 장면으로 옮길 때. 예를 들어 댄서를 해변으로 옮깁니다.
- 클립에서 제품이나 사람 뒤의 배경을 바꿀 때.
- [조명 변경 및 교체](https://nodaro.ai/docs/nodes/video/relight-and-switch)의 **사용자 지정 — 매트 동영상** 모드에 쓸 프레임 단위로 정확한 매트 동영상을 만들 때.
- 마스크 합성의 **마스크 반전**으로 한 대상을 뺀 나머지를 모두 남길 때.

## 빠른 시작
### 노드 추가
캔버스에서 Tab을 누르고 **동영상 › 연장 및 스타일 변환 › 동영상 마스크**를 선택하세요.

### 동영상 연결
클립을 **동영상** 입력에 연결하세요. 예를 들어 **동영상 업로드** 노드에서 연결합니다.

### 대상 설명
설정 패널을 여세요. **마스크할 대상 설명**에 짧은 명사구를 쓰세요. 예를 들면 “the dancer”(댄서)나 “the red car”(빨간 자동차)입니다.

### 실행
노드에서 **실행**을 클릭하세요. 마스크 동영상이 노드에 나타납니다. **마스크** 출력을 **마스크 합성** 노드의 **마스크** 입력에 연결하세요.

Workflow: 동영상 마스크가 댄스 클립 속 댄서를 추적하고, 마스크 합성이 그 마스크를 통해 댄서를 해변 클립 위에 놓습니다.

- 동영상 업로드 → 동영상 마스크 (동영상)
- 동영상 업로드 → 마스크 합성 (전경)
- 동영상 업로드 → 마스크 합성 (배경)
- 동영상 마스크 → 마스크 합성 (마스크)

## 입력
| 입력 | 받는 것 | 하는 일 |
| --- | --- | --- |
| **동영상** | **동영상 업로드**, **동영상 생성**, **동영상 자르기** 같은 동영상 노드 | 마스크할 클립입니다. 필수입니다. |
| **프롬프트** | **텍스트** 같은 텍스트 노드 또는 목록 항목 | 대상에 대한 설명입니다. 연결한 프롬프트는 설정 패널의 설명을 대신합니다. 선택 사항입니다. |

## 출력
| 출력 | 담고 있는 것 |
| --- | --- |
| **마스크** | 마스크 동영상입니다. 클립과 길이와 프레임 속도가 같은 MP4입니다. 흰색은 대상, 검은색은 나머지 모두입니다. |

흰색이 대상입니다. 정지 이미지를 마스크하는 노드인 [마스크 생성](https://nodaro.ai/docs/nodes/image/generate-mask)도 같은 규칙을 쓰고, 마스크 합성도 이 규칙을 기대합니다.

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

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

## 설정
| 설정 | 하는 일 |
| --- | --- |
| **마스크할 대상 설명** | 추적할 대상이며 최대 500자입니다. “the woman in the red coat”(빨간 코트를 입은 여성)나 “the skateboard”(스케이트보드) 같은 짧은 명사구가 가장 좋습니다. 여러 대상은 쉼표로 구분하세요. 예를 들면 “person, dog”입니다. 마스크는 대상 중 하나라도 있는 곳에서 흰색이 됩니다. **프롬프트**에 텍스트 노드를 연결하지 않았다면 필수입니다. |
| **감지 임계값** | 모델이 영역을 표시하기 전에 얼마나 확신해야 하는지 정합니다. 0.05~0.95 사이에서 0.05 단위로 정하며, 기본값은 0.5입니다. 값이 낮을수록 더 많은 영역을 찾지만 정확도는 낮아집니다. 일치하는 것이 없으면 0.3을 시도해 보세요. |
| **모델** | 기본값인 **SAM 3.1**은 한 번에 여러 대상을 추적하고 더 빠르게 실행됩니다. **SAM 3**은 절반 가격입니다. |
| **앞뒤 텍스트** | 설명 앞뒤에 항상 붙는 텍스트입니다. 워크플로를 앱으로 쓰는 사람에게는 보이지 않습니다. [프롬프트 앞뒤 텍스트](https://nodaro.ai/docs/concepts/prompt-pre-post-text)를 참고하세요. |

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

Nodaro가 읽을 수 없는 클립이나 한도를 넘는 클립은 요금이 청구되기 전에 거부됩니다. 긴 클립은 먼저 [동영상 자르기](https://nodaro.ai/docs/nodes/video/trim-video)로 자르세요.

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

| 클립 길이(30fps 기준) | SAM 3.1 | SAM 3 |
| --- | --- | --- |
| 최대 5초 | 55 | 28 |
| 최대 10초 | 105 | 53 |
| 최대 15초 | 160 | 81 |
| 최대 30초 | 314 | 158 |
| 최대 60초 | 622 | 312 |
| 최대 90초 | 935 | 468 |
| 최대 2분 | 1,243 | 622 |
| 최대 3분 | 1,865 | 933 |
| 최대 4분 | 2,486 | 1,243 |
| 최대 5분 | 3,108 | 1,555 |

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

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

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

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

**클립이 너무 길다며 거부됩니다.** 클립이 30fps 기준으로 5분보다 길거나, 프레임 속도가 더 높은 클립이 그보다 길게 계산되었습니다. [동영상 자르기](https://nodaro.ai/docs/nodes/video/trim-video)로 자른 뒤 다시 실행하세요.

**셀프 호스팅 설치에서 실행이 실패합니다.** 셀프 호스팅 설치에서는 동영상 마스크의 모델을 실행하는 공급자의 키가 필요합니다. 키가 없으면 그 사실을 알려 주는 메시지와 함께 실행이 실패합니다. [공급자 키](https://nodaro.ai/docs/self-hosting/provider-keys)를 참고하세요.

## 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 })`. [미디어 및 업로드](https://nodaro.ai/docs/developers/sdk/media-and-uploads)를 참고하세요.
- **MCP:** `video_mask` 도구는 `video_url` 또는 `video_asset_id`, `prompt`, 선택 사항인 `threshold`와 `provider`를 받습니다. 이 작업 ID는 `mask_composite`에 `mask_asset_id`로 넘길 수 있습니다. [MCP 도구 레퍼런스](https://nodaro.ai/docs/mcp/tools)를 참고하세요.
- **CLI:** `nodaro media video-mask <videoUrl> <prompt> [--threshold <n>] [--model sam-3.1|sam-3]`. [미디어 및 보이스 명령](https://nodaro.ai/docs/developers/cli/media-commands)을 참고하세요.

[단일 노드 실행](https://nodaro.ai/docs/developers/api/nodes)과 [작업](https://nodaro.ai/docs/developers/api/jobs)을 참고하세요.

## 자주 묻는 질문

### 동영상 마스크 노드는 무엇을 하나요?

동영상 마스크는 말로 설명한 대상을 동영상 전체에서 추적합니다. 길이와 프레임 속도가 같은 흑백 마스크 동영상을 반환하며, 모든 프레임에서 대상은 흰색, 나머지는 모두 검은색입니다.

### SAM 3.1과 SAM 3 중 무엇을 선택해야 하나요?

기본값은 SAM 3.1입니다. SAM 3.1은 한 번에 여러 대상을 추적하고 더 빠르게 실행됩니다. SAM 3은 SAM 3.1의 절반 가격입니다.

### 동영상은 얼마나 길 수 있나요?

30fps 기준으로 최대 5분입니다. 프레임 속도가 더 높은 클립은 그만큼 더 길게 계산되므로, 60fps 클립은 최대 2.5분입니다. 한도를 넘는 클립은 요금이 청구되기 전에 거부됩니다.

### 여러 대상을 추적할 수 있나요?

네. 대상을 쉼표로 구분하세요. 예를 들면 “person, dog”입니다. 마스크는 대상 중 하나라도 있는 곳에서 흰색이 됩니다.

### 프롬프트와 일치하는 것이 없으면 어떻게 되나요?

어느 프레임에서도 일치하는 것이 없으면 실행이 “No region matched the mask prompt on any frame” 메시지와 함께 실패하고 크레딧이 환불됩니다. 설명을 더 짧고 단순하게 바꾸거나 감지 임계값을 낮추세요.

### 마스크한 대상을 다른 동영상에 넣으려면 어떻게 하나요?

마스크 출력을 마스크 합성 노드의 마스크 입력에 연결하세요. 원본 동영상은 전경 입력에, 새 장면은 배경 입력에 연결합니다.