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개 블록을 쓴다. 한 줄당 2024단어, 약 89초, 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 문서) — higgsfield-video-explainer v0.12.0 (MIT). 6단계 파이프라인·하드 규칙·프롬프트 템플릿·체크포인트의 근거.
• 공식 스킬이 문서화한 MCP↔CLI 대응표를 MCP 방향으로 되돌려 사용한다. 조립기 동작(10초 정규화·피치 보존 가속·영상 비신축)은 공식 문서 기술이다.
• 프리셋·보이스·모델 목록은 라이브 조회가 유일한 진실원이다.