README.md

metadata

license: other
license_name: minimax-h3-image-community-license-agreement
license_link: https://huggingface.co/MiniMaxAI/MiniMax-H3-Image/blob/main/LICENSE
pipeline_tag: text-to-image
language:
  - en
base_model:
  - MiniMaxAI/MiniMax-H3-Image
  - MiniMaxAI/MiniMax-H3
  - Comfy-Org/MiniMax-H3-Image
base_model_relation: quantized
tags:
  - comfyui
  - minimax-h3
  - minimax-h3-image
  - text-encoder
  - qwen3-vl
  - qwen3.5
  - quantized
  - int4
  - convrot
  - 4-bit
  - comfy-kitchen
  - text-to-image
  - image-editing

MiniMax-H3-Image — Text Encoder (INT4 ConvRot)

Ultra-compact 4-bit ConvRot text encoder & prompt enhancer weights for ComfyUI

---

Overview

Ultra-compact INT4 ConvRot single-file .safetensors weights for MiniMax-H3-Image in ComfyUI. Built to minimize download size and GPU memory footprint while keeping native comfy_kitchen compatibility — shrinking the 32B text encoder to 13.30 GB (-51.0% vs int8_convrot, -15.2% vs nvfp4_awq, and -80% vs the 66.7 GB BF16 original).

---

Files & Comparison

File	Role	Precision / Format	Size	vs Comfy-Org Baseline
qwen3vl_32b_minimax_h3_int4_convrot.safetensors	Main Text Encoder (Qwen3-VL-32B, 50 layers)	convrot_w4a4 + nvfp4 / int8 / bf16	13.30 GB (12.39 GiB)	-51.0% vs int8_convrot (27.14 GB) -15.2% vs nvfp4_awq (15.69 GB)
qwen3.5_9b_int4_convrot.safetensors	Prompt Enhancer (Qwen3.5-9B, optional)	convrot_w4a4 + int8 / bf16	5.42 GB (5.05 GiB)	-26.2% vs qwen3.5_9b_w4a8_gptq (7.34 GB)

---

ComfyUI Usage

1. Installation

Download the desired .safetensors file(s) and place them inside ComfyUI/models/text_encoders/:

📂 ComfyUI/
└── 📂 models/
    └── 📂 text_encoders/
        ├── qwen3vl_32b_minimax_h3_int4_convrot.safetensors   # Main Text Encoder (required)
        └── qwen3.5_9b_int4_convrot.safetensors             # Prompt Enhancer (optional)

2. Workflow Setup

1. Text Encoder: In CLIPLoader, select qwen3vl_32b_minimax_h3_int4_convrot.safetensors with type = minimax and connect it to MiniMaxH3ImageConditioning.
2. *Prompt Enhancer (optional):* In CLIPLoader, select qwen3.5_9b_int4_convrot.safetensors with type = minimax and connect it to Generate Text (TextGenerateV2).
3. Templates: Works as a direct drop-in replacement inside ComfyUI's official MiniMax-H3-Image Text-to-Image and Image Edit workflows.

Requirements: Up-to-date ComfyUI with comfy_kitchen kernels supporting convrot_w4a4 and nvfp4 on CUDA GPUs.

---

Quantization Details

qwen3vl_32b_minimax_h3_int4_convrot.safetensors (727 tensors)

Formatted to MiniMax-H3-Image's exact 50-layer extraction spec (minimax_h3_te: {"num_hidden_layers": 50, "output": "unnormalized_hidden_after_layer_50"}):

• LM & Merger Linears (358 layers): convrot_w4a4 (convrot_groupsize=256, quant_group_size=64).
• Vision Projections (81 layers): convrot_w4a4 (convrot_groupsize=64).
• Vision MLP Down (fc2, 27 layers): nvfp4 fallback (K = 4304 is not divisible by 64 for convrot_w4a4).
• Embeddings & Sensitive Layers: embed_tokens in ConvRot int8_tensorwise (gs=256); RMSNorms, vision biases, patch_embed, and pos_embed preserved in BF16.

Why viewers show I8 on 4-bit layers: Safetensors has no native int4 tensor dtype, so two 4-bit weights are packed per byte in I8 (int8) containers. ComfyUI reads actual 4-bit precision and scales from each layer's .comfy_quant and .weight_scale tensors.

qwen3.5_9b_int4_convrot.safetensors (1,511 tensors)

Quantized 32-layer Qwen3.5-9B multimodal prompt enhancer (5.42 GB) using convrot_w4a4 across language-model, lm_head, and compatible vision projections (gs=256 / gs=64), ConvRot int8_tensorwise on embed_tokens and ViT mlp.linear_fc2, and BF16 norms/biases.

---

License & Credits

• License: Governed by the MiniMax H3 Image Community License Agreement. Commercial use exceeding 1 Million USD in annualized revenue or providing hosted services to third parties requires separate written authorization via platform.minimax.io/license.
• Upstream Repositories: MiniMaxAI/MiniMax-H3-Image · MiniMaxAI/MiniMax-H3 · Comfy-Org/MiniMax-H3-Image