MiniMax H3 Flow Director:
MiniMax H3 Flow Director is a visual storyboard and timeline tool for creating continuous videos with MiniMax H3 in ComfyUI. Rather than generating an entire long video in one operation, it works through the timeline one block at a time, treating each block as a separate generation task. It carries the decoded final image of one block into the beginning of the next, helping neighboring scenes connect visually. An image placed on a later block can also act as a destination image for that transition. This approach lets you develop a sequence of actions or scenes while keeping the active generation workload focused on an individual block. It supports text-driven generation, image-guided generation, reference-image workflows, shared visual direction, and optional audio generation. Its sequential design is intended to keep generation VRAM requirements relatively steady as the timeline grows, although storing and assembling the completed video and audio still requires memory.
MiniMax H3 Flow Director Input Parameters:
clip
Required CLIP connection for the MiniMax Qwen3-VL text encoder. This encoder turns your written directions into conditioning that the video model can use to guide appearance, subjects, and actions. Connect the encoder intended for your MiniMax H3 workflow rather than assuming an encoder from an unrelated image model will work. This connection has no numeric range or default value.
vae
Required VAE connection for the MiniMax H3 video VAE, identified in the source tooltip as minimax_h3_video_vae. A video VAE translates between the model’s compressed visual representation and visible frames; this is important both for producing the finished video and for decoding the image passed between timeline blocks. Use the compatible video VAE for your model. No numeric range or default value is specified.
sampler
Required SAMPLER connection, normally supplied by KSamplerSelect. It determines the sampling method used to turn noisy starting data into a generated video. The visible implementation uses the connected sampler rather than choosing one internally. Its behavior should be considered together with the connected sigma schedule. No sampler options or default sampler are defined by this node itself.
sigmas
Required SIGMAS connection, normally supplied by BasicScheduler. This supplies the sequence of noise levels that guides sampling, influencing how the generation progresses toward its final result. The node also applies its separate video and audio shift settings to the selected model. No default schedule, range, or list of sigma values is specified here.
timeline_data
Required STRING containing the timeline editor’s JSON state, with a default of an empty string. The editor normally manages this information automatically. The node parses it to identify generation blocks, determine whether reference mode is enabled, and prepare each block’s generation plan. This is the central source of storyboard structure, so manually replacing it with arbitrary text can disrupt execution. The complete JSON format is not included in the supplied source, so use the timeline editor rather than inventing a JSON structure.
model
Optional MODEL connection, displayed as “model (t2v/i2v).” Connect MiniMax H3 fl2va weights, identified by the tooltip as minimax_h3_fl2va_*, for operation when the timeline toolbar is set to “Refs OFF.” Although the socket is optional in the interface, the active generation mode needs its appropriate model connection. This input is lazy, meaning ComfyUI can defer evaluating it when it is not the selected model branch. No default model is supplied.
model_ref2va
Optional MODEL connection, displayed as “model (ref2v).” Connect MiniMax H3 reference-capable ref2va weights, identified as minimax_h3_ref2va_*, for operation when the timeline toolbar is set to “Refs ON.” Model selection is determined by the timeline’s reference-mode state, not simply by which socket you connect. This input is also lazy, allowing the inactive model branch to remain unevaluated. No default model is supplied.
audio_vae
Optional VAE connection for minimax_h3_audio_vae, described as supporting joint audio generation and decoding. Use this audio-specific VAE when your workflow needs generated audio; the video VAE is a separate component and should not be substituted for it. The supplied code does not show the complete handling of audio when this connection is absent, so do not assume that decoded audio will be available without it. No default or numeric range is specified.
noise
Optional NOISE connection, normally supplied by RandomNoise. In the visible implementation, this object is inspected for a seed: block zero uses that seed, and each following block adds its block index, with the result kept within an unsigned 64-bit range. If a usable seed is unavailable, the fallback is 42 plus 10007 times the block index. This gives blocks distinct but repeatable seeds. The shown code establishes seed handling; it does not establish that every property of the supplied noise object is used.
global_prompt
Optional multiline STRING, defaulting to an empty string, supplied through an input connection. It provides directions shared across all blocks, such as a consistent character description, visual style, environment, or atmosphere. The node passes it into each block’s planning stage so the storyboard can maintain a common creative direction while individual blocks describe changing actions. There is no specified text-length limit.
start_second
Optional FLOAT with a default of 0.0, minimum of 0.0, maximum of 10000.0, and step of 0.01. This is a seconds-based start-position control exposed by the interface. However, the visible execution code extracts blocks from timeline_data and does not show this value being used to trim or reposition the render. Treat the timeline as authoritative unless the complete implementation confirms additional behavior.
end_second
Optional FLOAT with a default of 5.0, minimum of 0.0, maximum of 10000.0, and step of 0.01. This exposes an end-position value in seconds. Its effect on execution is not demonstrated in the provided source excerpt, so it should not be relied on as a guaranteed render cutoff. Use the timeline’s block boundaries to define the sequence you want to generate.
duration_seconds
Optional FLOAT with a default of 5.0, minimum of 0.1, maximum of 10000.0, and step of 0.01. This exposes a duration expressed in seconds, but the visible block-extraction call uses duration_frames as its fallback duration rather than this value. Consequently, changing this control alone is not established as a way to change the rendered timeline’s length.
start_frame
Optional INT with a default of 0, minimum of 0, maximum of 1000000, and step of 1. This is a frame-based start-position control. The supplied portion of execution does not show it being consumed, so it should not be assumed to skip earlier blocks or select a render range. Define block positions and boundaries through the timeline editor for the behavior directly supported by the shown code.
end_frame
Optional INT with a default of 120, minimum of 1, maximum of 1000000, and step of 1. This provides a frame-based end-position value in the interface. No direct use of this parameter appears in the visible execution, so it is not a confirmed frame-limit control for the complete storyboard. In particular, do not assume it will truncate all generated output to 120 frames merely because that is its default.
duration_frames
Optional INT with a default of 120, minimum of 1, maximum of 1000000, and step of 1. Unlike the other exposed timing controls, this value is explicitly passed to timeline block extraction as the default block duration in frames. It therefore supplies a fallback when block extraction needs a duration, rather than necessarily overriding durations already stored in the timeline. At 24 frames per second, 120 frames corresponds to five seconds.
use_custom_audio
Optional BOOLEAN, defaulting to False. This switch is passed into the block planner to control its custom-audio behavior. The supplied excerpt does not include the planner’s rules for locating, arranging, or conditioning on custom audio, so enabling it should be paired with audio configured through the intended timeline workflow. It should not be confused with a guarantee that generated audio will be decoded without the appropriate audio VAE.
use_custom_motion
Optional BOOLEAN, defaulting to True. This is passed into each block’s planning stage to enable or disable the planner’s custom-motion handling. It can affect how motion-related timeline information contributes to a block, but the exact supported motion controls and their interpretation are not included in the supplied source. Keep it enabled when using the timeline’s intended motion features, and test changes on a short block before rendering a long sequence.
inpaint_audio
Optional BOOLEAN, defaulting to True. The interface exposes this as an audio-inpainting control, but the provided execution excerpt does not show where it is applied or how audio regions are selected. Its precise effect on preserving or regenerating audio cannot be established from the available code. Do not rely on this switch alone to protect an existing soundtrack without testing the complete workflow.
local_prompts
Optional multiline STRING with an empty-string default. It exposes a place for local prompt text, but the visible implementation constructs block prompts through the timeline planner and does not show this string being read. No format or separator rules are supplied. For dependable per-block direction, use the timeline editor rather than assuming that text entered here will override its block prompts.
segment_lengths
Optional STRING with an empty-string default. Although the interface exposes this field, the source excerpt does not show it being parsed or used to assign block lengths, and it provides no supported list format or units. Actual block extraction reads the timeline state and receives duration_frames as its fallback. Avoid treating this field as a confirmed alternative to editing timeline block durations.
frame_rate
Optional FLOAT with a default of 24, minimum of 1, maximum of 240, and step of 1. The visible code uses this value when interpreting timeline blocks and loading timeline imagery. Importantly, the output schema documents the generated video as MiniMax H3’s native 24 fps and describes the fps output as always 24.0. This control should therefore not be treated as a supported way to generate native 60 fps or 120 fps video; keeping it at 24 avoids ambiguity between timeline timing and documented playback timing.
display_mode
Optional COMBO with options “frames” and “seconds,” defaulting to “seconds.” It provides a timing-display choice for the interface. No direct role in generation is visible in the supplied execution code, so changing the display mode should not be treated as a way to change the model’s native frame rate or resample the finished video.
guide_strength
Optional STRING with an empty-string default. The interface provides this field, but the supplied source does not show how it is parsed, what values it accepts, or whether it modifies generation. No numeric minimum, maximum, or strength scale is defined. Do not assume that entering a familiar CFG value from another workflow will have a documented effect here.
custom_width
Optional INT with a default of 0, minimum of 0, maximum of 8192, and step of 1. This value is passed to the size-resolution helper together with custom_height and the connected width and height values. The resulting canvas is then resolved using the resize mode, divisibility requirement, and available starting image. A value of zero is an unset sizing value rather than a request for a zero-pixel render; the helper’s exact precedence and fallback rules are not included in the excerpt.
custom_height
Optional INT with a default of 0, minimum of 0, maximum of 8192, and step of 1. This participates in canvas sizing alongside custom_width, connected dimensions, and any available initial image. The final canvas must pass the node’s minimum-edge check and is fitted using the selected resize behavior. As with width, zero does not describe a usable rendered canvas, and the precise automatic-sizing rules are not shown.
resize_method
Optional COMBO with options “maintain aspect ratio,” “stretch to fit,” “pad,” “pad green,” and “crop,” defaulting to “crop.” It controls how images are fitted to the resolved canvas. These choices let you favor preserving proportions, filling the canvas, adding borders, or removing outer content; stretching may change a subject’s proportions. The visible code checks the resized result and applies an additional crop if it still does not exactly match the required canvas dimensions, so every block’s guiding imagery is kept at a consistent size. Exact padding and crop placement are delegated to the image helper.
divisible_by
Optional INT with a default of 32, minimum of 1, maximum of 256, and step of 1. This value is passed into canvas resolution and image resizing to help align image dimensions to a chosen multiple. Such alignment is useful because video models and their VAEs commonly operate on structured image grids. The source does not reveal whether the helper rounds upward or downward, and allowing a value in the interface does not guarantee that every resulting dimension is compatible with the model.
img_compression
Optional INT with a default of 0, minimum of 0, maximum of 100, and step of 1. When greater than zero, this value is passed to an image-compression helper after guiding imagery has been resized to the canvas. At zero, that compression step is skipped. The supplied code does not define the compression algorithm or whether larger values represent greater compression or greater quality, so inspect a short test rather than assuming a standard JPEG-quality scale.
override_audio
Optional BOOLEAN, defaulting to False. This switch is passed into block planning along with use_custom_audio and the timeline state. It participates in the planner’s audio-override behavior, but the exact precedence between timeline audio and generated audio is not included in the supplied source. Enable it only as part of a tested timeline-audio workflow rather than assuming it automatically replaces the final soundtrack in every configuration.
ref_image_size
Optional COMBO with options “match” and “max,” defaulting to “match.” It exposes a reference-image sizing policy, but the visible execution excerpt does not show where this choice is applied or what dimensions “max” selects. It should not be used as a substitute for explicit canvas sizing, which is handled separately. Use the default unless the complete reference-image workflow provides a reason to change it.
shift_video
Optional FLOAT with a default of 12.0, minimum of 0.01, maximum of 100.0, and step of 0.01. The node explicitly applies this value to the selected model through the MiniMax H3 sigma-shift operation before generating blocks. It adjusts video-related sampling behavior rather than moving the video forward or backward in time. The source does not establish a simple rule such as “higher means sharper,” so begin with the default and compare short renders when experimenting.
shift_audio
Optional FLOAT with a default of 3.0, minimum of 0.01, maximum of 100.0, and step of 0.01. This is applied alongside shift_video through the model’s sigma-shift operation and controls its audio-related sampling behavior. It is not an audio synchronization offset, volume setting, or duration setting. Keep the default as a baseline unless your MiniMax H3 workflow has tested alternative shift values.
ref_images
Optional IMAGE connection described as extra reference images for ref2va. These images are intended to provide additional visual guidance in the reference-capable workflow. Connect the appropriate reference model and enable the timeline’s reference mode when using that workflow; supplying images alone does not select the model branch. The truncated source does not establish reference-count limits, ordering rules, or how each image is assigned to a block.
ref_image_notes
Optional multiline STRING with an empty-string default. This text is passed to block planning and can supply notes associated with reference imagery. The source does not define a tagging syntax, image-numbering convention, or guaranteed mapping between individual notes and images. Use clear descriptive text consistent with the timeline workflow rather than inventing unsupported reference commands.
start
Optional FLOAT supplied through an input connection, defaulting to 0.0. No minimum, maximum, or step is specified in its schema. The visible execution excerpt accepts this value but does not show it being used, so its units and effect on rendering cannot be confirmed. Do not assume it overrides start_second or the timeline’s starting position.
end
Optional FLOAT supplied through an input connection, defaulting to 0.0. No minimum, maximum, or step is specified. Its role is not demonstrated in the visible execution, and the source does not establish whether it defines an absolute endpoint or another kind of range value. Use the timeline editor to set confirmed block boundaries rather than depending on this connection to stop generation.
duration
Optional FLOAT supplied through an input connection, defaulting to 0.0. No minimum, maximum, or step is specified. The shown execution does not use it when extracting blocks, so it is not established as an override for timeline duration. For the duration behavior directly visible in the code, configure timeline blocks and use duration_frames as the extraction fallback.
width
Optional INT supplied through an input connection, defaulting to 0, with no explicitly declared minimum or maximum. It is passed to the size-resolution helper together with custom_width, custom_height, and height. This supports providing canvas dimensions from another node, although the helper’s exact precedence between connected and custom dimensions is not available. Confirm the actual selected dimensions through the node’s width output.
height
Optional INT supplied through an input connection, defaulting to 0, with no explicitly declared minimum or maximum. It participates in resolving the canvas alongside the other size controls. The result may also depend on the initial image, resize method, and divisibility setting. Confirm the final canvas height through the corresponding output instead of assuming every requested value is preserved unchanged.
first_frame_override
Optional IMAGE connection that explicitly seeds block zero, taking priority over an image placed on the first timeline block. If an image batch is connected, the visible implementation uses only its first image. This image also participates in initial canvas resolution and is resized to the chosen canvas before generation. It is useful for starting a new sequence from an existing picture or continuing from another render’s final frame; subsequent blocks still follow the automatic last-frame continuity process.
MiniMax H3 Flow Director Output Parameters:
model
MODEL output documented as the patched model. The visible execution selects the appropriate standard or reference-capable model and applies the video and audio sigma shifts before block generation. This output makes the resulting model available for downstream connections; it is not a newly trained model or a saved model file.
positive
CONDITIONING output containing the node’s positive conditioning, meaning the encoded guidance used to direct generation toward the requested content. This is model-facing information rather than readable prompt text. Because the implementation is truncated before the return statement, the supplied source does not fully establish which block’s conditioning is returned or whether it represents more than one block; do not assume it contains the complete timeline as a reusable conditioning sequence.
latent
LATENT output containing a compressed model-space representation from generation. Latents are not directly viewable video frames and generally need a compatible decoder for visualization. The supplied excerpt does not show the final assignment or return logic, so it does not establish that this output contains every block concatenated together. For the complete decoded video, use images instead.
images
IMAGE output documented as the full concatenated, decoded video frames at 24 fps. It represents the visible result assembled from the sequential timeline blocks and can be connected directly to a compatible video-combination node such as VHS Video Combine. Although its socket type is IMAGE, it carries a frame sequence rather than necessarily a single still image; a video-combination node is what turns that sequence into a playable video file.
audio
AUDIO output documented as the full concatenated, decoded stereo waveform at 44.1 kHz. It is intended to accompany the generated frames and can be connected to VHS Video Combine. Actual audio availability depends on the audio workflow and compatible decoding components; the supplied source does not show the complete behavior when audio generation or the audio VAE is absent.
fps
FLOAT output documented as always 24.0, the native MiniMax H3 output frame rate. Connect it to your video-combination node so the frames play back at the documented speed. This output should not be confused with a guarantee that changing the frame_rate input produces a different native video rate.
width
INT output reporting the resolved video canvas width in pixels. This lets downstream nodes work with the actual rendered geometry rather than the size originally requested. It is also useful for checking the result of automatic sizing, image fitting, and divisibility handling.
height
INT output reporting the resolved video canvas height in pixels. Together with width, it describes the final frame dimensions used by the sequence. Inspect this value when troubleshooting unexpected aspect ratios or canvas adjustments.
length
INT output documented as the total rendered frame count. It describes the assembled video rather than merely an individual block’s requested duration. Dividing this count by the reported fps gives the playback duration in seconds, making it useful for checking the final sequence length.
prompt
STRING output documented as the compiled storyboard prompt. It provides a readable representation of the text direction assembled for the sequence, useful for reviewing the creative instructions produced from timeline planning. The supplied excerpt does not establish its exact formatting or separators.
last_image
IMAGE output containing the last frame of the final block. It provides a convenient still image for inspection or for starting another sequence. Connecting it to another Flow Director’s first_frame_override is a practical way to begin a continuation from the preceding render’s endpoint.
retake_info
STRING output documented as retake-window information. It is intended to communicate information associated with a retake region or window, but the supplied source does not show its format, contents, or the conditions under which it is populated. Treat it as informational text unless your downstream workflow explicitly supports its format.
MiniMax H3 Flow Director Usage Tips:
-
Start with a short timeline and keep
frame_rateat 24. Connect the returnedfpsto your video-combination node so playback follows the node’s documented native output rate. -
Match the model branch to the timeline toolbar: use
modelwithfl2vaweights for “Refs OFF,” andmodel_ref2vawithref2vaweights for “Refs ON.” Both sockets are optional in the schema, but the selected workflow still needs its appropriate model. -
Put recurring visual instructions in
global_promptand changing actions in the timeline’s individual blocks. For example, keep the same character and lighting description globally while changing the character’s activity from block to block. -
Use
first_frame_overridewhen the opening image must be explicit. It overrides the first timeline image and uses only the first image in a connected batch. -
Let the automatic final-frame handoff establish continuity between blocks. If you place an image on a later block, plan for it to act as the target transition image rather than as an unrelated replacement opening frame.
-
Establish the canvas dimensions early and begin with
divisible_byat its default of 32. Large dimensions increase the workload of every block, so validate composition and motion at a modest supported resolution before increasing it. -
Choose
resize_methodbased on the artwork: cropping can remove outer details, stretching can distort proportions, and padding can introduce visible borders. Check faces, hands, and important objects near the frame edges in a short test. -
Connect RandomNoise when you want explicit seed control. The node derives neighboring block seeds from that seed, so preserving the timeline and seed configuration helps make comparisons more controlled.
-
Begin with
shift_videoat 12.0 andshift_audioat 3.0. Change one setting at a time on a short block; these are sampling adjustments, not straightforward visual-quality or synchronization sliders. -
Use the timeline editor to manage
timeline_data. Several additional timing and text controls are exposed but have no demonstrated execution effect in the supplied excerpt, so timeline edits are the more reliable way to structure your sequence. -
Connect
images,audio, andfpsto compatible inputs on VHS Video Combine when assembling an audiovisual result. Check that your audio setup includes the MiniMax H3 audio VAE if decoded generated audio is required. -
Remember that sequential generation limits the active block workload, not all memory use. Long timelines still produce many decoded frames and audio samples, so test shorter sequences first and consider rendering separate sections if assembly becomes memory-intensive.
MiniMax H3 Flow Director Common Errors and Solutions:
MiniMax H3 Flow Director: the canvas came out %dx%d. Minimum is %dpx.
- Explanation: This error string is present in the source. The placeholders are filled with the resolved canvas width, height, and required minimum edge size. It means at least one canvas dimension is below the node’s accepted minimum; the numeric minimum itself is not provided in the excerpt.
- Solution: Set usable width and height values through the canvas controls or connected dimensions, or provide an appropriate starting image. Check the resulting dimensions after aspect-ratio and divisibility adjustments, and use the minimum printed in the actual error as your guide.
Missing model for the selected reference mode
- Explanation: This is a diagnostic description, not a verified literal error string. The timeline chooses either the standard model or the reference-capable model. Connecting only the inactive branch can leave the selected workflow without the model it needs.
- Solution: Check “Refs ON” or “Refs OFF” in the timeline toolbar. Connect compatible
ref2vaweights tomodel_ref2vafor the former, or compatiblefl2vaweights tomodelfor the latter.
Missing required input: clip, vae, sampler, sigmas, or timeline_data
- Explanation: This summarizes a possible ComfyUI input-validation problem; the exact message depends on the installed version. These inputs are required by the interface, even though the timeline string has an empty default.
- Solution: Connect the MiniMax Qwen3-VL encoder, MiniMax H3 video VAE, sampler, and sigma schedule. Make sure the timeline editor is installed and supplying valid timeline state rather than leaving the storyboard undefined.
Timeline data cannot be parsed or contains no usable blocks
- Explanation: This is a diagnostic description rather than a confirmed error message. The node depends on parsing the timeline and extracting generation blocks. Corrupted manually edited data or an uninitialized storyboard can prevent meaningful planning; the excerpt does not show exactly how those cases are reported.
- Solution: Rebuild a simple block through the timeline editor and try a short render. Avoid hand-editing the JSON without the complete schema, and check that the node’s frontend extension is loading correctly.
Model, encoder, or VAE incompatibility
- Explanation: This describes a possible compatibility failure, not a literal message from the supplied class. Unrelated model components can cause loading, encoding, sampling, or decoding errors because their internal representations may not match.
- Solution: Use MiniMax H3-compatible weights, the specified Qwen3-VL text encoder, and the H3 video VAE. Use the separate H3 audio VAE for audio decoding, and verify that the model family matches the active reference mode.
CUDA out of memory or another device-memory allocation error
- Explanation: This is a possible runtime error from the underlying processing libraries, not a quoted message from this class. Sequential blocks reduce the amount of generation work active at once, but large canvases, long individual blocks, model components, and decoded results can still exhaust available memory.
- Solution: Reduce the resolution or individual block duration, test a shorter timeline, and close other GPU-heavy processes. If the problem appears only during final assembly, render and combine shorter sections separately.
Generated audio is missing or audio decoding fails
- Explanation: This is a troubleshooting symptom rather than a confirmed literal error. Audio depends on compatible components and the configured audio workflow; the visible code does not guarantee a usable soundtrack when the audio VAE is absent.
- Solution: Connect
minimax_h3_audio_vae, verify your timeline audio settings, and inspect theaudiooutput before combining the video. Test custom-audio and override behavior on a short sequence before committing to a long render.
Output plays too quickly, too slowly, or drifts from audio
- Explanation: This is a symptom, not an exception message. A mismatch can occur when frames are combined at an inappropriate playback rate. The node documents its output as 24 fps even though
frame_rateis also used during timeline interpretation. - Solution: Keep
frame_rateat 24 for a straightforward native-rate workflow and connect the node’sfpsoutput to the video combiner. Check the expected duration usinglengthdivided byfpsbefore making external speed adjustments.
Timing or prompt controls appear to have no effect
- Explanation: This is a configuration symptom. The provided execution visibly relies on
timeline_datafor block structure and does not demonstrate use of several exposed controls, includingstart_second,end_second,local_prompts, andsegment_lengths. - Solution: Set scene timing and per-block instructions through the timeline editor. Use
global_promptfor shared direction andduration_framesfor the documented extraction fallback rather than assuming every exposed field overrides timeline settings.
Opening image is different from the first timeline image
- Explanation: This can be expected behavior rather than an error. A connected
first_frame_overridetakes priority over the first block’s timeline image, and only the first image of an override batch is used. - Solution: Disconnect
first_frame_overrideif you want the timeline image to seed the opening block. If you want the override, confirm that the intended image is first in its batch.
A later block does not begin with its placed timeline image
- Explanation: This can also be expected behavior. Later blocks automatically begin from the decoded final frame of the preceding block, while a placed image on that later block acts as a target transition frame according to the source comments.
- Solution: Design later images as transition destinations. If you need a completely independent opening image instead of continuity from the preceding block, render that section separately and use the image as its
first_frame_override.
Images are unexpectedly cropped, padded, or distorted
- Explanation: This symptom usually reflects the relationship between the source image’s proportions and the fixed canvas. The node applies the selected resize method and can apply a final crop if the result still does not match the canvas exactly.
- Solution: Choose a canvas close to your source image’s aspect ratio, select an appropriate resize method, and test important edge details. Avoid “stretch to fit” when preserving natural proportions is more important than filling every pixel.
