MiniMax H3 Image Studio

ComfyUI nodes and workflows for MiniMax H3 text-to-image, image-to-image, and REF2VA reference editing.

MiniMax H3 is an audio-video model. These nodes generate a short frame packet, decode it, and select one still image.

Requirements

• ComfyUI 0.30.0 or newer
• MiniMax H3 diffusion model
• MiniMax H3 Qwen text encoder
• MiniMax H3 video VAE
• Matching Turbo adapter only for a Turbo workflow

Use the official ComfyUI MiniMax H3 guide for model downloads and installation.

Recommended official model	Folder
minimax_h3_fl2va_pruned_int8_convrot.safetensors or minimax_h3_ref2va_pruned_int8_convrot.safetensors	ComfyUI/models/diffusion_models/
qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors	ComfyUI/models/text_encoders/
minimax_h3_video_vae_fp16.safetensors	ComfyUI/models/vae/
Exact Turbo adapter named in the sampling table	ComfyUI/models/loras/

The audio VAE is not required for image output.

Installation

ComfyUI Manager

Search for MiniMax H3 Image Studio, or run:

comfy node install minimax-h3-image-studio

Git

cd ComfyUI/custom_nodes
git clone https://github.com/astropuzzo/ComfyUI-MiniMax-H3-Image-Studio.git

Restart ComfyUI after installing or updating.

To update a Git installation:

git -C ComfyUI/custom_nodes/ComfyUI-MiniMax-H3-Image-Studio pull --ff-only

Workflows

Open a file from examples/ui/, or drag a file from examples/png/ onto the canvas.

Workflow	UI JSON	PNG	API JSON
Text to Image	Open	Open	API
Text to Image, single frame (experimental)	Open	Open	API
Image to Image	Open	Open	API
Image to Image, single frame (experimental)	Open	Open	API
Reference Edit	Open	Open	API
Reference Edit, single image (experimental)	Open	Open	API
Image to Image, Turbo v1.0	Open	Open	API
Generative Detail Refiner	Open	Open	API

Files in examples/api/ are prompt JSON for API clients. They do not contain a canvas layout.

For image-to-image and reference-edit workflows, select an image in every Load Image node before running the workflow.

Nodes

Node	Function
Text to Image	Prepares FL2VA text conditioning for multi-frame or one-frame output.
Image to Image	Uses an FL2VA frame-0 anchor for multi-frame editing and REF2VA source conditioning for editable one-frame output.
Reference Edit	Prepares REF2VA editing with up to nine ordered references.
Resolution Preset	Calculates common H3 canvas sizes.
Sampling Preset	Configures documented recipes or a complete custom sampler setup.
Exact Frame Decode	Decodes the requested frame profile.
Single Image Output	Selects one frame or returns the decoded batch.
Advanced Resolution	Calculates custom canvas sizes.
Advanced Sampling	Exposes sampler, scheduler, denoise, and sigma shifts.
Advanced Combined Prepare	Combines all preparation modes in one node.
Detail Tone Lock	Blends refined detail while restoring the H3 image's broad lighting and color.

Optional detail refinement

H3_DETAIL_REFINER is a separate generative image-edit pass. Load a finished H3 image, or connect any Single Image Output directly to Scale Image to Total Pixels. It is optional and does not change H3 generation.

The workflow uses ComfyUI's native Qwen Image Edit 2511 path with the four-step Lightning adapter. Qwen 2511 was selected over FLUX.2 Klein 4B because this pass prioritizes edit fidelity, identity, and scene preservation rather than the smallest model.

Component	File	Folder
Diffusion model	qwen_image_edit_2511_int8_convrot.safetensors	ComfyUI/models/diffusion_models/
Text encoder	qwen_2.5_vl_7b_fp8_scaled.safetensors	ComfyUI/models/text_encoders/
VAE	qwen_image_vae.safetensors	ComfyUI/models/vae/
Four-step adapter	Qwen-Image-Edit-2511-Lightning-4steps-V1.0-bf16.safetensors	ComfyUI/models/loras/

Downloads and setup are documented in the official ComfyUI Qwen Image Edit 2511 guide. The workflow uses the official Comfy INT8 ConvRot checkpoint and the published four-step Lightning adapter.

The workflow uses Euler/simple, four steps, CFG 1, AuraFlow shift 3.1, CFG normalization 1, and a two-megapixel working copy. That working copy controls model cost only. The original H3 image goes directly to Detail Tone Lock, so the saved result always has the original width and height.

The prompt is intentionally generic and preservation-first. Do not append the complete H3 generation prompt by default: scene descriptions can encourage reconstruction. Describe a specific defect only when it needs repair.

Detail Tone Lock uses frequency separation rather than masks: Qwen supplies newly generated fine detail while H3 remains authoritative for dimensions, broad lighting, and color. The shipped defaults are tone_lock=0.85, refinement_strength=0.55, and detail_radius=32. This is not an upscaler or restoration-only chain; Qwen performs the second image-generation pass.

Frame profiles

H3 processes multiple frames even when the output is one image.

Profile	Frames	Notes
Single image	1	T2I, I2I, or REF2VA. Use the experimental image VAE and hybrid checkpoint.
Recommended	5	Default.
Extended	9	More temporal context.
High	13	Higher memory and runtime.
Maximum	20	Highest memory and runtime.

Exact Frame Decode returns the selected profile and a recommended_index. Connect that index to Single Image Output.

Single Image Output uses the recommended index by default. Its scoring modes are optional diagnostics; they cannot correct weak conditioning or an unclear edit prompt.

Sampling

Profile	Sampler	Scheduler	Steps	Video/audio shift
Base quality	res_multistep	simple	20	12/3
Base speed	res_multistep	simple	12	12/3
FL2VA Turbo v1.0	euler	simple	8	12/3
FL2VA Turbo v1.0 768p	euler	simple	4	6/3
REF2VA Turbo v0.1	euler	simple	4	12/3
Hybrid single image	er_sde	sgm_uniform	8	12/3

Turbo profiles require the exact matching adapter below. Sampling Preset configures sampling but does not load a LoRA.

Choose custom | use controls below in Sampling Preset to select any installed sampler and scheduler and set steps, denoise, H3 video/audio shifts, and beta-scheduler parameters directly. The custom controls are ignored while a documented preset is selected, so loading an existing workflow preserves its exact recipe.

Profile	Required adapter
FL2VA Turbo v1.0, 8 steps	minimax_h3_fl2v_turbo_8step_v1.0_comfyui_bf16.safetensors
FL2VA Turbo v1.0 768p, 4 steps	minimax_h3_fl2v_turbo_4step_v1.0_768p_comfyui_bf16.safetensors
REF2VA Turbo v0.1, 4 steps	minimax_h3_ref2v_turbo_4step_v0.1_comfyui_bf16.safetensors

Do not mix FL2VA and REF2VA adapters or reuse one adapter's shifts with another. The older LightX v0.1 profile names remain available only to load existing workflows.

The hybrid single-image profile reproduces the linked community workflow. It is experimental and expects the model stack listed below; it is not an official MiniMax recipe.

Reference editing

REF2VA rebuilds an image from ordered references. Refer to each input by number:

Keep the identity, face, hair, clothing, camera, and environment from <Picture 1>.
Use the body pose and limb positions from <Picture 2>. The final pose must visibly match <Picture 2>.

source_fidelity changes preservation wording for traits that the instruction does not mention. Explicit assignments such as "pose from <Picture 2>" take priority. It is not denoise strength. For large pose, framing, or composition transfers, start around 0.50-0.60; higher values favor an unchanged <Picture 1>.

Each reference socket represents exactly one picture. If an upstream node sends an IMAGE batch, only its first image is used so later sockets keep stable <Picture N> numbers. State the role of every connected picture explicitly in the target instructions.

Experimental one-frame workflows

H3_T2I_SINGLE, H3_I2I_SINGLE, and H3_REFERENCE_SINGLE generate a true T=1 H3 latent directly. They do not patch ComfyUI or route around Image Studio's conditioning output. Their model stack follows the community workflow:

Component	File
Hybrid diffusion model	minimax_h3_hybrid_fl2va_ref2va_b25-49-int8.safetensors
Image VAE	minimax_h3_t1_image_vae_step1597.safetensors
Turbo adapter	minimax_h3_fl2v_turbo_8step_v1.0_comfyui_bf16.safetensors, strength 0.75
Detail adapter	MaxiMin-HHH-R2V-ThisIsFine_LoRA_V0_1.safetensors, strength 0.5

The image VAE is intended only for one-frame output. Keep minimax_h3_video_vae_fp16.safetensors for multi-frame workflows. The hybrid checkpoint, image VAE, and detail adapter are community experiments and inherit their source-model licenses.

The detail adapter is intentionally set to 0.5. In direct pose-transfer testing, 1.0 over-preserved Picture 1 and suppressed the requested pose, while 0.5 retained its identity and environment and allowed Picture 2's pose to transfer.

One-frame T2I uses the hybrid checkpoint's FL2VA base without an image reference. One-frame I2I cannot use FL2VA's exact frame-0 keyframe because that keyframe would occupy the only output frame; Image Studio automatically switches that case to Picture 1 reference conditioning. Multi-frame I2I continues to use the original FL2VA keyframe path.

Downloads: hybrid checkpoint, single-image VAE, ThisIsFine adapter, and Turbo adapter.

The approach was prompted by the single-image community workflow. ComfyUI main subsequently added conversion from a regular empty image latent in commit 0696f61. Image Studio builds the correct nested H3 video/audio latent itself, so its one-frame profile also works on ComfyUI 0.33.1 without that core commit.

Resolution and memory

Resolution is rounded to a 32-pixel grid. 1 MP follows ComfyUI's 1024² convention.

The native H3 canvas is about 1344×768, or one megapixel. Start with native detail | 0.98 MP. A 2 MP canvas can help small or distant details in some images, but increases memory and runtime and is not a general quality upgrade.

Performance

• Prefer the official pruned INT8 ConvRot diffusion model and NVFP4 text encoder listed above. The Comfy model card recommends the INT8 ConvRot model on current CUDA/PyTorch builds and FP8 only as a fallback.
• Use the base 20-step profile as the quality reference. The official Turbo v1.0 eight-step profile is the practical speed/quality default; the 768p four-step profile favors speed.
• SageAttention is optional. ComfyUI's H3 guide reports roughly double sampling speed with minimal quality loss. Enable it globally with ComfyUI's --use-sage-attention option or a compatible attention node, not both.
• Match FL2VA source images to the generation canvas for lower preprocessing cost. In REF2VA, match is faster; the 2048-short-edge option can strengthen identity at higher cost.
• Change one optimization at a time and compare with the same seed. Stacking unrelated caches, attention patches, and distilled adapters can reduce detail or introduce incompatibilities.

Experimental W4A8 diffusion and INT8 ConvRot VAE variants require ComfyUI 0.31 or newer. They are not workflow defaults because hardware support and output behavior vary.

Troubleshooting

H3WorkflowNote is reported as missing

This node was added in v15. Update MiniMax H3 Image Studio, restart ComfyUI, and refresh the browser. Current bundled workflows no longer depend on documentation-note nodes.

A sampling profile or selector strategy is not in the list

Errors mentioning Turbo v1.0 | 8 steps, base quality | RES 20 steps, or decode_recommended mean that a current workflow reached an older backend. Updating files without restarting ComfyUI does not replace the node definitions already loaded in memory.

1. Update MiniMax H3 Image Studio.
2. Stop every running ComfyUI process.
3. Start ComfyUI again.
4. Reload the browser page.
5. Reopen the workflow from examples/ui/ or examples/png/.

Do not repair this by changing only the rejected values. The current decoder also provides the recommended_index output used by the workflow.

Load Image - image is missing

Select an input file in each Load Image node. This is required for image-to-image and reference editing.

The canvas is empty

Use a file from examples/ui/ or examples/png/. Files in examples/api/ are not canvas workflows.

ComfyUI reports deprecated frontend imports

This extension imports only ComfyUI's supported scripts/app.js frontend module. Update the other custom nodes named in the warning or disable them one at a time to identify the source.

Reporting a generation error

Open a GitHub issue and include:

• complete console traceback
• ComfyUI and Image Studio versions
• operating system, GPU, VRAM, and system RAM
• model and LoRA filenames
• workflow JSON or metadata PNG
• resolution, frame profile, sampler, scheduler, and steps

Do not post private prompts, tokens, or personal images.

Development

python scripts/validate_release.py
python -m unittest discover -s tests -v

See CONTRIBUTING.md and CHANGELOG.md.

License

The Unlicense. Models, ComfyUI, and third-party nodes keep their own licenses.