Zoey - MiniMax H3 参考转视频 (@)

ZoeyMiniMaxH3ReferenceToVideo is the heavy artillery node in this pack: a self-contained wrapper around ComfyUI's official MiniMax H3 reference-to-video node that bundles in its own model loaders, a Seedance-style @ reference syntax, a permanent cross-workflow asset library, and a full storyboard "director" panel for multi-shot video. If you've been juggling the official MiniMax H3 reference node plus half a dozen extra packs to get character consistency and shot planning, this is someone's attempt to put the whole job behind one widget.

A quick reality check on the model itself: MiniMax H3 is the 2026 open-weights omni-modal video model - text, image, video, and audio in one context, generating clips with native audio - and its Community License excludes several territories (US, EU, UK, South Korea), so check your region before leaning on it. That caveat belongs to the weights, not this node.

How it works

It's a replacement for the stock MiniMaxH3ReferenceToVideo, not an add-on: it loads the DiT, CLIP, VAE, and audio VAE itself (dropdowns for unet_name, clip_name, vae_name, audio_vae_name over ComfyUI's model folders), stacks optional LoRAs, builds conditioning and a latent, and hands you model, vae, audio_vae, positive, LATENT, plus 提示词(已转换) - the compiled prompt, so you can see exactly what it fed the sampler.

The bits that make it worth your time:

• @ reference tags. In reference mode you write @P1, @V1, @A1 in the prompt and they auto-expand to native <Picture 1> / <Video 1> / <Audio 1> - no hand-counting which reference slot is which. Reference images/videos/audios plug into the ref_image_N, ref_video_N (+ ref_video_audio_N), ref_audio_N inputs. auto_declaration prepends the formal "Use <Picture 1> as reference frame, and <Audio 1> exactly as it is" declaration line that H3 wants.
• Modes. mode lets you pick 参考 (reference), T2V, I2V, or 自动 - auto picks the backend from what you connected (one image → I2V with it as first frame, video/audio → reference mode, nothing → T2V). I2V even lets a second image act as a last frame.
• director_mode + director_shots. Flip director mode on and the single prompt becomes a multi-shot storyboard: per shot you get shot-size/camera-move presets, dialogue rows (compiled to (S1) says: <d>[language] text</d>), character slots, transitions, per-shot duration (with auto-allocation by dialogue length), reordering, and template starting points. dialogue_convert also turns quoted lines in a plain prompt into the <d>[lang]…</d> form H3 reads as spoken audio.
• The global asset library (library). Upload characters/props/audio once through the node's 素材库 widget and they're stored permanently in ComfyUI/input/zoey_library/ (with a library.json manifest, served over a /zoey/library HTTP route). Reference any saved entry in your prompt as @L1… and the node auto-loads the file and injects it into generation - no LoadImage node needed. Characters can carry an appearance note and a voice audio, and the node auto-writes the "this is {name}'s character reference (face and clothes locked)" annotation into the prompt.

Supporting controls: resolution and aspect presets (plus auto), duration (1–15s), ref_image_size (match/max), ref_purposes JSON for per-image usage annotations, sage_attention (per-model-clone SageAttention speedup if you've pip install sageattention), and a LoRA list.

Installing it

cd ComfyUI/custom_nodes
git clone https://github.com/liangzoey/comfyui-ZoeyTool.git
cd comfyui-ZoeyTool
pip install -r requirements.txt

Restart ComfyUI (or ComfyUI Manager → comfyui-ZoeyTool). Two prerequisites: your ComfyUI build must include the official MiniMax H3 support (comfy_extras.nodes_minimax_h3 - the node only registers when it can import that), and the H3 models themselves must be in the usual folders, which you obtain through ComfyUI's MiniMax H3 autodownload/manager or manually. This is a local-weights node; it doesn't call the Hailuo API.

Where people get burned

Three classics. Out-of-range tags error - write @P3 with only two images connected and you get a hard ValueError telling you exactly that; the fix is renumbering, and the rule is slots are counted per type in connection order, ignoring gaps. Audio without an audio VAE - reference mode with any audio reference demands audio_vae_name be set to the pixel-space audio VAE, or the node refuses to run. Director mode needs shots - enable it with an empty storyboard and it raises "add at least one shot." Beyond that, expect long compile times on the director's text (it can push token budgets) and remember the territory restriction on H3 weights before you build a pipeline you intend to keep. For a beginner, the sanest path is: get H3 running with the stock workflow first, then adopt this node for the @ tags and library, and only then graduate to director mode.