ComfyUI node for MiniMax H3 that chains multiple video clips with motion context, disk caching, dynamic image references, audio reference support, and seamless final video/audio decoding.
Python
323
228 commits
updated Oct 9, 2026
A ComfyUI custom node for MiniMax H3 designed to generate long, continuous video sequences from multiple clips while preserving motion, visual continuity, and audio continuity between generations.
The node combines Ref2VA conditioning, Motion Context, disk caching, multi-clip generation, image references, audio references, and final video/audio decoding into a much simpler workflow.
This is probably the final feature release of MiniMax H3 Extender.
Apart from possible bug fixes or compatibility corrections, I do not currently plan to continue active development of this project.
A new optional Latent Refine / Upscale mode is now available, inspired by the latent refine work introduced in PR #83.
When enabled, each clip is generated normally, then its latent is upscaled and passed through a second H3 refine pass before continuing through the Extender’s existing cache, Motion Context, preview and export pipeline.
There is no separate draft/refine workflow: the refined result becomes the clip’s final result directly.
Refine settings include:
The same H3 model is reused for both passes, and the required latent upscaler model is downloaded automatically on first use.
MiniMax H3 Extender can now continue from an existing video.
continue_existing_video input.<Picture N> reference, useful for preserving character identity when the end of the source video does not show the subject clearly.This makes it possible to take an existing video and continue building it directly inside the Extender.
Full Batch can now optionally save each final clip as a separate video file using the new Save Individual Clips option in Final Decode / Preview.
The option is disabled by default, so the existing Full Batch workflow remains unchanged unless explicitly enabled.
When enabled, individual clips are exported only after all normal processing is complete. They use the same final video segments as the assembled output, including seam correction, per-clip color adjustments and FL2VA visible-frame trimming/handoffs.
Audio is captured during the same final PCM assembly pass used for the complete video, so no additional audio reconstruction pass is required.
No additional sampling or VideoVAE decode is introduced. Individual video streams are reused with stream-copy and saved in a dedicated folder beside the final assembled video.
Supported in:
.ext project save after a successful Full BatchAdded a new New Project button to quickly start from a completely clean state.
It clears all current project data and cached references, removes prompts, resets the timeline to a single empty clip, and wipes previous computed/validated state — while keeping all global node settings unchanged.
Useful when switching to a completely different project and helps prevent old references or cached project data from carrying over into the next generation.
Ref2VA now includes a Motion Context ON/OFF option.
With Motion Context OFF, clips are fully independent from each other. This means you can insert, rerender, or invalidate any clip without invalidating the clips before or after it, making random-access editing much more flexible.
The trade-off is that there is no continuity between clips: each clip is generated as a separate shot, so characters, framing, camera position, motion, and scene composition are not automatically carried over from one clip to the next.
Use Motion Context ON when you want continuous multi-clip motion and seamless progression, and Motion Context OFF when you prefer independent shots and easier editing.
Ref2VA clips can now use their own local Picture, Video and Audio references in addition to the existing global references.
Each clip gets a compact Refs panel where local references can be added, removed and previewed without cluttering the main card UI.
Local references use the normal H3 slot numbering and share the same limits as global references:
Global references remain global exactly as before. Local references simply use the next available slots for that clip.
If a slot is already used locally, the matching global slot is automatically reserved to avoid conflicts. References coming from a Ref Pack are also handled safely without remapping or blocking generation.
Local Pictures can be edited with the same image editor as global references, and local Video/Audio references include compact preview players directly inside the Refs panel.
All local references are fully included in Project Save/Load, so they are restored automatically with the project.
Full Batch workflows are now much safer and easier to manage.
You can interrupt a long Full Batch, keep the clips that are already computed, save the project, close ComfyUI, reload it later, and resume from where you stopped without losing completed work.
This also works with project Save/Load, so long generations can now be split across multiple sessions instead of needing to finish in one run.
Available for both Ref2VA and FL2VA.
FL2VA clips can now use up to 3 independent image guides, each placed at an exact frame_idx.
This is based on ComfyUI's native MiniMaxH3AddGuide support introduced in PR #15439.
You can now build a real visual timeline inside a single generation:
First → Guide 1 → Guide 2 → Guide 3 → Last
MiniMax H3 automatically generates the transitions between these visual anchors, opening the door to controlled transformations, pose changes, camera evolution, action staging and much more.
The Final Decode / Preview node now exposes a native ComfyUI VIDEO output.
This makes it possible to connect the final result directly to compatible video nodes such as upscalers, post-processing pipelines and video encoders, without having to reload the generated MP4 manually.
Version 2.0.0 is now available!
This release introduces FL2VA support
It also includes major speed and memory optimizations, with reduced RAM/VRAM usage, faster continuity handling, smoother preview behavior, and improved performance on longer projects.
Project save/load, preview restoration, clip continuity, and overall stability have also been improved.
MiniMax H3 Extender 2.0.0 is now the new base for the project.
Thanks to everyone testing, reporting issues, and helping improve the extension ❤️
Each clip card can now use its own LoRA.
This makes it possible to change style, motion or behavior from one clip to another while keeping the Extender’s normal continuity workflow.
The Extender now supports MiniMax H3 video references directly inside the workflow.
You can now use external video frames as <Video N> references, combine them with image references, and optionally attach the matching video audio for motion, timing, camera behavior and lip-sync guidance.
<Video 1>, <Video 2>, <Video 3> support in promptsref_video_audio_N inputs17k+5 frame structureMiniMax H3 expects reference-video frames at 24 fps, but real source videos can be 23.976, 25, 30, 45, 50, 60 fps, etc.
The Extender now accepts the original source FPS through:
ref_video_fps_1ref_video_fps_2ref_video_fps_3The reference-video frame batch is then automatically resampled to 24 fps while preserving the original duration before it is sent to H3.
This fixes cases where the end of a reference video appeared to be missing because a non-24-fps image batch was previously interpreted as if it were already 24 fps.
Typical workflow:
Load Video
↓
Get Video Components
├── images → ref_video_1
├── fps → ref_video_fps_1
└── audio → ref_video_audio_1
Video references can be combined with image references for workflows such as:
For example:
<Picture 1> defines the new character identity<Video 1> provides the original performance, timing and camera behaviorref_video_audio_1 provides the matching audio referenceThis keeps the Extender’s existing internal image-reference system fully intact while adding proper H3 Ref2VA video/audio support.
Added support for an external prompt pack through the new MiniMax H3 Prompt Pack Bridge node.
A new node MiniMax H3 Reference Pack Bridge has been added.
This allows external ComfyUI IMAGE outputs to be injected directly into the Extender’s existing internal reference slots, while keeping the current internal reference system fully intact.
You can now mix both approaches in the same workflow:
Load Image, crop/resize nodes, video frames, Kontext-style preprocessing, or any other IMAGE source<Picture N> slotThe Bridge is optional and does not replace the current reference workflow. It simply adds a flexible external entry point for advanced ComfyUI pipelines.
The Final Decode / Preview node now includes a dedicated Save Preview button.
It saves the currently assembled Extender preview exactly as shown, including:
The saved MP4 can be dragged back into ComfyUI to restore the workflow.
Each generated clip now has its own color editor, accessible directly from the clip card with the 🎨 button.
You can adjust:
The editor provides a live looping preview around the selected clip, including a short part of the previous and next clips, making it much easier to visually match colors between continuations.
Corrections are:
.ext Save/Load projectsColor correction is applied only to the decoded video and does not modify Motion Context, latent data or clip validation.
A small ✓ next to the palette indicates that a clip has an active color correction.
Full Batch correctly preserves and applies all previously configured clip corrections during final assembly.
You can therefore:
Per-clip color adjustments are stored inside .ext projects.
Loading a project restores the clip settings and color correction state, allowing you to continue exactly where you stopped.
Internal reference manager
Load Image nodes are required anymore.Portable .ext projects
Save Project now embeds the actual reference images inside the project archive.Load Project restores prompts, refs, validation state, cache, preview and resolution settings.Named clip cards
Improved audio joins (work in progress)
https://github.com/user-attachments/assets/a18cc6a5-2340-474e-9d3b-b784cd41584a
When using image references, it is strongly recommended to place a subject_definitions block at the beginning of every clip prompt.
This helps MiniMax H3 keep the same subjects, identities, clothing, visual roles and even the environment associated with a reference image from one clip to the next.
subject_definitions:
<Picture 1>is the reference image defining the exact visual appearance, identity, face, hairstyle, body proportions, clothing, accessories, and overall look of<Subject 1>, as well as the established environment and visual context of the scene.
<Picture 2>is the reference image defining the exact visual appearance, identity, face, hairstyle, body proportions, clothing, accessories, and overall look of<Subject 2>.
<Subject 1>is the exact same woman shown in<Picture 1>.
<Subject 2>is her friend, the exact same woman shown in<Picture 2>.
<Subject 3>is the same street environment and scene context established in<Picture 1>.
Place this subject_definitions block at the very beginning of every clip prompt.
The important point is that a reference image does not have to represent only a character.
A reference can also define the environment, location or visual context of the sequence.
In the example above:
<Picture 1> defines the appearance of <Subject 1><Picture 2> defines the appearance of <Subject 2><Picture 1> also defines the street environment used as <Subject 3>So the same reference image can be used both to preserve a character and to preserve the environment established by that image.
Repeating these definitions at the beginning of each clip prompt helps MiniMax H3 maintain the intended reference roles throughout the entire sequence.
Each clip has a Validated checkbox.
The validation system allows you to progressively build a long sequence without regenerating clips that have already been accepted.
When a clip is validated:
A typical workflow is:
Clip 1 → Generate
Clip 1 → Validate
Clip 2 → Generate
Clip 2 → Retry if needed
Clip 2 → Validate
Clip 3 → Generate
Clip 3 → Retry if needed
Clip 3 → Validate
This makes it possible to build a sequence one clip at a time while preserving all previously accepted generations.
Validation always forms a continuous chain from the beginning of the sequence.
For example:
Clip 1 ✅
Clip 2 ✅
Clip 3 ⬜
Clip 4 ⬜
If an earlier clip is unvalidated, every clip after it is automatically unvalidated as well, because each continuation depends on the previous generated clip.
Changing a generation parameter also invalidates the sequence when necessary. This includes changes to:
The affected clip and all dependent clips after it must then be regenerated.
In clip_by_clip mode, the Extender works on the first unvalidated clip in the sequence.
The intended workflow is therefore:
Generate → Preview → Retry if needed → Validate → Continue
This allows long MiniMax H3 sequences to be created progressively without repeatedly regenerating clips that are already approved.
Search for:
MiniMax H3 Extender
and install it directly from ComfyUI Manager.
Open a terminal in:
ComfyUI/custom_nodes/
Then run:
git clone https://github.com/tritant/ComfyUI_MiniMax_H3_Extender.git
Restart ComfyUI after installation.
The old low-level Motion Context Disk Join workflow is now considered deprecated and is no longer actively maintained.
New workflows should use the main MiniMax H3 Extender node, which now handles cache management, references, trimming, validation, preview, seam correction, project Save/Load, color correction and final assembly internally.
Thanks again to everyone testing the node and reporting edge cases.
The Extender is becoming much more comfortable to use for long H3 sequences.
5,308 followers · starred Aug 2026
ComfyUI node for MiniMax H3 that chains multiple video clips with motion context, disk caching, dynamic image references, audio reference support, and seamless final video/audio decoding.
Python
323
228 commits
updated Oct 9, 2026
A ComfyUI custom node for MiniMax H3 designed to generate long, continuous video sequences from multiple clips while preserving motion, visual continuity, and audio continuity between generations.
The node combines Ref2VA conditioning, Motion Context, disk caching, multi-clip generation, image references, audio references, and final video/audio decoding into a much simpler workflow.
This is probably the final feature release of MiniMax H3 Extender.
Apart from possible bug fixes or compatibility corrections, I do not currently plan to continue active development of this project.
A new optional Latent Refine / Upscale mode is now available, inspired by the latent refine work introduced in PR #83.
When enabled, each clip is generated normally, then its latent is upscaled and passed through a second H3 refine pass before continuing through the Extender’s existing cache, Motion Context, preview and export pipeline.
There is no separate draft/refine workflow: the refined result becomes the clip’s final result directly.
Refine settings include:
The same H3 model is reused for both passes, and the required latent upscaler model is downloaded automatically on first use.
MiniMax H3 Extender can now continue from an existing video.
continue_existing_video input.<Picture N> reference, useful for preserving character identity when the end of the source video does not show the subject clearly.This makes it possible to take an existing video and continue building it directly inside the Extender.
Full Batch can now optionally save each final clip as a separate video file using the new Save Individual Clips option in Final Decode / Preview.
The option is disabled by default, so the existing Full Batch workflow remains unchanged unless explicitly enabled.
When enabled, individual clips are exported only after all normal processing is complete. They use the same final video segments as the assembled output, including seam correction, per-clip color adjustments and FL2VA visible-frame trimming/handoffs.
Audio is captured during the same final PCM assembly pass used for the complete video, so no additional audio reconstruction pass is required.
No additional sampling or VideoVAE decode is introduced. Individual video streams are reused with stream-copy and saved in a dedicated folder beside the final assembled video.
Supported in:
.ext project save after a successful Full BatchAdded a new New Project button to quickly start from a completely clean state.
It clears all current project data and cached references, removes prompts, resets the timeline to a single empty clip, and wipes previous computed/validated state — while keeping all global node settings unchanged.
Useful when switching to a completely different project and helps prevent old references or cached project data from carrying over into the next generation.
Ref2VA now includes a Motion Context ON/OFF option.
With Motion Context OFF, clips are fully independent from each other. This means you can insert, rerender, or invalidate any clip without invalidating the clips before or after it, making random-access editing much more flexible.
The trade-off is that there is no continuity between clips: each clip is generated as a separate shot, so characters, framing, camera position, motion, and scene composition are not automatically carried over from one clip to the next.
Use Motion Context ON when you want continuous multi-clip motion and seamless progression, and Motion Context OFF when you prefer independent shots and easier editing.
Ref2VA clips can now use their own local Picture, Video and Audio references in addition to the existing global references.
Each clip gets a compact Refs panel where local references can be added, removed and previewed without cluttering the main card UI.
Local references use the normal H3 slot numbering and share the same limits as global references:
Global references remain global exactly as before. Local references simply use the next available slots for that clip.
If a slot is already used locally, the matching global slot is automatically reserved to avoid conflicts. References coming from a Ref Pack are also handled safely without remapping or blocking generation.
Local Pictures can be edited with the same image editor as global references, and local Video/Audio references include compact preview players directly inside the Refs panel.
All local references are fully included in Project Save/Load, so they are restored automatically with the project.
Full Batch workflows are now much safer and easier to manage.
You can interrupt a long Full Batch, keep the clips that are already computed, save the project, close ComfyUI, reload it later, and resume from where you stopped without losing completed work.
This also works with project Save/Load, so long generations can now be split across multiple sessions instead of needing to finish in one run.
Available for both Ref2VA and FL2VA.
FL2VA clips can now use up to 3 independent image guides, each placed at an exact frame_idx.
This is based on ComfyUI's native MiniMaxH3AddGuide support introduced in PR #15439.
You can now build a real visual timeline inside a single generation:
First → Guide 1 → Guide 2 → Guide 3 → Last
MiniMax H3 automatically generates the transitions between these visual anchors, opening the door to controlled transformations, pose changes, camera evolution, action staging and much more.
The Final Decode / Preview node now exposes a native ComfyUI VIDEO output.
This makes it possible to connect the final result directly to compatible video nodes such as upscalers, post-processing pipelines and video encoders, without having to reload the generated MP4 manually.
Version 2.0.0 is now available!
This release introduces FL2VA support
It also includes major speed and memory optimizations, with reduced RAM/VRAM usage, faster continuity handling, smoother preview behavior, and improved performance on longer projects.
Project save/load, preview restoration, clip continuity, and overall stability have also been improved.
MiniMax H3 Extender 2.0.0 is now the new base for the project.
Thanks to everyone testing, reporting issues, and helping improve the extension ❤️
Each clip card can now use its own LoRA.
This makes it possible to change style, motion or behavior from one clip to another while keeping the Extender’s normal continuity workflow.
The Extender now supports MiniMax H3 video references directly inside the workflow.
You can now use external video frames as <Video N> references, combine them with image references, and optionally attach the matching video audio for motion, timing, camera behavior and lip-sync guidance.
<Video 1>, <Video 2>, <Video 3> support in promptsref_video_audio_N inputs17k+5 frame structureMiniMax H3 expects reference-video frames at 24 fps, but real source videos can be 23.976, 25, 30, 45, 50, 60 fps, etc.
The Extender now accepts the original source FPS through:
ref_video_fps_1ref_video_fps_2ref_video_fps_3The reference-video frame batch is then automatically resampled to 24 fps while preserving the original duration before it is sent to H3.
This fixes cases where the end of a reference video appeared to be missing because a non-24-fps image batch was previously interpreted as if it were already 24 fps.
Typical workflow:
Load Video
↓
Get Video Components
├── images → ref_video_1
├── fps → ref_video_fps_1
└── audio → ref_video_audio_1
Video references can be combined with image references for workflows such as:
For example:
<Picture 1> defines the new character identity<Video 1> provides the original performance, timing and camera behaviorref_video_audio_1 provides the matching audio referenceThis keeps the Extender’s existing internal image-reference system fully intact while adding proper H3 Ref2VA video/audio support.
Added support for an external prompt pack through the new MiniMax H3 Prompt Pack Bridge node.
A new node MiniMax H3 Reference Pack Bridge has been added.
This allows external ComfyUI IMAGE outputs to be injected directly into the Extender’s existing internal reference slots, while keeping the current internal reference system fully intact.
You can now mix both approaches in the same workflow:
Load Image, crop/resize nodes, video frames, Kontext-style preprocessing, or any other IMAGE source<Picture N> slotThe Bridge is optional and does not replace the current reference workflow. It simply adds a flexible external entry point for advanced ComfyUI pipelines.
The Final Decode / Preview node now includes a dedicated Save Preview button.
It saves the currently assembled Extender preview exactly as shown, including:
The saved MP4 can be dragged back into ComfyUI to restore the workflow.
Each generated clip now has its own color editor, accessible directly from the clip card with the 🎨 button.
You can adjust:
The editor provides a live looping preview around the selected clip, including a short part of the previous and next clips, making it much easier to visually match colors between continuations.
Corrections are:
.ext Save/Load projectsColor correction is applied only to the decoded video and does not modify Motion Context, latent data or clip validation.
A small ✓ next to the palette indicates that a clip has an active color correction.
Full Batch correctly preserves and applies all previously configured clip corrections during final assembly.
You can therefore:
Per-clip color adjustments are stored inside .ext projects.
Loading a project restores the clip settings and color correction state, allowing you to continue exactly where you stopped.
Internal reference manager
Load Image nodes are required anymore.Portable .ext projects
Save Project now embeds the actual reference images inside the project archive.Load Project restores prompts, refs, validation state, cache, preview and resolution settings.Named clip cards
Improved audio joins (work in progress)
https://github.com/user-attachments/assets/a18cc6a5-2340-474e-9d3b-b784cd41584a
When using image references, it is strongly recommended to place a subject_definitions block at the beginning of every clip prompt.
This helps MiniMax H3 keep the same subjects, identities, clothing, visual roles and even the environment associated with a reference image from one clip to the next.
subject_definitions:
<Picture 1>is the reference image defining the exact visual appearance, identity, face, hairstyle, body proportions, clothing, accessories, and overall look of<Subject 1>, as well as the established environment and visual context of the scene.
<Picture 2>is the reference image defining the exact visual appearance, identity, face, hairstyle, body proportions, clothing, accessories, and overall look of<Subject 2>.
<Subject 1>is the exact same woman shown in<Picture 1>.
<Subject 2>is her friend, the exact same woman shown in<Picture 2>.
<Subject 3>is the same street environment and scene context established in<Picture 1>.
Place this subject_definitions block at the very beginning of every clip prompt.
The important point is that a reference image does not have to represent only a character.
A reference can also define the environment, location or visual context of the sequence.
In the example above:
<Picture 1> defines the appearance of <Subject 1><Picture 2> defines the appearance of <Subject 2><Picture 1> also defines the street environment used as <Subject 3>So the same reference image can be used both to preserve a character and to preserve the environment established by that image.
Repeating these definitions at the beginning of each clip prompt helps MiniMax H3 maintain the intended reference roles throughout the entire sequence.
Each clip has a Validated checkbox.
The validation system allows you to progressively build a long sequence without regenerating clips that have already been accepted.
When a clip is validated:
A typical workflow is:
Clip 1 → Generate
Clip 1 → Validate
Clip 2 → Generate
Clip 2 → Retry if needed
Clip 2 → Validate
Clip 3 → Generate
Clip 3 → Retry if needed
Clip 3 → Validate
This makes it possible to build a sequence one clip at a time while preserving all previously accepted generations.
Validation always forms a continuous chain from the beginning of the sequence.
For example:
Clip 1 ✅
Clip 2 ✅
Clip 3 ⬜
Clip 4 ⬜
If an earlier clip is unvalidated, every clip after it is automatically unvalidated as well, because each continuation depends on the previous generated clip.
Changing a generation parameter also invalidates the sequence when necessary. This includes changes to:
The affected clip and all dependent clips after it must then be regenerated.
In clip_by_clip mode, the Extender works on the first unvalidated clip in the sequence.
The intended workflow is therefore:
Generate → Preview → Retry if needed → Validate → Continue
This allows long MiniMax H3 sequences to be created progressively without repeatedly regenerating clips that are already approved.
Search for:
MiniMax H3 Extender
and install it directly from ComfyUI Manager.
Open a terminal in:
ComfyUI/custom_nodes/
Then run:
git clone https://github.com/tritant/ComfyUI_MiniMax_H3_Extender.git
Restart ComfyUI after installation.
The old low-level Motion Context Disk Join workflow is now considered deprecated and is no longer actively maintained.
New workflows should use the main MiniMax H3 Extender node, which now handles cache management, references, trimming, validation, preview, seam correction, project Save/Load, color correction and final assembly internally.
Thanks again to everyone testing the node and reporting edge cases.
The Extender is becoming much more comfortable to use for long H3 sequences.
5,308 followers · starred Aug 2026