Media Higgsfield Explainer

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

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

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

## 개요

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

**실행 전 기능 확인:** 현재 연결에 설명 영상 프리셋 조회·해석, 오디오·영상 생성, `explainer_video` 최종 블록 조립, 각 유료 단계의 비용 조회와 상태 확인 수단이 모두 있는지 확인한다. 모델 목록이나 일반 이미지·영상·오디오 생성 도구만으로 최종 조립 기능을 추정하지 않는다. 필요한 기능이 없으면 **유료 작업을 시작하지 않고** 사용 가능한 연결과 빠진 기능을 보고한다.

호출 계약·비용 프리플라이트·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` / `jobs_wait` 등) |
| 최종 조립 | 설명영상 조립 도구 |

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

## 하드 규칙

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

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

## 워크플로우

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

아래 슬롯은 **두 라운드로 나눠** 수집한다. 직접 실행에 질문 채널이 있으면 확인한다. 하위 에이전트는 질문 도구가 보여도 누락 슬롯·선택지·재개 방법을 blocker로 상위에 반환하고, 직접 실행에 채널이 없어도 같은 blocker를 반환한다. 한 번에 몰아 묻지 않는 이유는 스타일 선택이 나머지 결정의 전제이기 때문이다.

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

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

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

보이스 목록도 이 단계에서 조회해 사용자에게 하나를 고르게 한다. 보이스 id와 타입이 확정되기 전에는 전체 견적·승인으로 넘어가지 않는다.

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

### R단계 — 조사

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

### 1단계 — 스타일 키 설계

**프리셋을 골랐다면** 읽기 전용 프리셋 목록의 id·미리보기·화면비를 확인하고 해석 계획만 세운다. `resolve_explainer_preset`은 프리셋 이미지를 계정 미디어 저장소로 가져오므로 **아직 호출하지 않는다.** 프리셋 참조가 0단계에서 정한 화면비와 충돌하면 사용자에게 선택을 되돌린다.

**커스텀이라면** 키 이미지 **정확히 1장**의 프롬프트와 입력을 준비한다. 템플릿은 `references/prompts.md`의 추상 스와치(또는 마스코트 변형). **아직 생성하지 않는다.** 비용·승인 절차가 끝난 뒤 4단계 시작에서 생성해 완료된 잡 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단계 — 전체 계획 승인 (첫 유료 작업 전)

여기가 프리셋 이미지의 계정 가져오기와 첫 유료 작업 전 정지선이다. 커스텀 스타일 키 생성·오디오 N개·영상 N개·조립·재생성 예비분의 **현재 연결별 견적을 모두 확보한 뒤** 승인서를 만든다. 프리셋 경로라면 스타일 이미지가 계정 저장소로 가져와진다는 사실도 승인서에 표시한다. 어느 필수 단계의 견적도 얻지 못하면 계정 가져오기나 유료 작업을 시작하지 않는다.

- **[HARD] 첫 유료 호출 전에 전체 계획을 한 번에 승인받는다.** 잡마다 묻지 않는다 — N이 크면 그것대로 못 쓸 물건이 된다. 계획 전체에 한 번, 그것이 이 게이트다.
- **[HARD] 승인은 §승인 요청 계약의 경로로 받는다.** 직접 실행에 질문 채널이 있으면 승인서를 보여준다. 하위 에이전트는 질문 도구가 보여도 승인서 전체를 blocker로 상위에 반환하고, 직접 실행에 채널이 없어도 같은 blocker를 반환한다.
- **[HARD] 요약하지 말고 계획 전부를 그대로 보여준다:**

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

- **[HARD] 내레이션은 승인 화면에 올리기 전에 한국어 표현·맞춤법·원자료 대조를 확인한다.** 한국어 내레이션은 음성으로 굳으면 고치는 데 다시 크레딧이 든다. 아래 별도 스킬은 현재 앱에 설치돼 사용할 수 있을 때만 적용하고, 없어도 이 세 가지 검수를 이 스킬에서 수행한다. 개인·비공개 원문은 외부 스킬에 그대로 넘기지 않는다.

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

  감사 뒤에는 **언어별 길이 기준과 9.5초 상한을 다시 확인한다** — 감사가 문장을 고치므로 이전 계산은 무효다.

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

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

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

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

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

커스텀 스타일 키를 선택했다면 승인된 프롬프트로 키 이미지를 먼저 한 장 생성하고 완료를 확인한다. 프리셋을 선택했다면 **승인 뒤에만** `resolve_explainer_preset`을 호출해 스타일 이미지를 계정 저장소로 가져오고 반환된 media id를 사용한다. 0단계에서 승인받은 보이스의 id와 타입을 고정하고, 같은 보이스로 블록별 오디오를 생성한다. 블록 순서대로 잡 UUID를 기록한다.

실패했거나 지나치게 긴 테이크만 다시 만든다. 제출 응답이 애매하게 끊겼다면 상태·이력 도구로 **기존 잡이 없거나 실패했다는 사실을 확인한 뒤에만** 재제출한다. 확인할 수 없으면 멈춘다.

- **같은 문장 그대로** 다시 만드는 것은 예비분 안이므로 그대로 진행한다.
- **[HARD] 문장·보이스·말속도 등 승인된 입력을 바꾸면** 변경값으로 다시 견적하고 승인받는다. 문장이 같더라도 말속도가 달라지면 승인된 옵션과 결과 길이가 바뀐다.
- 여러 블록을 고쳐야 하면 **한 번에 모아 보여드린다** — 블록마다 따로 묻지 않는다.

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

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

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

### 6단계 — 즉시 조립

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

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

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

[HARD] 승인에는 코어 `media-higgsfield-core` §승인 요청 계약을 따른다. 현재 앱의 질문 채널이 없으면 직접 대화 중에도 산문으로 묻지 않고 blocker를 반환한다. blocker에는 다음을 모두 담는다:

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

**[HARD] 승인 응답을 받지 못하면 스타일 키·오디오·영상·조립을 제출하지 않는다.** 도구 실행 권한 프롬프트는 전체 계획과 크레딧 상한에 대한 승인으로 간주하지 않는다.

---

## 체크포인트

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