higgsfield-video-explainer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Higgsfield Video Explainer

Higgsfield 解说视频制作工具

Run the MCP video-explainer workflow through Higgsfield CLI. Lock one visual style key, write one narration line and one matching visual prompt per 10-second block, generate every voice take first, generate every clip second, then immediately assemble the ordered pairs with

explainer_video

Never use the monolithic

video_explainer

job in this skill.

通过Higgsfield CLI运行MCP视频解说工作流。锁定一个视觉风格密钥，为每个10秒片段撰写一句旁白台词和一个匹配的视觉提示词，先生成所有语音素材，再生成所有视频片段，随后立即使用

explainer_video

将有序的素材对组装起来。

本技能中禁止使用一体化的

video_explainer

任务。

MCP-to-CLI mapping

MCP工作流与CLI命令映射

MCP workflow operation	CLI equivalent
`get_explainer_presets`	`higgsfield preset list video-explainer --json`
`resolve_explainer_preset`	`higgsfield preset resolve video-explainer <preset_id> --json`
`generate_image` / `nano_banana_pro`	`higgsfield generate create nano_banana_2 ...`
`list_voices`	`higgsfield voices list --json`
`generate_audio` / `seed_audio`	`higgsfield generate create seed_audio ...`
`generate_video` / `gemini_omni`	`higgsfield generate create gemini_omni ...`
`job_status`	`--wait --json` or `higgsfield generate wait <job_id> --json`
`explainer_video`	`higgsfield generate create explainer_video ...`

nano_banana_2

is the public CLI id for the Nano Banana Pro style-key model used by the MCP workflow.

MCP工作流操作	CLI等效命令
`get_explainer_presets`	`higgsfield preset list video-explainer --json`
`resolve_explainer_preset`	`higgsfield preset resolve video-explainer <preset_id> --json`
`generate_image` / `nano_banana_pro`	`higgsfield generate create nano_banana_2 ...`
`list_voices`	`higgsfield voices list --json`
`generate_audio` / `seed_audio`	`higgsfield generate create seed_audio ...`
`generate_video` / `gemini_omni`	`higgsfield generate create gemini_omni ...`
`job_status`	`--wait --json` 或 `higgsfield generate wait <job_id> --json`
`explainer_video`	`higgsfield generate create explainer_video ...`

nano_banana_2

是MCP工作流所使用的Nano Banana Pro风格密钥模型的公开CLI标识。

Bootstrap

初始化步骤

higgsfield

is unavailable, install it:

bash

curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh

higgsfield account status

fails, ask the user to run

higgsfield auth login

, then wait.

Inspect the live contracts before the first submission:

bash

higgsfield model get nano_banana_2
higgsfield model get seed_audio
higgsfield model get gemini_omni
higgsfield model get explainer_video

如果未安装

higgsfield

，请执行以下命令安装：

bash

curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh

如果执行
```
higgsfield account status
```
失败，请让用户运行
```
higgsfield auth login
```
进行登录，等待登录完成。

在首次提交任务前，查看实时模型合约：

bash

higgsfield model get nano_banana_2
higgsfield model get seed_audio
higgsfield model get gemini_omni
higgsfield model get explainer_video

Phase 0 — ask first

阶段0 — 先收集需求

Collect choices in two separate turns, in this order. Never merge them.

分两轮收集用户选择，严格遵循以下顺序，不可合并为一轮。

Turn 1 — style only

第一轮 — 仅确认风格

Always load the live CMS catalog:

bash

higgsfield preset list video-explainer --json

Show the preset names with their thumbnail/video preview URLs. Say one short line asking the user to pick a preset, describe a custom style, or attach style-reference images, then end the turn. Do not ask production questions in the same turn. Choosing a style is mandatory; never choose silently unless the user explicitly says “you choose.”

Skip this turn only when the request already contains

explainer preset id: <uuid>

. Confirm that UUID exists in the live catalog and keep it for Phase 1.

始终加载实时CMS预设目录：

bash

higgsfield preset list video-explainer --json

展示预设名称及其缩略图/视频预览链接。用一句话询问用户选择预设、描述自定义风格，或上传风格参考图片，随后结束本轮。本轮不可询问制作相关的其他问题。风格选择为必填项，除非用户明确表示「由你选择」，否则不可自行决定。

仅当用户请求中已包含

explainer preset id: <uuid>

时，可跳过本轮。需确认该UUID存在于实时目录中，并将其保留至阶段1使用。

Turn 2 — production settings

第二轮 — 制作设置

Only after style selection, collect every unresolved setting:

Duration: one to ten whole minutes.
```
N = duration_minutes × 6
```
fixed 10-second blocks.
Narration language: English by default, but still offer the choice.
Character: recurring mascot or faceless stylistic scenes. Always ask.
Aspect:
```
16:9
```
by default or
```
9:16
```
vertical.
Subtitles: off by default. Explain that subtitles cost 0.05 credit per voiced block. If enabled, make the user choose
```
patrick
```
,
```
caveat
```
,
```
marker
```
, or
```
anton
```
; never choose silently.

Every choice belongs to the user unless they explicitly delegate it.

仅在确认风格后，收集所有未确定的设置：

时长：1至10整分钟。
```
N = 时长分钟数 × 6
```
，即固定的10秒片段数量。
旁白语言：默认英语，但仍需提供选择。
角色：重复出现的吉祥物或无脸风格场景。必须询问用户选择。
画幅比例：默认
```
16:9
```
或可选
```
9:16
```
竖屏。
字幕：默认关闭。需说明字幕每个旁白片段需花费0.05积分。若启用字幕，需让用户选择
```
patrick
```
、
```
caveat
```
、
```
marker
```
或
```
anton
```
字体，不可自行决定。

除非用户明确授权，否则所有选择均由用户决定。

Inputs

输入内容

Topic or personal/philosophical story.
Optional local source documents; read/extract them before scripting. They are factual input, not generation media.
Optional preset UUID, mutually exclusive with custom style-reference images.
Optional style-reference images. Use only their rendering style and color grading; never copy their people, text, logos, or objects unless requested.
Duration, language, character mode, aspect, and subtitle choice from Phase 0.

For local style donors, pass each path with a repeated

--image

. For a web image, download it locally first or use an existing uploaded media ID.

主题或个人/哲理故事。
可选的本地源文档；编写脚本前需读取/提取内容。这些是事实输入，而非生成素材。
可选的预设UUID，与自定义风格参考图片互斥。
可选的风格参考图片。仅使用其渲染风格和色彩分级；除非用户要求，否则不可复制其中的人物、文字、标志或物体。
阶段0确定的时长、语言、角色模式、画幅比例和字幕选项。

对于本地风格参考图片，使用重复的

--image

参数传入每个文件路径。对于网络图片，需先下载至本地或使用已上传的媒体ID。

Hard rules

硬性规则

Keep every visual strictly non-photorealistic. Repeat the same STYLE descriptor and non-realism negatives in every clip prompt.
Keep all spoken words out of video generation. Clip audio is ambient sound or music only; no dialogue, lip-sync, or baked narration.
Use exactly one narration take and one clip per labeled block. Block N audio always maps to Block N video.
Attach the same style-key image to every clip.
Write all image/video prompts in English. Only narration uses the selected language.
Research real topics before scripting. Do not invent quotes, dates, numbers, or events.
Assemble automatically in the same run. Returning loose clips is a failure.

所有视觉内容必须严格为非写实风格。在每个视频片段的提示词中重复相同的风格描述符和非写实否定词。
视频生成中不得包含任何语音内容。片段音频仅为环境音效或音乐；不得有对话、唇形同步或内嵌旁白。
每个标记的片段必须恰好包含一段旁白素材和一段视频片段。第N段音频必须对应第N段视频。
所有视频片段需附加相同的风格密钥图片。
所有图片/视频提示词需用英文撰写。仅旁白使用选定的语言。
编写脚本前需对真实主题进行调研。不得编造引用、日期、数字或事件。
在同一流程中自动完成组装。仅返回零散片段视为失败。

Pipeline

工作流程

Phase	Output	CLI
0 Ask	style first; then duration, language, character, aspect, subtitles	`preset list` + user questions
R Research	verified facts and sources	available research tools
1 Style key	one universal style image	`preset resolve` or `nano_banana_2`
2 Narration	N labeled narration lines	reasoning
3 Block prompts	N labeled video prompts	reasoning
4 Voice	user selects one voice; generate N takes	`voices list` + `seed_audio`
5 Clips	generate N 10-second clips	`gemini_omni`
6 Assemble	one final MP4	`explainer_video`

Read

references/prompts.md

before Phases 1–3.

阶段	输出内容	CLI操作
0 需求收集	先确认风格；再确认时长、语言、角色、画幅比例、字幕	`preset list` + 用户问题
R 调研	已验证的事实和来源	可用调研工具
1 风格密钥	一张通用风格图片	`preset resolve` 或 `nano_banana_2`
2 旁白撰写	N个带标记的旁白台词	逻辑推理
3 片段提示词	N个带标记的视频提示词	逻辑推理
4 语音生成	用户选择一种语音；生成N段语音素材	`voices list` + `seed_audio`
5 视频片段生成	生成N个10秒视频片段	`gemini_omni`
6 组装	一个最终MP4视频	`explainer_video`

在开始阶段1至3前，请阅读

references/prompts.md

文件。

Phase R — research

阶段R — 调研

For a real topic, use available web research tools and authoritative sources to verify enough facts for every block. Keep a short Sources list. Never script a factual explainer from memory alone.

For a personal story, skip web research and use only details supplied by the user. Invent nothing factual.

对于真实主题，使用可用的网络调研工具和权威来源验证每个片段所需的事实。保留简短的来源列表。不得仅凭记忆编写事实性解说脚本。

对于个人故事，跳过网络调研，仅使用用户提供的细节。不得编造任何事实内容。

Phase 1 — create or resolve the style key

阶段1 — 创建或解析风格密钥

Write one reusable STYLE descriptor: medium, palette, line/fill behavior, texture/finish, then

non-photorealistic, illustrated, not a photo, no live-action, no realism

撰写一个可复用的风格描述符：媒介、调色板、线条/填充方式、纹理/质感，随后添加

non-photorealistic, illustrated, not a photo, no live-action, no realism

（非写实、插画风格、非照片、无真人实拍、无写实效果）。

Selected CMS preset

选定CMS预设

Resolve the hidden style image into the active workspace:

bash

higgsfield preset resolve video-explainer "<preset UUID>" --json

Keep the returned

media_id

STYLE_KEY_ID

. Skip image generation: this imported media is the style key. Build the STYLE descriptor from the returned preset name plus the mandatory non-photoreal rules. Do not recreate a preset from its name.

The preset reference controls framing. If it conflicts with the aspect requested in Phase 0, stop and let the user choose rather than silently fighting the reference.

将隐藏的风格图片解析至当前工作区：

bash

higgsfield preset resolve video-explainer "<preset UUID>" --json

将返回的

media_id

保存为

STYLE_KEY_ID

。跳过图片生成：此导入的媒体即为风格密钥。根据返回的预设名称加上必填的非写实规则构建风格描述符。不得根据预设名称重新创建预设。

预设参考控制画面构图。若其与阶段0中请求的画幅比例冲突，请暂停并让用户选择，不得强行修改参考内容。

Custom style or reference images

自定义风格或参考图片

Generate exactly one key image. Use the abstract swatch template from

references/prompts.md

, or its mascot variant when character mode is enabled. Repeat

--image

for every style donor:

bash

higgsfield generate create nano_banana_2 \
  --prompt "<style-key prompt>" \
  --aspect_ratio 16:9 \
  --resolution 2k \
  --wait \
  --json

Use

9:16

for vertical. Keep the completed image job UUID as

STYLE_KEY_ID

; later CLI generations can reuse a completed job UUID as an image reference.

恰好生成一张密钥图片。使用

references/prompts.md

中的抽象样本模板，若启用角色模式则使用吉祥物变体模板。为每个风格参考图片重复使用

--image

参数：

bash

higgsfield generate create nano_banana_2 \
  --prompt "<style-key prompt>" \
  --aspect_ratio 16:9 \
  --resolution 2k \
  --wait \
  --json

竖屏使用

9:16

比例。将完成的图片任务UUID保存为

STYLE_KEY_ID

；后续CLI生成任务可复用已完成的任务UUID作为图片参考。

Phase 2 — write narration

阶段2 — 撰写旁白

Write exactly

labeled narration blocks in the selected language:

text

Block 1
<line spoken over clip 1>
Block 2
<line spoken over clip 2>

One line per block, usually 20–24 words and about 8–9 seconds.
Keep every take under roughly 9.5 seconds.
Use plain spoken text only: no timecodes, emotion cues, parentheticals, or stage directions.
Spell numbers out.
Use a concrete tone and never say “in this video.”
For a topic, build from hook through payoff. For a personal story, preserve the user's details and protagonist.

使用选定的语言恰好撰写

个带标记的旁白片段：

text

Block 1
<片段1的旁白台词>
Block 2
<片段2的旁白台词>

每个片段一句台词，通常为20-24个单词，时长约8-9秒。
每个语音素材时长需控制在约9.5秒以内。
仅使用口语化文本：不得包含时间码、情绪提示、插入语或舞台指示。
数字需拼写完整。
使用具体的语气，不得说「在本视频中」。
对于主题类内容，遵循从钩子到收尾的结构。对于个人故事，保留用户提供的细节和主角。

Phase 3 — write matching video prompts

阶段3 — 撰写匹配的视频提示词

Write exactly

labeled English prompts using the template in

references/prompts.md

text

Block N
STYLE REFERENCE: Match the attached reference image EXACTLY. <same STYLE descriptor>
SCENE: <one scene and action matching Block N narration>
MOTION: <camera move and animation behavior>
AUDIO: <ambient SFX or music only; no voice, dialogue, or narration>
NEGATIVE: <style drift and realism bans; no lip-sync, captions, text, logos, or watermark>

For mascot mode, Block 1 greets by gesture with mouth closed, the final block waves a sign-off, and middle blocks use consistent cameos only when useful. For faceless mode, use stylistic scenes only. Keep one clear action per block.

使用

references/prompts.md

中的模板恰好撰写

个带标记的英文提示词：

text

Block N
STYLE REFERENCE: Match the attached reference image EXACTLY. <相同的风格描述符>
SCENE: <与第N段旁白匹配的场景和动作>
MOTION: <镜头移动和动画行为>
AUDIO: <仅环境音效或音乐；无语音、对话或旁白>
NEGATIVE: <禁止风格偏移和写实内容；无唇形同步、字幕、文字、标志或水印>

在吉祥物模式下，第1个片段需展示吉祥物闭嘴挥手问候，最后一个片段需展示吉祥物挥手告别，中间片段仅在必要时加入一致的吉祥物客串。在无脸模式下，仅使用风格化场景。每个片段需保持一个清晰的动作。

Phase 4 — generate every voice take first

阶段4 — 先生成所有语音素材

List the live voices, present the choices, and wait for the user to select one narrator:

bash

higgsfield voices list --json

Keep the selected voice's exact

id

and

type

(

preset

element

). Never invent or auto-pick a voice unless the user explicitly delegates it.

Generate one completed

seed_audio

job per narration block, always with the same voice:

bash

higgsfield generate create seed_audio \
  --prompt "<Block N narration only>" \
  --voice_type "<preset|element>" \
  --voice_id "<voice UUID>" \
  --wait \
  --json

Record every audio job UUID in block order. Regenerate only a failed or excessively long take. Shorten that block or adjust

--speech_rate

modestly when needed. Do not begin Phase 5 until all

audio jobs are complete.

列出可用的实时语音选项，展示给用户，等待用户选择一位旁白：

bash

higgsfield voices list --json

保存所选语音的准确

id

和

type

（

preset

或

element

）。除非用户明确授权，否则不得编造或自动选择语音。

为每个旁白片段生成一个完成的

seed_audio

任务，始终使用同一语音：

bash

higgsfield generate create seed_audio \
  --prompt "<仅第N段旁白台词>" \
  --voice_type "<preset|element>" \
  --voice_id "<语音UUID>" \
  --wait \
  --json

按片段顺序记录每个音频任务的UUID。仅重新生成失败或时长过长的语音素材。必要时可缩短该片段的台词或适度调整

--speech_rate

参数。需等所有

个音频任务完成后，方可开始阶段5。

Phase 5 — generate every clip second

阶段5 — 再生成所有视频片段

Generate one completed 10-second

gemini_omni

clip per block. Attach the same style key to every call:

bash

higgsfield generate create gemini_omni \
  --prompt "<Block N video prompt>" \
  --image "<STYLE_KEY_ID>" \
  --duration 10 \
  --resolution 720p \
  --aspect_ratio 16:9 \
  --wait \
  --json

Use

9:16

when selected. Record every video job UUID in block order. Independent jobs may run concurrently inside this phase, but the audio-phase barrier is strict. Re-submit only failed blocks. Never silently replace

gemini_omni

; inspect the live video catalog if the model is unavailable.

为每个片段生成一个完成的10秒

gemini_omni

视频片段。每个请求需附加相同的风格密钥：

bash

higgsfield generate create gemini_omni \
  --prompt "<第N段视频提示词>" \
  --image "<STYLE_KEY_ID>" \
  --duration 10 \
  --resolution 720p \
  --aspect_ratio 16:9 \
  --wait \
  --json

若选择竖屏则使用

9:16

比例。按片段顺序记录每个视频任务的UUID。本阶段内的独立任务可并行运行，但必须严格等待音频阶段完成后再开始。仅重新提交失败的片段。不得擅自替换

gemini_omni

；若该模型不可用，请查看实时视频模型目录。

Phase 6 — assemble immediately

阶段6 — 立即组装

Create

blocks.json

with at least two ordered block pairs. The CLI model contract requires typed references, so use the generic completed-job types:

json

[
  {
    "video": {"id": "<clip 1 job UUID>", "type": "video_job"},
    "audio": {"id": "<voice 1 job UUID>", "type": "audio_job"}
  },
  {
    "video": {"id": "<clip 2 job UUID>", "type": "video_job"},
    "audio": {"id": "<voice 2 job UUID>", "type": "audio_job"}
  }
]

Submit the server-side assembler immediately:

bash

higgsfield generate create explainer_video \
  --items @blocks.json \
  --width 1280 \
  --height 720 \
  --wait \
  --json

Use

--width 720 --height 1280

for vertical. When subtitles are enabled, add the chosen font:

bash

--subtitles '{"font":"patrick"}'

The assembler keeps each block at exactly 10 seconds: it centers short voice takes, pitch-safely speeds small overruns, never stretches video, concatenates blocks in order, and optionally burns timed captions. Total duration is exactly

N × 10

seconds.

Do not use local ffmpeg, the legacy assembly scripts, or the monolithic

video_explainer

job.

创建包含至少两个有序片段对的

blocks.json

文件。CLI模型合约要求使用带类型的引用，因此请使用通用的已完成任务类型：

json

[
  {
    "video": {"id": "<片段1视频任务UUID>", "type": "video_job"},
    "audio": {"id": "<片段1语音任务UUID>", "type": "audio_job"}
  },
  {
    "video": {"id": "<片段2视频任务UUID>", "type": "video_job"},
    "audio": {"id": "<片段2语音任务UUID>", "type": "audio_job"}
  }
]

立即提交服务端组装任务：

bash

higgsfield generate create explainer_video \
  --items @blocks.json \
  --width 1280 \
  --height 720 \
  --wait \
  --json

竖屏使用

--width 720 --height 1280

参数。若启用字幕，需添加所选字体参数：

bash

--subtitles '{"font":"patrick"}'

组装工具会将每个片段保持为恰好10秒：对于较短的语音素材会居中放置，对于稍长的素材会在保持音调不变的前提下略微加速，绝不会拉伸视频，按顺序拼接片段，并可选添加内嵌定时字幕。总时长恰好为

N × 10

秒。

不得使用本地ffmpeg、旧版组装脚本或一体化的

video_explainer

任务。

Checkpoints and recovery

检查点与故障恢复

Before Phase 5: require one style key, exactly
```
N
```
narration lines and prompts, one selected voice, and
```
N
```
completed audio jobs.
Before Phase 6: require
```
N
```
completed video jobs and exact one-to-one block pairing with no missing or duplicate IDs.
Preset missing: refresh
```
preset list
```
; never reuse or fabricate an ID.
Preset resolve failure: verify workspace selection and retry once.
Style drift or realism: strengthen the shared STYLE and NEGATIVE text, then regenerate only that clip.
Timeout: rejoin with
```
higgsfield generate wait <job_id> --json
```
; never duplicate a running job.
Two identical failures mean the prompt or parameters must change.

阶段5开始前：需确保已拥有一个风格密钥、恰好
```
N
```
句旁白台词和提示词、已选定一种语音，以及
```
N
```
个已完成的音频任务。
阶段6开始前：需确保已拥有
```
N
```
个已完成的视频任务，且片段对为精确的一一对应，无缺失或重复ID。
预设缺失：刷新
```
preset list
```
；不得复用或编造ID。
预设解析失败：验证工作区选择后重试一次。
风格偏移或出现写实内容：强化通用风格描述符和否定词文本，仅重新生成该片段。
超时：使用
```
higgsfield generate wait <job_id> --json
```
重新连接；不得重复提交正在运行的任务。
连续两次相同故障意味着必须修改提示词或参数。

Deliver

交付内容

Return the final assembled video URL, exact duration, aspect, narration language, selected style, narrator, subtitle status, and a Sources list for researched topics. Keep intermediate job IDs and loose asset URLs internal unless requested.

返回最终组装好的视频链接、精确时长、画幅比例、旁白语言、选定风格、旁白语音、字幕状态，以及调研主题的来源列表。除非用户要求，否则中间任务ID和零散素材链接需内部保留，不得对外提供。