moai-media| Block-assembled narration video (core:media-higgsfield-core)
Overview
An explainer video differs from single-clip generation. Fix one style key across all blocks, pair one line of narration with one 10-second clip per block 1:1, then stitch them together in order with the server assembler. If you break this order, the style wavers and the audio and visuals fall out of sync.
The call contract, cost preflight, and namespace resolution follow the core:
- Call contract:
../media-higgsfield-core/references/call-schema.md - Job, cost, readback:
../media-higgsfield-core/references/job-lifecycle.md
The prompt template is references/prompts.md. must be read before entering steps 1–3.
Trigger keywords
explainer video, explainer, explainer, narration video, narration, commentary video, animated explanation, mascot video, faceless video, story video, documentary-style video
Tools used (MCP)
| Step | Tool |
|---|---|
| Style preset list | Explainer video preset lookup |
| Preset → style key media | Preset resolution |
| Create custom style key | generate_image (Nano Banana series) |
| Voice list | Voice lookup |
| Narration generation | generate_audio (seed_audio) |
| Clip generation | generate_video (Gemini Omni series) |
| Progress check | job_status |
| Final assembly | Explainer video assembly tool |
Model IDs are confirmed via live lookup. Assembly is done by the server — do not use local ffmpeg or manual stitching.
Hard rules
These rules determine not the output quality but whether it works.
- All visuals non-photorealisticmust be maintained. Repeat the same STYLE description and realism-prohibition terms in every block prompt.
- Clips do not contain speech. Clip audio is ambience and music only, with no dialogue, lip-sync, or narration. The voice comes only from the narration track.
- One narration per block, one clip. Audio N must be attached to video N.
- Attach the same style key image to every clip.
- Image and video prompts are written in English. Only the narration is written in the language the user chose.
- Research the actual topic before writing the script. Do not invent quotes, dates, figures, or events.
- Finish through assembly within the same run. If you just scatter the clips and stop there, it's a failure.
Workflow
Step 0 — Ask in two rounds (do not combine)
This skill does not ask the user directly. It requests the orchestrator as a blocker to collect the slots below in two rounds . The reason for not asking everything at once is that the style choice is the premise for the remaining decisions.
Round 1 — Style only. Live-query the preset list, present the names and previews, and receive one of: preset selection / direct description / reference image attachment. Style selection is mandatory, and unless the user explicitly delegates it, do not choose arbitrarily.
Round 2 — Production settings. Ask only after the style is decided.
| Slot | Default | 값 |
|---|---|---|
| Length | — | Integer from 1 to 10 minutes. Number of blocks N = minutes × 6 |
| Narration language | English | give options |
| Character | — | Mascot / no character. Always ask |
| Aspect ratio | If a preset is chosen, 9:16 |
16:9 / 9:16 — see the note below |
| Subtitles | 끔 | If enabled, have them choose a font (arbitrary selection prohibited). Inform them that additional cost is incurred per voice block |
Aspect ratio note (live observation). As of the time of writing, CMS presets are all
9:16vertical. Therefore, after choosing a preset,16:9requesting it conflicts with the preset reference. If horizontal is absolutely necessary, custom style key instead of a presetis the normal path. Theaspectvalue in the preset list is not fixed, so check the query result every time, and if a preset is chosen, use thataspectas the default.
R step — Research
For a real topic, secure the facts to use for each block through web research and leave a source list. Do not write a factual script from memory alone. For a personal story, skip research and use only the content the user provided.
Step 1 — Obtain the style key
If a preset was chosen, resolve the preset to obtain the style key media id. Do not create a new image. If the preset reference conflicts with the aspect ratio decided in Step 0, do not quietly push it through; return the choice to the user — in the current state where all presets are vertical, guide horizontal requests to the custom style key path.
If custom, generate the key image exactly 1 . The template is references/prompts.md's abstract swatch (or a mascot variant). Store the completed job UUID as the style key.
Step 2 — N lines of narration
Write exactly N blocks in the chosen language. 20 per line24 words, about 8Do not exceed 9 seconds or 9.5 seconds. Do not include timecodes, emotion directions, or parenthetical stage directions; spell out numbers; do not use expressions like "in this video."
Step 3 — N clip prompts
references/prompts.mdWrite N English prompts using the block template (STYLE REFERENCE / SCENE / MOTION / AUDIO / NEGATIVE). Copy the STYLE token identically across all blocks. Only one action per block.
Step 3.5 — Approve the full plan (before the first paid task)
This is the only cost stop line in this skill. From step 4 onward, N audio + N video + assembly run in succession, and the cost so far is only in the output format after everything is done reaches the user. By then it has already been billed.
- [HARD] Get the full plan approved at once before the first paid call. Do not ask per job — if N is large, that itself makes it unusable. Once for the whole plan, that is this gate.
- [HARD] Approval is obtained via the path in the §Approval Request Contract. Since this skill does not ask the user directly, return it as a blocker and the orchestrator asks.
- [HARD] Do not summarize; show the entire plan as is:
| What to show | Why it is needed |
|---|---|
| Narration Full text of N lines | These sentences become the voice as is. A summary cannot catch awkward sentences |
| N clip prompts (manifest) | What kind of image will appear |
| Confirmed voice name, id, type | Applied fixed to all blocks in step 4 |
| Video model, aspect ratio, subtitle font | Values determined in steps 0–1 |
| Number of jobs: N audio + N video + style key + assembly + regeneration reserve | How many times money will be spent in total |
| Maximum total creditsand current balance | Sum the per-block unit price × (N + regeneration reserve) and show it in advance. This value is the upper limit, and exceeding it requires re-approval |
| Step R source list | If it is a factual script, what it was based on |
- [HARD] Narration must pass ⟨Korean audit 3 stages⟩ before being put on the approval screen. Korean narration is published text, and once it is fixed as voice, fixing it costs credits again.
moai-coworker:ai-slop-reviewer 1차 일반 슬롭 정리
→ moai-writer:korean-spell-check 2차 맞춤법 — 제안 수집 (미공개 정보가 섞였으면 건너뜀)
→ moai-writer:korean-humanize 3차 정밀 윤문 + 맞춤법 반영 + Phase 6 최종 검수
After the audit, recount 20–24 words per line and the 9.5-second upper limit — because the audit changes sentences, previous calculations are invalid.
- [HARD] Factual scripts are put on the approval screen after being checked against sources. If the narration contains numbers, dates, or quotations not in the sources gathered in step R, mark that line so the user can judge. Do not quietly mix sentences filled in from memory into the approval screen.
Compose the approval options like this:
| Options | 뜻 |
|---|---|
| Produce according to this plan (recommended) | Proceed to step 4 exactly as the shown plan |
| Rewrite | Return to steps 2–3 → pass audit again → re-approve |
| Cancel | Exit without generating anything. No credits consumed |
- [HARD] The approved amount is calculated including regenerations.
오디오 N + 영상 N + 스타일 키 + 조립the amount with just more added is the lower bound of actual spending, not the upper bound. Failed and overlong takes are bound to occur, so in the maximum total credits on the approval screen, explicitly include the retry reserveand write down that count as well (e.g.,블록당 재생성 1회까지 = +N건). - [HARD] If even a single item exceeds the approved maximum credits, new approval is obtained. If regeneration stays within the reserve, it is within the plan scope, and additional generation after the reserve is exhausted is out of scope. Do not exceed the cap on the grounds that "only that clip is being regenerated" — if exceeding by one item at a time accumulates, the user ends up paying an amount they never approved.
- [HARD] Track cumulative consumption. While looping through steps 4 and 5, count the credits spent so far, and stop when the approved cap is reached. If you do not count, you cannot know whether you have exceeded it.
Step 4 — Generate all narration first
Query the voice list to let the user onechoose(no arbitrary selection). Fix the id and type of the chosen voice, and generate the audio for each block with the same voice. Record the job UUIDs in block order.
Only failed or excessively long takes are remade.
- The exact same sentence remade is within the reserve, so proceed as is.
- [HARD] If you shorten the sentence, that is a different narration. Since it is no longer the sentence read on the approval screen, show the corrected sentence and get approval again. Adjusting only the speech rate is not subject to re-approval because the sentence stays the same.
- If multiple blocks need correction, show them all at once — do not ask separately for each block.
Do not move on to step 5 until all N audios are complete. This barrier is strict.
Step 5 — Generate all clips
Create a 10-second clip for each block. Attach the same style key to every call. Within this step, independent jobs may be run concurrently. Resubmit only failed blocks, and do not quietly switch the model to a different one.
Step 6 — Immediate assembly
Construct block pairs in order (video job ↔ audio job, at least 2 pairs) and pass them to the assembly tool. Landscape is 1280×720, portrait is 720×1280. If subtitles are enabled, pass the chosen font as well.
The assembler fits each block to exactly 10 seconds — short takes are center-aligned, slightly overlong ones have their speed increased while preserving pitch, and video is not stretched. Total length is exactly N × 10초다.
Approval Request Contract (Runtime-Neutral)
[HARD] The gate of this skill is not tied to a specific tool name. AskUserQuestionis only a means of the Claude runtime, and other runtimes such as Codex do not have that tool. If the contract is written in terms of a tool name, then in runtimes that do not have that tool the gate becomes a permanent blocker, and every task requiring approval simply halts. That is not safety, it is a malfunction.
Approval is obtained in the following order. From the top, use the first one that is actually possible.
The definition of approval is not the means but the result: showing the approval form to the user as-is and receiving an explicit response to it. Below are the paths that produce that result; use the first one possible from the top.
| Rank | Path | Condition |
|---|---|---|
| 1 | The runtime's structured question tool (AskUserQuestion 등) |
when that tool is exposed in the current session |
| 2 | Present the approval form in ordinary conversation and receive the response on the next turn | when in direct conversation with the user. Even without tools, this path is always open |
| 3 | Return a structured blocker → the higher-level orchestrator asks | when running as a subagent |
[HARD] The runtime's tool execution permission prompt is not approval. That prompt only asks "may this tool be called"; it does not display the arguments, estimate, and consent items that the gate is supposed to show. It counts as path 2 only when the full approval form and the options are actually displayed.
[HARD] Because path 2 exists, there is virtually no situation of "no means to ask." Anywhere conversation is possible, the approval form can always be presented in writing. fail-closed applies only to fully unattended execution where neither conversation nor blocker return is possible— only in that case does it stop without executing.
[HARD] When using path 3, the blocker must itself be an approval request. If the higher level does not know what to ask, it cannot ask back, and then deadlock occurs. Include all of the following:
- The action to be approved in one line (what is irreversible / how much is being spent)
- Every argument the gate requires (values not summarized)
- List of options — in a form the higher level can present to the user as-is
- How to resume — upon receiving which answer, what is executed next
[HARD] In unattended execution where all three paths are impossible, do not execute (fail-closed). Having no means to ask does not mean approval was obtained. In this case, record "could not proceed because there was no means of approval" and stop — do not proceed silently. Conversely, Stopping because there is no tool even though conversation is possible is also wrong. Use route 2.
This contract is
CLAUDE.local.mdan application on the gate side of the §Generality Principle (identical behavior across 2 OS types × 2 runtime types). A gate that runs on only one runtime is considered incomplete.
Checkpoint
| Timing | Satisfaction condition |
|---|---|
| Before step 4 | Step 3.5 approval complete — the narration passed the 3-stage Korean audit, and approval was obtained for that plan showing the maximum total credits |
| Before step 5 | 1 style key, N lines of narration, N prompts, 1 voice finalized, N audio jobs complete |
| Before step 6 | N video jobs complete, block pairs are 1:1 with no omissions or duplicates |
Recovery
| Symptom | Action |
|---|---|
| No preset exists | Query the list again. Do not reuse or invent ids |
| Preset resolution failure | Check the workspace selection and retry once |
| Style drift/realistic conversion | Strengthen the shared STYLE and NEGATIVE and only that clip regenerate |
| Timeout | Reattach to the job in progress. Do not submit a running job twice |
| Same failure twice | Change the prompt or parameters. Do not repeat the same call a third time |
Output format
## Higgsfield 설명 영상 결과
- 최종 영상 URL: [조립 완료 결과]
- 길이: [정확히 N × 10초] · 화면비: [16:9 | 9:16]
- 내레이션 언어: [선택 언어] · 내레이터: [보이스 이름]
- 스타일: [프리셋 이름 | 커스텀 서술]
- 자막: [끔 | 폰트명]
- 비용: [get_cost 합계]
- 출처: [실제 주제인 경우 조사 출처 목록]
Intermediate job ids and individual clip URLs are kept internal until requested.
Precautions
- If the block numbers of the narration and the screen are misaligned, the entire video is misaligned. Verify the pairs mechanically.
- Reference images are used style donoronly as such. Do not replicate the people, text, logos, or objects in them.
- Do not put subtitles or on-screen text in clips. If subtitles are needed, use the subtitle option in the assembly stage.
- Cost is proportional to the number of blocks. 10 minutes (60 blocks) is 10 times 1 minute (6 blocks) — inform before finalizing the length.
- Do not guess model ids or parameters.
Related skills
| Skill | Timing |
|---|---|
moai-media:media-higgsfield-core |
Core: call contract, cost, namespace |
moai-media:media-higgsfield-assets |
Configuration: audio parameter details |
moai-media:media-higgsfield-video |
Alternative: single-shot clips, realistic, ad videos |
moai-officer:doc-html-slide |
Alternative: the same content as slides |
moai-story:story-screenplay |
Prerequisite: narrative structure design |
moai-marketer:marketing-youtube-podcast-planner |
Prerequisite: channel planning |
Source
- Higgsfield Skills (official agent documentation) —
higgsfield-video-explainerv0.12.0 (MIT). Basis for the 6-stage pipeline, hard rules, prompt templates, and checkpoints. - Use the MCP↔CLI correspondence table documented by the official skill in reverse, in the MCP direction. The assembler behavior (10-second normalization, pitch-preserving speedup, non-stretching video) is described in the official documentation.
- Live lookup is the only source of truth for preset, voice, and model lists.