---
name: modu-ai/media-higgsfield-explainer
source: https://app.decimal.ai/s/modu-ai-media-higgsfield-explainer@1/SKILL.md
source_sha256: 27e8eece3974
---

# Higgsfield 설명 영상 (media-higgsfield-explainer)

> `moai-media` | 블록 조립형 내레이션 영상 (코어: `media-higgsfield-core`)

## 개요

설명 영상은 단발 클립 생성과 다르다. **하나의 스타일 키를 전 블록에 고정하고**, 블록마다 내레이션 1줄과 10초 클립 1개를 1:1로 짝지은 뒤, 서버 조립기로 순서대로 이어 붙인다. 이 순서를 어기면 스타일이 흔들리고 음성과 화면이 어긋난다.

호출 계약·비용 프리플라이트·namespace 해석은 코어를 따른다:
- 호출 계약: `../media-higgsfield-core/references/call-schema.md`
- 잡·비용·리드백: `../media-higgsfield-core/references/job-lifecycle.md`

프롬프트 템플릿은 `references/prompts.md`. **1~3단계 진입 전에 반드시 읽는다.**

## 트리거 키워드

설명 영상, 익스플레이너, explainer, 내레이션 영상, 나레이션, 해설 영상, 애니메이션 설명, 마스코트 영상, 얼굴 없는 영상, 스토리 영상, 다큐 스타일 영상

## 사용 도구 (MCP)

| 단계 | 도구 |
|---|---|
| 스타일 프리셋 목록 | 설명영상 프리셋 조회 |
| 프리셋 → 스타일 키 미디어 | 프리셋 해석 |
| 커스텀 스타일 키 생성 | `generate_image` (Nano Banana 계열) |
| 보이스 목록 | 보이스 조회 |
| 내레이션 생성 | `generate_audio` (`seed_audio`) |
| 클립 생성 | `generate_video` (Gemini Omni 계열) |
| 진행 확인 | `job_status` |
| 최종 조립 | 설명영상 조립 도구 |

모델 id는 라이브 조회로 확인한다. 조립은 서버가 한다 — 로컬 ffmpeg나 수동 이어붙이기를 쓰지 않는다.

## 하드 규칙

이 규칙들은 결과 품질이 아니라 **성립 여부**를 가른다.

- 모든 화면은 **비실사**를 유지한다. 같은 STYLE 서술과 사실주의 금지어를 매 블록 프롬프트에 반복한다.
- 클립에는 **말소리가 들어가지 않는다.** 클립 오디오는 앰비언스·음악뿐이며 대사·립싱크·내레이션을 넣지 않는다. 목소리는 내레이션 트랙에서만 온다.
- 블록당 내레이션 1개, 클립 1개. **N번 오디오는 반드시 N번 영상에 붙는다.**
- **같은 스타일 키 이미지를 모든 클립에 첨부한다.**
- 이미지·영상 프롬프트는 **영어로 쓴다.** 내레이션만 사용자가 고른 언어로 쓴다.
- 실제 주제는 조사한 뒤 대본을 쓴다. 인용·날짜·수치·사건을 지어내지 않는다.
- **같은 실행 안에서 조립까지 끝낸다.** 클립만 흩어놓고 끝내면 실패다.

## 워크플로우

### 0단계 — 두 번에 나눠 묻기 (합치지 않는다)

이 스킬은 사용자에게 직접 묻지 않는다. 아래 슬롯을 **두 라운드로 나눠** 수집하도록 오케스트레이터에 blocker로 요청한다. 한 번에 몰아 묻지 않는 이유는 스타일 선택이 나머지 결정의 전제이기 때문이다.

**라운드 1 — 스타일만.** 프리셋 목록을 라이브 조회해 이름과 미리보기를 제시하고, 프리셋 선택 / 직접 서술 / 참조 이미지 첨부 중 하나를 받는다. 스타일 선택은 필수이며, 사용자가 명시적으로 위임하지 않는 한 임의로 고르지 않는다.

**라운드 2 — 제작 설정.** 스타일이 정해진 뒤에만 묻는다.

| 슬롯 | 기본 | 값 |
|---|---|---|
| 길이 | — | 1~10분 정수. **블록 수 N = 분 × 6** |
| 내레이션 언어 | 영어 | 선택지를 준다 |
| 캐릭터 | — | 마스코트 / 무인물. 항상 묻는다 |
| 화면비 | **프리셋을 고르면 `9:16`** | `16:9` / `9:16` — 아래 주의 |
| 자막 | 끔 | 켜면 폰트를 고르게 한다(임의 선택 금지). 음성 블록당 추가 비용 발생을 알린다 |

> **화면비 주의 (라이브 관측).** CMS 프리셋은 저술 시점 기준 **전부 `9:16` 세로**다. 따라서 프리셋을 고른 뒤 `16:9`를 요구하면 프리셋 참조와 충돌한다. 가로형이 꼭 필요하면 **프리셋 대신 커스텀 스타일 키**로 가는 것이 정상 경로다. 프리셋 목록의 `aspect` 값은 고정이 아니므로 매번 조회 결과를 확인하고, 프리셋을 고른 경우 그 `aspect`를 기본값으로 삼는다.

### R단계 — 조사

실제 주제면 웹 조사로 블록마다 쓸 사실을 확보하고 출처 목록을 남긴다. 기억만으로 사실형 대본을 쓰지 않는다. 개인 이야기면 조사를 건너뛰고 사용자가 준 내용만 쓴다.

### 1단계 — 스타일 키 확보

**프리셋을 골랐다면** 프리셋을 해석해 스타일 키 미디어 id를 얻는다. 이미지를 새로 만들지 않는다. 프리셋 참조가 0단계에서 정한 화면비와 충돌하면 조용히 밀어붙이지 말고 사용자에게 선택을 되돌린다 — 프리셋이 전부 세로인 현 상태에서 가로형 요구는 **커스텀 스타일 키 경로**로 안내한다.

**커스텀이라면** 키 이미지를 **정확히 1장** 생성한다. 템플릿은 `references/prompts.md`의 추상 스와치(또는 마스코트 변형). 완료된 잡 UUID를 스타일 키로 보관한다.

### 2단계 — 내레이션 N줄

선택한 언어로 정확히 N개 블록을 쓴다. 한 줄당 20~24단어, 약 8~9초, 9.5초를 넘기지 않는다. 타임코드·감정 지시·괄호 지문을 넣지 않고, 숫자는 풀어 쓰며, "이 영상에서는" 같은 표현을 쓰지 않는다.

### 3단계 — 클립 프롬프트 N개

`references/prompts.md`의 블록 템플릿(STYLE REFERENCE / SCENE / MOTION / AUDIO / NEGATIVE)으로 영어 프롬프트 N개를 쓴다. STYLE 토큰은 전 블록 동일하게 복사한다. 블록당 동작은 하나만.

### 4단계 — 내레이션 먼저 전부 생성

보이스 목록을 조회해 사용자가 **하나**를 고르게 한다(임의 선택 금지). 고른 보이스의 id와 타입을 고정하고, 같은 보이스로 블록별 오디오를 생성한다. 블록 순서대로 잡 UUID를 기록한다.

실패했거나 지나치게 긴 테이크만 다시 만든다. 길면 문장을 줄이거나 말속도를 조금 조정한다.

**N개 오디오가 전부 완료되기 전에는 5단계로 넘어가지 않는다.** 이 장벽은 엄격하다.

### 5단계 — 클립 전부 생성

블록마다 10초 클립을 만든다. **모든 호출에 같은 스타일 키를 첨부한다.** 이 단계 안에서는 독립 잡을 동시에 돌려도 된다. 실패한 블록만 재제출하고, 모델을 조용히 다른 것으로 바꾸지 않는다.

### 6단계 — 즉시 조립

블록 쌍을 순서대로 구성해(영상 잡 ↔ 오디오 잡, 최소 2쌍) 조립 도구에 넘긴다. 가로는 1280×720, 세로는 720×1280. 자막을 켰다면 고른 폰트를 함께 넘긴다.

조립기는 각 블록을 정확히 10초로 맞춘다 — 짧은 테이크는 가운데 정렬하고, 약간 넘치면 피치를 보존한 채 속도를 올리며, 영상은 늘이지 않는다. 총 길이는 정확히 **N × 10초**다.

## 체크포인트

| 시점 | 충족 조건 |
|---|---|
| 5단계 전 | 스타일 키 1개, 내레이션 N줄, 프롬프트 N개, 보이스 1개 확정, 오디오 잡 N개 완료 |
| 6단계 전 | 영상 잡 N개 완료, 블록 쌍이 1:1이며 누락·중복 없음 |

## 복구

| 증상 | 조치 |
|---|---|
| 프리셋이 없음 | 목록을 다시 조회한다. id를 재사용하거나 지어내지 않는다 |
| 프리셋 해석 실패 | 워크스페이스 선택을 확인하고 한 번 재시도 |
| 스타일 흔들림·실사화 | 공유 STYLE과 NEGATIVE를 강화하고 **그 클립만** 재생성 |
| 타임아웃 | 진행 중인 잡에 다시 붙는다. **돌고 있는 잡을 중복 제출하지 않는다** |
| 같은 실패 2회 | 프롬프트나 파라미터를 바꾼다. 같은 호출을 3번째 반복하지 않는다 |

## 출력 형식

```
## Higgsfield 설명 영상 결과
- 최종 영상 URL: [조립 완료 결과]
- 길이: [정확히 N × 10초] · 화면비: [16:9 | 9:16]
- 내레이션 언어: [선택 언어] · 내레이터: [보이스 이름]
- 스타일: [프리셋 이름 | 커스텀 서술]
- 자막: [끔 | 폰트명]
- 비용: [get_cost 합계]
- 출처: [실제 주제인 경우 조사 출처 목록]
```

중간 잡 id와 개별 클립 URL은 요청받기 전에는 내부에 둔다.

## 주의사항

- 내레이션과 화면의 블록 번호가 어긋나면 영상 전체가 어긋난다. 짝을 기계적으로 검증한다.
- 참조 이미지는 **스타일 기증자**로만 쓴다. 거기 있는 인물·글자·로고·사물을 복제하지 않는다.
- 클립에 자막·화면 텍스트를 넣지 않는다. 자막이 필요하면 조립 단계의 자막 옵션을 쓴다.
- 비용은 블록 수에 비례한다. 10분(60블록)은 1분(6블록)의 10배다 — 길이를 확정하기 전에 알린다.
- 모델 id·파라미터를 추측하지 않는다.

## 관련 스킬

| 스킬 | 시점 |
|---|---|
| `moai-media:media-higgsfield-core` | 코어: 호출 계약·비용·namespace |
| `moai-media:media-higgsfield-assets` | 구성: 오디오 파라미터 상세 |
| `moai-media:media-higgsfield-video` | 대안: 단발 클립·실사·광고 영상 |
| `moai-officer:doc-html-slide` | 대안: 같은 내용을 슬라이드로 |
| `moai-story:story-screenplay` | 선행: 서사 구조 설계 |
| `moai-marketer:marketing-youtube-podcast-planner` | 선행: 채널 기획 |

## 출처

- [Higgsfield Skills (공식 agent 문서)](https://github.com/higgsfield-ai/skills) — `higgsfield-video-explainer` v0.12.0 (MIT). 6단계 파이프라인·하드 규칙·프롬프트 템플릿·체크포인트의 근거.
- 공식 스킬이 문서화한 MCP↔CLI 대응표를 MCP 방향으로 되돌려 사용한다. 조립기 동작(10초 정규화·피치 보존 가속·영상 비신축)은 공식 문서 기술이다.
- 프리셋·보이스·모델 목록은 라이브 조회가 유일한 진실원이다.