Media Higgsfield Explainer

---
name: media-higgsfield-explainer
description: |
  Higgsfield MCP로 내레이션이 깔린 비실사 설명 영상을 만듭니다. 10초 블록 단위로 내레이션 한 줄과
  영상 한 컷을 짝지어 만든 뒤, 서버에서 순서대로 조립해 완성 MP4를 반환합니다.
  다음과 같은 요청 시 사용하세요:
  - "이 주제로 설명 영상 만들어줘"
  - "이 문서를 나레이션 영상으로"
  - "얼굴 안 나오는 내레이션 영상"
  - "마스코트가 설명하는 영상"
  - "이 이야기를 애니메이션으로 풀어줘"
  1~10분(블록 = 분×6)을 지원하고, 스타일 프리셋 라이브 카탈로그·마스코트/무인물 모드·16:9와 9:16·
  선택적 자막을 다룹니다. 실사 영상, 광고·UGC, 토킹헤드, 팟캐스트, 단발 클립은 범위 밖이며
  media-higgsfield-video를 사용하세요.
version: "1.3.0"
---

# 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 토큰은 전 블록 동일하게 복사한다. 블록당 동작은 하나만.

### 3.5단계 — 전체 계획 승인 (첫 유료 작업 전)

여기가 이 스킬의 유일한 비용 정지선이다. 4단계부터는 오디오 N개 + 영상 N개 + 조립이 연달아 나가고, 지금까지 비용은 **다 끝난 뒤 출력 형식에서야** 사용자에게 도달한다. 그때는 이미 청구된 뒤다.

- **[HARD] 첫 유료 호출 전에 전체 계획을 한 번에 승인받는다.** 잡마다 묻지 않는다 — N이 크면 그것대로 못 쓸 물건이 된다. 계획 전체에 한 번, 그것이 이 게이트다.
- **[HARD] 승인은 §승인 요청 계약의 경로로 받는다.** 이 스킬은 사용자에게 직접 묻지 않으므로 blocker로 반환하고 오케스트레이터가 묻는다.
- **[HARD] 요약하지 말고 계획 전부를 그대로 보여준다:**

| 보여줄 것 | 왜 필요한가 |
|---|---|
| 내레이션 **N줄 전문** | 이 문장들이 그대로 음성이 된다. 요약본으로는 어색한 문장을 잡을 수 없다 |
| 클립 프롬프트 N개 (매니페스트) | 어떤 그림이 나올지 |
| 확정한 보이스 이름·id·타입 | 4단계에서 전 블록에 고정 적용된다 |
| 영상 모델·화면비·자막 폰트 | 0~1단계에서 정한 값 |
| 잡 개수: 오디오 N + 영상 N + 스타일 키 + 조립 **+ 재생성 예비분** | 총 몇 번 돈이 나가는지 |
| **최대 총 크레딧**과 현재 잔액 | 블록당 단가 × (N + 재생성 예비분)을 합산해 미리 보여준다. 이 값이 상한이며, 넘으면 재승인이다 |
| R단계 출처 목록 | 사실형 대본이면 무엇에 근거했는지 |

- **[HARD] 내레이션은 승인 화면에 올리기 전에 ⟨한국어 감사 3단⟩을 통과시킨다.** 한국어 내레이션은 발행되는 글이고, 음성으로 굳으면 고치는 데 다시 크레딧이 든다.

```
  moai-coworker:ai-slop-reviewer     1차 일반 슬롭 정리
→ moai-writer:korean-spell-check     2차 맞춤법 — 제안 수집 (미공개 정보가 섞였으면 건너뜀)
→ moai-writer:korean-humanize        3차 정밀 윤문 + 맞춤법 반영 + Phase 6 최종 검수
```

  감사 뒤에는 **줄당 20~24단어·9.5초 상한을 다시 센다** — 감사가 문장을 고치므로 이전 계산은 무효다.

- **[HARD] 사실형 대본은 출처와 대조한 뒤 승인 화면에 올린다.** R단계에서 모은 출처에 없는 수치·날짜·인용이 내레이션에 있으면 그 줄을 표시해 사용자가 판단하게 한다. 기억으로 채운 문장을 승인 화면에 조용히 섞지 않는다.

승인 선택지는 이렇게 구성한다:

| 선택지 | 뜻 |
|---|---|
| 이 계획대로 제작 (권장) | 보여준 계획 그대로 4단계 진입 |
| 고쳐 쓰기 | 2~3단계로 복귀 → 감사 재통과 → 재승인 |
| 취소 | 아무것도 생성하지 않고 종료. 크레딧 소진 없음 |

- **[HARD] 승인 금액은 재생성분까지 포함해 계산한다.** `오디오 N + 영상 N + 스타일 키 + 조립`만 더한 금액은 **실제 지출의 하한**이지 상한이 아니다. 실패·과길이 테이크는 반드시 생기므로, 승인 화면의 최대 총 크레딧에 **재시도 예비분을 명시적으로 포함**하고 그 횟수를 함께 적는다(예: `블록당 재생성 1회까지 = +N건`).
- **[HARD] 승인된 최대 크레딧을 한 건이라도 넘기면 새 승인을 받는다.** 재생성이 예비분 안이면 계획 범위이고, 예비분을 소진한 뒤의 추가 생성은 **범위 밖**이다. "그 클립만 재생성"이라는 이유로 상한을 넘기지 않는다 — 한 건씩 넘는 것이 누적되면 사용자는 승인한 적 없는 금액을 내게 된다.
- **[HARD] 누적 소진분을 추적한다.** 4·5단계를 도는 동안 지금까지 나간 크레딧을 세고, 승인 상한에 닿으면 멈춘다. 세지 않으면 넘었는지 알 수 없다.

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

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

실패했거나 지나치게 긴 테이크만 다시 만든다.

- **같은 문장 그대로** 다시 만드는 것은 예비분 안이므로 그대로 진행한다.
- **[HARD] 문장을 줄이면 그건 다른 나레이션이다.** 승인 화면에서 읽으신 문장이 아니게 되므로, 고친 문장을 보여드리고 다시 승인받는다. 말속도만 조정하는 것은 문장이 그대로이므로 재승인 대상이 아니다.
- 여러 블록을 고쳐야 하면 **한 번에 모아 보여드린다** — 블록마다 따로 묻지 않는다.

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

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

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

### 6단계 — 즉시 조립

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

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

## 승인 요청 계약 (런타임 중립)

[HARD] 이 스킬의 게이트는 **특정 도구 이름에 묶이지 않는다.** `AskUserQuestion`은 Claude 런타임의 수단일 뿐이고, Codex를 비롯한 다른 런타임에는 그 도구가 없다. 도구 이름으로 계약을 쓰면 그 도구가 없는 런타임에서 게이트가 **영구 blocker**가 되어, 승인이 필요한 모든 작업이 그냥 멈춘다. 그건 안전이 아니라 고장이다.

승인은 아래 순서로 구한다. 위에서부터 **실제로 가능한 첫 번째**를 쓴다.

**승인의 정의는 수단이 아니라 결과다: 승인서를 사용자에게 그대로 보여주고, 그에 대한 명시적 응답을 받는 것.** 아래는 그 결과를 만드는 경로들이며, 위에서부터 가능한 첫 번째를 쓴다.

| 순위 | 경로 | 조건 |
|---|---|---|
| 1 | 런타임의 구조화 질문 도구 (`AskUserQuestion` 등) | 그 도구가 현재 세션에 노출돼 있을 때 |
| 2 | **일반 대화로 승인서를 제시하고 다음 턴에서 응답을 받는다** | 사용자와 직접 대화 중일 때. 도구가 없어도 이 경로는 언제나 열려 있다 |
| 3 | 구조화 blocker 반환 → 상위 오케스트레이터가 물어봄 | 서브에이전트로 실행 중일 때 |

**[HARD] 런타임의 도구 실행 권한 프롬프트는 승인이 아니다.** 그 프롬프트는 "이 도구를 호출해도 되는가"를 물을 뿐, 게이트가 보여주기로 한 인자·견적·동의 문항을 표시하지 않는다. 승인서 전체와 선택지를 실제로 표시하는 경우에만 2번 경로로 인정한다.

**[HARD] 2번 경로가 있으므로 "물을 수단이 없다"는 상황은 사실상 없다.** 대화가 가능한 곳에서는 언제나 승인서를 글로 제시할 수 있다. fail-closed는 **대화도 blocker 반환도 불가능한 완전 무인 실행**에만 해당한다 — 그 경우에만 실행하지 않고 멈춘다.

**[HARD] 3번을 쓸 때 blocker는 그 자체로 승인 요청서여야 한다.** 상위가 무엇을 물어야 할지 모르면 되물을 수 없고, 그러면 교착된다. 다음을 모두 담는다:

- 승인받을 **행위** 한 줄 (무엇이 되돌릴 수 없는지 / 얼마가 나가는지)
- 게이트가 요구하는 **인자 전부** (요약하지 않은 값)
- **선택지 목록** — 상위가 그대로 사용자에게 제시할 수 있는 형태
- **재개 방법** — 어떤 답을 받으면 무엇을 이어서 실행하는지

**[HARD] 세 경로가 모두 불가능한 무인 실행에서는 실행하지 않는다(fail-closed).** 물을 수단이 없다는 것은 승인을 받았다는 뜻이 아니다. 이때는 "승인 수단이 없어 진행하지 못했다"고 기록하고 멈춘다 — 조용히 진행하지 않는다. 반대로 **대화가 가능한데 도구가 없다는 이유로 멈추는 것도 잘못**이다. 2번 경로를 쓴다.

> 이 계약은 `CLAUDE.local.md` §범용성 원칙(OS 2종 × 런타임 2종에서 동일 동작)의 게이트 쪽 적용이다. 한 런타임에서만 도는 게이트는 미완성으로 본다.

---

## 체크포인트

| 시점 | 충족 조건 |
|---|---|
| 4단계 전 | 3.5단계 승인 완료 — 내레이션이 한국어 감사 3단을 통과했고, 최대 총 크레딧을 보여준 그 계획에 대해 승인을 받았음 |
| 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초 정규화·피치 보존 가속·영상 비신축)은 공식 문서 기술이다.
- 프리셋·보이스·모델 목록은 라이브 조회가 유일한 진실원이다.