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