| --- |
| 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 |
| --- |
| |
| <div align="center"> |
| <img width="100%" src="cover.jpg" alt="MiniMax H3 image - Text Encoder · INT4 ConvRot"> |
| </div> |
|
|
| <h1 align="center">MiniMax-H3-Image — Text Encoder (INT4 ConvRot)</h1> |
|
|
| <p align="center"> |
| <strong>Ultra-compact 4-bit ConvRot text encoder & prompt enhancer weights for ComfyUI</strong> |
| </p> |
|
|
| <p align="center"> |
| <a href="https://huggingface.co/MiniMaxAI/MiniMax-H3-Image"><img src="https://img.shields.io/badge/Base%20Model-MiniMax--H3--Image-FF6C37" alt="Base Model"></a> |
| <a href="https://github.com/Comfy-Org/ComfyUI"><img src="https://img.shields.io/badge/ComfyUI-Single%20File-007ACC" alt="ComfyUI"></a> |
| <img src="https://img.shields.io/badge/Quantization-INT4%20ConvRot%20(W4A4)-6F42C1" alt="Quantization"> |
| <img src="https://img.shields.io/badge/VRAM%20Peak-13.25%20GiB-2EA44F" alt="VRAM Peak"> |
| <a href="https://huggingface.co/MiniMaxAI/MiniMax-H3-Image/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MiniMax%20H3%20Community-4CAF50" alt="License"></a> |
| </p> |
|
|
| --- |
|
|
| ## Overview |
|
|
| Ultra-compact **INT4 ConvRot** single-file `.safetensors` weights for **[MiniMax-H3-Image](https://huggingface.co/MiniMaxAI/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`)<br>**`-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/`: |
|
|
| ```text |
| 📂 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](https://github.com/Comfy-Org/workflow_templates/blob/main/templates/image_minimax_h3_image_t2i.json) and [Image Edit](https://github.com/Comfy-Org/workflow_templates/blob/main/templates/image_minimax_h3_image_edit.json) 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](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image/blob/main/LICENSE)**. 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](https://platform.minimax.io/license). |
| - **Upstream Repositories:** [MiniMaxAI/MiniMax-H3-Image](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image) · [MiniMaxAI/MiniMax-H3](https://huggingface.co/MiniMaxAI/MiniMax-H3) · [Comfy-Org/MiniMax-H3-Image](https://huggingface.co/Comfy-Org/MiniMax-H3-Image) |
|
|
