ComfyUI-MiniMaxH3-Easy Introduction
ComfyUI-MiniMaxH3-Easy is a set of ComfyUI nodes that makes MiniMax H3 video and image workflows easier to build and manage. It brings common tasks, such as turning a written idea into a video, animating an image, guiding a video with references, and creating a digital human with audio, into a more consistent workflow.
Its visual Media Loader keeps images, videos, and audio clips together. You can refer to those assets directly in a prompt by typing @, instead of writing special reference tags yourself. For longer videos, Context Segments lets you plan connected shots, give each shot its own instructions, and carry continuity forward from the previous shot.
The extension also includes an H3 Image workflow for text-to-image generation and reference-image editing. Its nodes remain compatible with ordinary ComfyUI connections, so you can still use samplers, LoRAs, decoders, and save nodes in your workflow.
MiniMax H3 Easy Media Loader and main node
How ComfyUI-MiniMaxH3-Easy Works
Think of a workflow as a small production line. The Easy Loader supplies the models, the Media Loader supplies any pictures, footage, or sound, and the MiniMax H3 Easy node combines them with your prompt and generation settings. The resulting H3 Context passes to an output or sampling node, where ComfyUI produces the result.
A typical video workflow follows this pattern:
Easy Loader → MiniMax H3 Easy → Easy Output → sample / decode / save
You can start with the basic example workflow. Select the appropriate models, choose a generation mode, write a prompt, add any needed media, set the resolution, aspect ratio, and duration, then queue the workflow.
References work like named ingredients in a shot description. If you add an image of a character and type @ in the prompt, the editor lets you select that image. At generation time, the extension converts your visible reference into the format H3 expects. Images, videos, and audio have separate numbering, so @Image1, @Video1, and @Audio1 can appear in the same prompt.
Long videos work as a sequence of connected shots. Context Segments gives each shot its own prompt and duration. A continuity mode carries information from the previous shot into the next, while each shot uses only the reference media explicitly mentioned in its own prompt. This helps you keep a character or action moving across shots without sending every reference to every shot.
ComfyUI-MiniMaxH3-Easy Features
Video Generation Modes
| What you want to make | Mode and media |
|---|---|
| A video from a written prompt | Choose I2V or First/Last Frame or Reference-to-video; connect no media |
| A video that starts from an image | Choose I2V or First/Last Frame; connect one image |
| A video guided by its opening and ending images | Choose I2V or First/Last Frame; connect two images |
| A video guided by several references | Choose Reference-to-video; connect images, videos, or standalone audio, including at least one image or video |
| A digital human driven by sound | Choose Digital Human; connect visual references and exactly one driving audio track |
When two first/last-frame images do not match your chosen canvas shape, the extension center-crops them rather than stretching them. In Digital Human mode, the single audio item becomes the driving track in the result. If you provide no audio, the node falls back to ordinary reference-to-video generation.
Visual Media Management
The Media Loader gives you one place to upload, drag, paste, preview, reorder, replace, disable, or remove images, videos, and audio. Video cards show duration, while audio cards have a play/pause control for checking a clip. You can drag supported files from your file manager, or select only the Media Loader node and press Ctrl+V to paste supported clipboard media.
Disabling a card keeps it in your saved library but excludes it from loading and prompt optimization. This is useful when you want to compare references without deleting and re-adding them. Enabled media is renumbered within its type; references in the editor update when cards are toggled or swapped. A reference to an unavailable number remains pending in the editor but is not used for generation until that number is available again.
You have four ways to supply media:
| Method | When it is useful |
|---|---|
| Media Loader | Everyday visual management of a shared media library |
| Direct Media-port links | Connecting ordinary ComfyUI image, video, or audio nodes |
| Media Bridge | Workflows needing explicit numbered inputs, including API or headless use |
| Media Splitter | Sending items from one Media Bundle to other ComfyUI nodes as separate outputs |
Only the Media Loader caches decoded video references. Reusing an unchanged reference video can therefore reduce its preparation time on later runs; it does not shorten the model’s sampling time. Long or high-resolution reference videos can consume substantial system RAM.
Prompt Editing and Optimization
Type @ in a reference or context prompt to choose connected media from a popup. Type # to create a dialogue block, which the extension converts to H3’s dialogue format when the workflow runs. The editor can show a structured view or a raw prompt view. If you connect an external STRING prompt, that string is used and the built-in editor becomes read-only.
Prompt optimization is optional. You can click the ✦ control to optimize a prompt manually or enable optimization when a workflow runs. The available connections include OpenAI-compatible Chat Completions, OpenAI Responses, Gemini Native, and Ollama. Settings also include optional reading of connected media and mode-specific H3 prompt guides. English and Chinese prompt modes are available.
For a segmented video, the durations tell the optimizer how many shot prompts to produce. For example, 5,5,5 calls for three prompts separated by ---. Whole sequence optimization considers the story together; Per segment optimization revises the shots separately while using earlier original shots as continuity context. Automatic optimization remembers prompts it has already processed and does not rewrite an unchanged prompt on every run.
API settings are stored in prompt_optimizer.json in the plugin directory. API keys in that file are plain text, so do not publish or upload it.
Prompt optimization and view controls
Connected Video Segments
Context Segments is for videos that need more than one connected shot. Separate shot prompts with a line containing only ---, or type ~ in the structured editor to insert a divider. Enter a matching list of durations in Segment seconds: 5,5,5 means three five-second segments. Connect H3 Context to Segment Sample to generate the first-pass sequence.
Use @ in each segment prompt to identify the media that shot should use. A shared library does not mean every shot receives every asset. If the same image should guide shots one and three, mention it in both prompts. An unmentioned asset is not supplied directly to that shot, although the shot can still receive continuity from the preceding segment.
The standard Context Segments workflow generates a chain. The per-segment control workflow adds Segment Step nodes, each with its own seed and optional prompt override. This is useful when you need finer control over individual shots or want to rerun an affected part.
| Continuity mode | What it carries into the next segment | Available context-frame counts |
|---|---|---|
| Motion Context | Time-aligned motion information from the previous video segment; a useful starting point | 5 / 22 / 39 / 56 / 73 |
| RGB Guide | A multi-frame visual guide made from the previous segment’s ending | 5 / 22 / 39 / 56 / 73 |
| Soft AV Prefix | Video and audio from the previous segment, with a softer audio release at the boundary | 39 / 90 / 141 |
| Hard AV Prefix | Strictly preserved overlapping video and audio | 39 / 90 / 141 |
If keeping a speaker’s or singer’s voice consistent matters, an AV Prefix mode or a clear audio reference is a better choice than RGB Guide alone. Context Segments also supports Digital Human audio: one connected audio item can be sliced across the complete timeline and used as the final soundtrack.
Refinement and Output
Segment Refine works on one segment at a time and passes its refined result onward, keeping different shots’ prompts and references separate.
- Pixel Resize decodes, resizes, and re-encodes a segment. It does not require a separate latent upscaler model and reuses the first-pass model.
- Latent Upscale uses an H3 3D latent upscaler instead of resizing pixels.
- Low VRAM Tile processes spatial tiles of the current segment, trading more sampling time for lower VRAM use.
The segment refinement workflow contains Pixel Resize and Latent Upscale in separate groups; its Latent Upscale group with a three-step custom Sigma is enabled by default. Segment Decode decodes segments one at a time to temporary video files and returns a complete ComfyUI video with audio, avoiding the need to keep the full decoded timeline in memory. It requires FFmpeg, using imageio-ffmpeg when available or FFmpeg on the system PATH.
H3 Image
The H3 Image example workflow supports both text-to-image generation and editing guided by reference pictures. Leave its Media Loader empty to create an image from text, or add pictures to guide an edit. The dedicated Easy Image node shares the visual Media Loader, multi-link media input, @ references, and prompt-optimizer API settings used by the video workflows. This workflow requires ComfyUI 0.45.0 or newer.
H3 Image workflow and generated image
ComfyUI-MiniMaxH3-Easy Models
The extension selects several model roles; the provided context does not name specific model files. Choose a file that matches each role rather than assuming any file shown in a model menu will work.
| Model role | What it is used for |
|---|---|
| FL2VA transformer | Preferred for regular text and image-based video generation when both transformer types are configured |
| Ref2VA transformer | Preferred for full-reference video generation when both types are configured |
| Text encoder | Processes written prompts; the H3 video text encoder can also be reused for H3 Image |
| Video VAEs | Handle the video workflow’s encoded visual and audio representations |
| H3 Image model and dedicated image VAE | Used by the text-to-image and reference-image editing workflow |
| H3 3D latent upscaler | Needed when you choose Latent Upscale refinement; not needed for Pixel Resize |
If you configure only one video transformer, it serves all video modes. The Easy Loader lets you select FL2VA, Ref2VA, the text encoder, and both VAEs. The Model Adapter allows suitable models supplied by other native, community, or GGUF loaders to be connected instead. Some example workflows may also require additional models, LoRAs, or custom nodes.
What’s New with ComfyUI-MiniMaxH3-Easy
The supplied documentation describes these additions and changes, but does not provide a version-by-version changelog for this extension. They are listed here without assigning release numbers:
- H3 Image support: One example workflow now covers text-to-image creation and reference-image editing.
- Broader model selection: The Easy Loader shows available files from the corresponding ComfyUI model directories without its former filename whitelist or naming filters. You still need to select the right file for each role.
- More flexible media handling: Dragging and pasting supported files places them in the appropriate Media Loader category; audio cards provide quick playback, and video cards show duration.
- Improved reference editing:
@references stay aligned with enabled media order as cards are toggled or swapped. Temporarily unavailable references remain pending rather than being silently redirected to another asset. - Digital Human audio handling: A single audio item serves as the driving track; with no audio, the mode falls back to reference-to-video.
- More control over long videos: Segment Step workflows provide per-segment seeds and optional prompt overrides, alongside the simpler all-at-once Segment Sample workflow.
- Combined refinement example: Pixel Resize and Latent Upscale are available as separate groups in one Context Segments refinement workflow. Pixel Resize reuses the first-pass model.
- Context-aware prompt optimization: The optimizer can produce a specified number of segment prompts from one idea or improve an existing sequence while keeping each shot’s purpose and order.
Troubleshooting ComfyUI-MiniMaxH3-Easy
A reference is visible in the prompt but is not affecting the result.
- Check that the referenced media card is enabled.
- Check that its
@reference points to an available item of the correct type. - In Context Segments, repeat the
@reference inside each shot that needs it. Media in the shared library is not automatically used by every shot.
Text-to-video runs when you expected reference-guided video.
- Check that you connected media to the chosen mode.
- For
Reference-to-video, include at least one image or video; standalone audio alone does not meet that mode’s visual-reference requirement. - For Digital Human, supply exactly one driving audio track. Without one, the mode falls back to ordinary reference-to-video.
The built-in prompt editor cannot be changed.
- Check whether an external
STRINGinput is connected to the prompt. - If it is, edit that external text instead. The built-in editor is read-only while the connection supplies the prompt.
A long-video shot ignores an image used in the preceding shot.
- Find that shot’s own prompt between its
---dividers. - Add the image’s
@reference there. References do not carry over automatically, even when visual continuity information does.
A refined workflow cannot use Latent Upscale.
- Confirm that the matching H3 3D latent upscaler is available to the workflow.
- If you do not intend to use an upscaler model, choose the Pixel Resize group instead.
Segment Decode does not produce the expected complete video.
- Check for an FFmpeg-related error in ComfyUI.
- Make sure
imageio-ffmpegor an FFmpeg executable on the system PATH is available. Segment Decode needs one of them.
Reference videos take time to prepare or use too much system memory.
- Where practical, use the Media Loader so unchanged decoded video references can be reused through ComfyUI’s cache.
- Consider shorter or lower-resolution reference footage when system RAM is limited. Caching saves repeated decoding time, but cached video frames can use substantial RAM.
A widget’s input area looks unusually wide or narrow.
The original documentation identifies this as a ComfyUI frontend issue. Most users will not need a workaround. If it affects your workflow, ComfyUI-LegacyWidgetWidthFix can help, but a Legacy Widget Width Fix node must also be kept in the workflow; installing that plugin alone does not activate the fix.
Frequently asked questions
- Do I need prompt optimization to generate an image or video? No. It is optional; you can write and use your own prompts.
- Can I use both pictures and sound as references? Yes, within the limits of the selected mode. A regular reference generation supports up to 9 images, 3 videos, and 3 standalone audio clips, with no more than 15 media items in total.
- How large can a Context Segments media library be? Its shared library supports up to 27 images, 9 videos, and 9 audio clips. Each individual segment still follows the regular per-call reference limits.
- Will rerunning an unchanged segment workflow always use a cached result? Not with the regular Segment Sample and Segment Refine nodes: they currently execute again on every queue. The per-segment control workflow can use ComfyUI’s native cache for unchanged preceding Steps.
- Does the extension work with different ComfyUI canvases? The documentation states support for both the classic canvas and Nodes 2.0.
Learn More about ComfyUI-MiniMaxH3-Easy
The example workflow collection is the best place to explore the extension in ComfyUI. Start with the basic video workflow, then move to the standard connected-segments workflow when you need a longer sequence. For individual shot controls, use the Segment Step example; for a higher-resolution second pass, explore the refinement example. The H3 Image workflow demonstrates still-image creation and editing.
The extension’s context-continuity design was inspired by H3 Motion Context and ComfyUI-MiniMaxH3-Contex-Loop. These are related projects, not instructions or features to assume are present in ComfyUI-MiniMaxH3-Easy.
