MiniMax H3 Easy:
MiniMaxH3Easy is an all-in-one MiniMax H3 generation node for creating video content from text, images, reference videos, or audio-driven digital-human inputs. It prepares the selected media and generation settings for the MiniMax H3 model, supports text-to-video, image-guided animation, first/last-frame workflows, reference-to-video generation, and digital-human generation, and creates the latent video and audio information needed by later sampling and decoding nodes. You can use it as the main preparation stage for a range of H3 workflows, while the node automatically selects the appropriate generation path, model role, canvas dimensions, frame count, conditioning information, and media handling based on your chosen mode and connected resources.
MiniMax H3 Easy Input Parameters:
h3_bundle
This required input accepts a MiniMax H3 loader bundle containing the model resources needed for generation, including the video and audio components used by the H3 workflow. You must connect a compatible MiniMax H3 Easy Loader bundle; otherwise, the node stops with the error Connect a MiniMax H3 Easy Loader bundle. The bundle also determines which transformer model is used for the selected generation path. No default value is provided.
mode
This required menu selects the general generation workflow. Available options are Image, Reference Video, and Digital Human, with Image as the default. Image is used for text-to-video and image-guided workflows, including optional first-frame or last-frame images. Reference Video uses connected reference media to guide the generated result. Digital Human is an audio-driven reference-to-video workflow; it requires an audio input to remain in digital-human mode, and automatically falls back to the ordinary reference workflow when no audio is connected.
prompt
This required multiline text field contains the description of the scene, action, appearance, camera behavior, and other visual or cinematic details you want the model to generate. Its default is an empty string, and dynamic prompt processing is enabled. The prompt is used to create the generation conditioning and can also be processed by the optional prompt optimizer when optimizer settings are enabled and the prompt is not connected from another node. In digital-human mode, audio references are handled separately and audio marker expressions such as <Audio 1> are removed before generation.
resolution
This required menu controls the target pixel area used for the generated canvas. Its default is 480 and the available choices are the values defined by the node's resolution list, including the default 480 option. For a standard resolution choice, the node combines this setting with aspect_ratio to calculate the width and height while keeping the selected approximate megapixel level. Selecting the custom resolution option, when available in the configured resolution list, makes the node use width and height instead. The calculated dimensions are aligned to the model's required dimension step.
aspect_ratio
This required menu controls the shape of the generated video canvas. Its default is widescreen and the available choices are the aspect-ratio values defined by the node's configured aspect-ratio list. The selected ratio affects the calculated width and height whenever resolution is not set to custom. A widescreen ratio is generally suitable for landscape video, while other available ratios can be used when you need a different composition format. The node adjusts the resulting dimensions to valid model-aligned values.
width
This required integer controls the custom canvas width when resolution is set to the custom option. Its default is 1344, its minimum is 32, its maximum is nodes.MAX_RESOLUTION, and its step is 32. Larger values provide more horizontal detail but require more memory and processing time. When a non-custom resolution is selected, the node calculates the effective width from resolution and aspect_ratio instead of using this value directly.
height
This required integer controls the custom canvas height when resolution is set to the custom option. Its default is 768, its minimum is 32, its maximum is nodes.MAX_RESOLUTION, and its step is 32. Larger values provide more vertical detail but increase memory use and generation time. When a non-custom resolution is selected, the node calculates the effective height from resolution and aspect_ratio instead of using this value directly.
seconds
This required floating-point value sets the requested video duration in seconds. Its default is 5.0, its minimum and maximum are controlled by MIN_SECONDS and MAX_SECONDS, and its step is 0.1. The node clamps the value to that allowed range and converts it into a model-compatible frame count using the selected fps. Longer clips generally require more memory and processing time, while shorter clips are useful for quick tests and compact animations.
advanced
This required boolean switch defaults to False. It is exposed as an advanced-workflow control, but the provided generate implementation does not directly use its value when preparing the model, conditioning, or latent data. You can leave it disabled for the normal workflow. Its presence allows the node interface to remain compatible with the surrounding MiniMax H3 workflow controls.
fps
This required floating-point value sets the requested playback frame rate. Its default is 24.0, its minimum is 1.0, its maximum is 120.0, and its step is 1.0. The frame rate is used together with seconds to calculate the target number of frames, which is then rounded to the model's supported frame-length pattern. Higher frame rates can produce smoother motion but increase the number of frames and the processing requirements for the same duration.
keyframe_role
This required menu determines how a single connected image is interpreted in image mode. The available options are first and last, with first as the default. When set to first, one image is used as the opening frame; when set to last, one image is used as the ending frame. If two images are connected, the setting determines which connected image is treated as the first or last keyframe according to the node's ordering rules. This setting applies to image mode and does not replace the reference-media handling used by reference or digital-human workflows.
ref_image_size
This required menu controls the target size used when preparing reference images. Available options are match input, 1K, 1.5K, 2K, and original, with 1K as the default. The setting affects how reference images are resized or preserved before they are used for reference conditioning. Smaller reference sizes can reduce resource usage, while larger or original sizes can preserve more source detail at the cost of additional memory and processing requirements.
reference_mention_mode
This required menu selects how connected reference resources are identified when the prompt or reference-conditioning system refers to them. Available options are filename and index, with index as the default. filename identifies a resource using its source name when that information is available, while index identifies it by its connection order. Use index when you want stable references based on the order of connected media, or filename when recognizable source names are more useful in your workflow.
prompt_optimizer_settings
This required boolean controls whether the node exposes or uses the configured prompt-optimizer behavior. Its default is False. When prompt optimization is configured and enabled for the run, the node can rewrite an unconnected prompt before generation using the configured optimization settings and scene guide. The optimizer is skipped when this switch is disabled, when the prompt is empty, or when the prompt is connected from another node, preserving the connected prompt instead.
prompt_optimizer_scene_guide
This required menu selects the scene-guidance profile used by the prompt optimizer. Its default is none. The available options come from the configured prompt-guide manifest; if no guide entries are available, none is the only fallback option. The selected guide can help the optimizer interpret the intended scene type when optimization is active, but it does not directly change the prompt when optimization is disabled or unavailable.
media
This optional wildcard input accepts one direct media resource or a MiniMaxH3MediaBundle containing multiple media items. A directly connected image is treated as an image, an audio mapping containing a waveform field is treated as audio, and other supported media objects are treated as video unless their type is supplied through the virtual media inputs. In image mode, only images are accepted and no more than two images may be connected. In reference mode, connected reference media are validated and used for reference conditioning. In digital-human mode, an audio item provides the driving sound while the visual references provide the appearance. This input cannot be combined with the virtual media_1 through media_15 inputs.
prompt_optimizer_resources
This optional hidden string input carries serialized resource information for the prompt optimizer. Its default is an empty string. It is intended for workflow or frontend integration rather than manual editing, and may describe connected media or other context available to the optimizer. It does not itself create media conditioning; it supports prompt optimization when that feature is configured and active.
prompt_optimizer_marker
This optional hidden string input carries a serialized optimization marker used to identify a previously optimized prompt and its context. Its default is an empty string. The marker helps the node recognize matching optimization results and avoid unnecessary repeated optimization work. It is normally managed by the workflow or frontend and does not need to be entered manually.
prompt_optimizer_prompt_connected
This optional hidden boolean indicates whether the prompt is supplied by another connected node. Its default is False. When set to True, automatic prompt optimization is skipped so that the connected prompt is preserved exactly as the source workflow provides it. This is a hidden workflow-control input and is normally set automatically by the frontend.
media_1
This optional hidden wildcard input is the first virtual media connection used by the multi-wire media frontend. It can carry an image, video, or audio resource. The node ignores empty connections and determines the media type from media_type_1 when that value is image, video, or audio; otherwise, it infers the type from the supplied object. This input is intended as an alternative to media and should not be used with a MiniMaxH3MediaBundle connected to media.
media_type_1
This optional hidden string identifies the type of the resource connected to media_1. Its default is an empty string. Valid explicit values are image, video, and audio; any other value causes the node to infer the type from the connected object. The type affects validation and determines whether the resource is treated as a keyframe, reference video, or audio source.
media_2
This optional hidden wildcard input is the second virtual media connection. It accepts an image, video, or audio resource and is ignored when no resource is connected. Its type is taken from media_type_2 when valid, or inferred automatically otherwise. The resource participates in the same mode-specific validation and conditioning rules as other connected media.
media_type_2
This optional hidden string identifies the type of the resource connected to media_2. Its default is an empty string. Valid values are image, video, and audio. Supplying the correct type is useful when the frontend passes a generic media object whose type cannot be reliably inferred automatically.
media_3
This optional hidden wildcard input is the third virtual media connection for an image, video, or audio resource. Empty connections are skipped. A connected resource is added to the ordered media collection and can affect reference conditioning, keyframe selection, or digital-human audio handling depending on its resolved type and the selected mode.
media_type_3
This optional hidden string identifies the type of media_3. Its default is an empty string, and accepted explicit values are image, video, and audio. If it is empty or invalid, the node determines the type from the connected resource.
media_4
This optional hidden wildcard input is the fourth virtual media connection. It accepts one media resource and contributes it to the workflow when connected. The node uses the resolved media type to decide whether the resource can be used as an image keyframe, a reference resource, or an audio source.
media_type_4
This optional hidden string specifies the type of media_4. Its default is an empty string. Use image, video, or audio when an explicit type is needed; otherwise, the node falls back to automatic type inference.
media_5
This optional hidden wildcard input is the fifth virtual media connection. It can carry an image, video, or audio object and is included in the media collection only when connected. Its effect depends on the selected mode and the type resolved through media_type_5 or automatic inference.
media_type_5
This optional hidden string specifies the type of the resource connected to media_5. Its default is an empty string, with image, video, and audio accepted as explicit values. An empty or unrecognized value causes automatic type detection.
media_6
This optional hidden wildcard input is the sixth virtual media connection. It accepts a media resource for the multi-input workflow and is skipped when empty. Connected resources are processed in connection order and are subject to the selected mode's media restrictions.
media_type_6
This optional hidden string identifies the type of media_6. Its default is an empty string. Valid values are image, video, and audio; otherwise, the node infers the type from the supplied media object.
media_7
This optional hidden wildcard input is the seventh virtual media connection. It can provide an image, video, or audio resource to the node's media collection. The resource is used only if connected and valid for the selected workflow.
media_type_7
This optional hidden string identifies the type of media_7. Its default is an empty string. Set it to image, video, or audio when you need to override automatic detection; other values are treated as unspecified and trigger inference.
media_8
This optional hidden wildcard input is the eighth virtual media connection. It accepts one image, video, or audio resource and passes it into the node's ordered media-processing path. Its use is governed by the same image-mode, reference-mode, and digital-human validation rules as the other media inputs.
media_type_8
This optional hidden string identifies the type of media_8. Its default is an empty string. Accepted explicit types are image, video, and audio. If no valid type is supplied, the node infers one from the resource.
media_9
This optional hidden wildcard input is the ninth virtual media connection. It provides an additional image, video, or audio resource when connected. It is useful for workflows that need more reference material than can be provided through the direct media input.
media_type_9
This optional hidden string specifies the type of media_9. Its default is an empty string. Use image, video, or audio for explicit classification, or leave it empty to allow automatic detection.
media_10
This optional hidden wildcard input is the tenth virtual media connection. It carries one optional media resource into the node and is included only when a value is present. The resolved type determines how the resource participates in generation.
media_type_10
This optional hidden string identifies the type of media_10. Its default is an empty string. Valid explicit values are image, video, and audio; invalid or empty values cause the node to infer the type.
media_11
This optional hidden wildcard input is the eleventh virtual media connection. It accepts an optional image, video, or audio resource and adds it to the node's media collection when connected. It follows the same ordering and validation behavior as the other virtual media inputs.
media_type_11
This optional hidden string identifies the type of media_11. Its default is an empty string. Specify image, video, or audio when needed, or leave it empty for automatic type inference.
media_12
This optional hidden wildcard input is the twelfth virtual media connection. It provides another optional media slot for multi-reference and media-driven workflows. The node skips it when no value is connected and validates the resolved resource type against the selected mode.
media_type_12
This optional hidden string identifies the type of media_12. Its default is an empty string. Accepted explicit values are image, video, and audio; otherwise, the type is inferred automatically.
media_13
This optional hidden wildcard input is the thirteenth virtual media connection. It accepts an optional image, video, or audio resource and contributes it to reference, keyframe, or audio processing according to its resolved type.
media_type_13
This optional hidden string specifies the type of media_13. Its default is an empty string. Use one of image, video, or audio for explicit classification, or leave it empty for automatic detection.
media_14
This optional hidden wildcard input is the fourteenth virtual media connection. It carries an optional media resource into the workflow and is processed only when connected. Its compatibility depends on the selected mode and its resolved media type.
media_type_14
This optional hidden string identifies the type of media_14. Its default is an empty string. Valid explicit values are image, video, and audio; any other value results in automatic type inference.
media_15
This optional hidden wildcard input is the fifteenth and final virtual media connection. It accepts an optional image, video, or audio resource for workflows requiring multiple connected references or media sources. Empty connections are ignored, while connected resources are processed in order.
media_type_15
This optional hidden string identifies the type of media_15. Its default is an empty string. Set it to image, video, or audio when explicit classification is required; otherwise, the node infers the type from the connected resource.
MiniMax H3 Easy Output Parameters:
model
This output provides the selected MiniMax H3 model in the standard MODEL format. The node chooses the model role based on the workflow: image, text-to-video, and first/last-frame workflows use the FL2VA path, while reference-video and digital-human workflows use the REF2VA path. The loader bundle may provide separate models for these roles, and the surrounding implementation can use a compatible fallback model when only one H3 transformer is installed. Connect this output to the downstream sampling or generation node that expects a model.
h3_context
This output provides the prepared MiniMax H3 context in the MINIMAX_H3_CONTEXT format. It contains the conditioning information, prepared video and audio latent data, video and audio VAE references, the selected frame rate, aspect-ratio information, and any applicable keyframe or digital-human audio information. This context is essential because it carries the scene preparation and media guidance produced by the node into later sampling and decoding stages. It is not an image or video preview by itself; it is the structured generation data that downstream MiniMax H3 nodes use to create the final result.
MiniMax H3 Easy Usage Tips:
- Start with
modeset toImageand no media connected when testing a text-to-video prompt. This uses the standard image-generation preparation path and makes it easier to confirm that the loader, model, and basic prompt are working. - Use one image with
keyframe_roleset tofirstfor an opening-frame animation, or set it tolastwhen the image should define the ending frame. With two images, use the role setting to control how the connected images are assigned to the beginning and ending of the clip. - In image mode, connect only images. The node accepts at most two images in this mode and reports an error if videos or audio are included.
- Use
Reference Videowhen the connected media should guide the generated result as reference material rather than act as first or last keyframes. Reference media are validated separately from image-mode keyframes. - Use
Digital Humanonly when an audio resource is connected along with the visual reference material. The audio track drives the digital-human variant and is locked into the prepared latent so it is not denoised like generated audio. - Keep
resolutionat its default while developing prompts, then increase it after the motion and composition are working. Higher resolution increases memory use and processing time. - Use
aspect_ratiofor normal preset canvas sizes. Use the custom resolution option, when available, only when you need exact dimensions, and keepwidthandheightat valid aligned values within their allowed limits. - Keep
fpsat24.0for a practical general-purpose setting. Increase it when smoother motion is important, but remember that a higher frame rate creates more frames for the samesecondsvalue. - Begin with short durations near the default
5.0seconds when testing. Longer durations increase the amount of latent data and can significantly increase generation time and memory requirements. - Set
ref_image_sizeto1Kfor a balanced reference workflow. Use1.5K,2K, ororiginalwhen preserving more source detail is more important than minimizing resource use. - Leave
reference_mention_modeatindexwhen you want references to be identified consistently by their connection order. Usefilenamewhen source names are more useful for organizing reference-heavy workflows. - Enable prompt optimization only when it is configured in the surrounding installation and you want the node to improve an unconnected prompt automatically. Keep
prompt_optimizer_prompt_connectedenabled for externally generated prompts that must not be rewritten. - Connect either the direct
mediainput or the virtualmedia_1throughmedia_15inputs. Do not combine aMiniMaxH3MediaBundleonmediawith virtual media inputs, because the node intentionally rejects both transport methods being used together.
MiniMax H3 Easy Common Errors and Solutions:
Connect a MiniMax H3 Easy Loader bundle
- Explanation: The required
h3_bundleinput is missing or contains an object that is not a MiniMax H3 loader bundle. The node cannot find the model and VAE resources needed to prepare the generation. - Solution: Connect the output of a compatible MiniMax H3 Easy Loader to
h3_bundleand verify that the loader completed successfully before running the workflow.
Image mode accepts image resources only
- Explanation:
modeis set toImage, but one or more connected media items were identified as video or audio. Image mode supports text-to-video and image keyframes, not mixed media types. - Solution: Remove the video or audio connections, connect only image resources, or change
modetoReference VideoorDigital Humanwhen those media types are intended.
Image mode accepts at most two images
- Explanation: More than two image resources were connected while
modewas set toImage. The node supports zero, one, or two images for its first-frame and last-frame preparation. - Solution: Disconnect the extra images or switch to a reference workflow when you need to provide more visual reference material.
Media Loader/Bridge and virtual media inputs cannot be used together
- Explanation: A
MiniMaxH3MediaBundlewas connected tomediawhile one or more virtual inputs frommedia_1throughmedia_15were also populated. The node requires one media transport method at a time. - Solution: Keep the media bundle on
mediaand clear all virtual media inputs, or disconnect the bundle and connect the individual resources through the virtual inputs.
Connect a media bundle to the Media input, not a virtual media input
- Explanation: A
MiniMaxH3MediaBundlewas connected to one of the virtual media inputs instead of the directmediainput. - Solution: Move the media bundle connection to
media. Usemedia_1throughmedia_15only for individual media resources.
Reference Video mode requires at least one MiniMax H3 transformer model.
- Explanation: The selected reference workflow needs an H3 transformer, but the loader bundle does not provide a usable REF2VA or fallback transformer model.
- Solution: Install or select at least one compatible MiniMax H3 transformer in the loader bundle, then reconnect or reload the bundle.
Text-to-video and I2V or First/Last Frame mode require at least one MiniMax H3 transformer model.
- Explanation: The image or first/last-frame workflow cannot find a usable FL2VA model or fallback transformer in the connected bundle.
- Solution: Configure a compatible MiniMax H3 transformer in the loader, verify the model path, and reconnect the resulting bundle.
Digital-human generation does not produce the expected result
- Explanation: Digital-human mode is audio-driven. If no media item is resolved as
audio, the node automatically changes the workflow to ordinary reference mode instead of using the digital-human path. - Solution: Connect a valid audio resource, ensure its type is correctly identified as
audiothrough the relevantmedia_typeinput when using virtual media, and provide the visual reference resources needed for the subject.
Prompt optimization did not produce the required segments for the configured segment durations
- Explanation: This error belongs to the prompt-optimization path and can occur when an optimizer request is expected to produce multiple prompt segments but returns a different number of segments. It may also indicate that the source prompt contains fewer segments than the configured duration list.
- Solution: Make the prompt contain the required number of clearly separated segments, correct the configured segment durations, or disable prompt optimization and run with the original prompt.
Resolution or frame settings exceed available resources
- Explanation: Very large
resolution, customwidthorheight, longsecondsvalues, or highfpssettings create a larger generation workload. This can lead to memory errors or extremely long processing times even when the node inputs are valid. - Solution: Test with the default
480resolution,5.0seconds, and24.0fps. Reduce custom dimensions or duration first, then increase settings gradually after the workflow succeeds.
Reference media is rejected or produces weak guidance
- Explanation: The connected reference resources may not match the selected mode, may have an incorrectly assigned media type, or may be too large or unsuitable for the selected reference-image preparation setting.
- Solution: Confirm that each virtual
media_typevalue is exactlyimage,video, oraudioas appropriate, useReference Videofor video references, and tryref_image_sizeset to1Kbefore increasing it.
Prompt optimization is not changing the prompt
- Explanation: Optimization is skipped when the optimizer is disabled or incomplete, the prompt is empty, the prompt is connected from another node, or the optimizer configuration is unavailable. The node is designed to continue with the original prompt in these cases.
- Solution: Enable and configure prompt optimization, provide a non-empty local prompt, and ensure
prompt_optimizer_prompt_connectedisFalsewhen automatic rewriting is intended.
