Diffusers documentation
MiniMax-H3-Image
MiniMax-H3-Image
MiniMax-H3-Image 是 MiniMax 基于 MiniMax-H3 开发的图像模型，用于文本生成图像和参考图像编辑。您可以在 MiniMaxAI/MiniMax-H3-Image 找到该检查点。
与 MiniMax-H3 类似，它仅以 Modular Diffusers 块的形式集成：MiniMaxH3ImageBlocks 及其 MiniMaxH3ImageModularPipeline 构成了完整的集成。
import torch
from diffusers import ComponentsManager, ModularPipeline
manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda")
pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3-Image", components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)在 bfloat16 精度下，transformer 和文本编码器各占用约 62 GB，无法同时放入 80 GB 的 GPU，因此示例使用了自动卸载：当某个 block 需要时，ComponentsManager 会将对应的组件移动到加速器上。此时，一张 4736x3552 的图像峰值内存占用约为 65 GB。
文本到图像：
prompt = (
"An overhead photograph of a rustic farm-to-table spread on a weathered wooden table: a round loaf of sourdough "
"on burlap, wedges of cheese on a dark board, a copper bowl of vegetables, vine tomatoes, olives and walnuts."
)
image = pipe(
prompt=prompt, height=3552, width=4736, generator=torch.Generator().manual_seed(42), output="images"
)[0]编辑参考图像：
from diffusers.utils import load_image
reference = load_image("https://huggingface.co/MiniMaxAI/MiniMax-H3-Image/resolve/main/examples/reference1.png")
image = pipe(
prompt="Keep everything in <Picture 1> as it is, but remove the headphones and have the two hosts fist bump.",
image=reference,
height=4096,
width=4096,
generator=torch.Generator().manual_seed(1234),
output="images",
)[0]组件
| 组件 | 类 |
|---|---|
transformer | MiniMaxH3ImageTransformer2DModel |
text_encoder | Qwen3VLForConditionalGeneration |
vae | AutoencoderKLMiniMaxH3Image |
tokenizer, processor | 文本编码器的分词器和一个 Qwen3VLProcessor |
scheduler | MiniMaxH3Scheduler |
文本编码器与 MiniMax-H3 所使用的相同。检查点保留了自己的副本，以确保仓库的自包含性；Hub 会跨仓库对相同文件进行去重，因此该副本不会占用额外的存储空间。
工作流程
工作流在 image 输入上选择：
text2image根据prompt生成图像。image_conditioned根据prompt以及作为image传入的一张或多张参考图像进行生成。提示词按顺序将它们称为<Picture 1>、<Picture 2>，依此类推。参考图像保留其自身尺寸：仅当某张图像的短边不在 1024 到 2048 像素范围内时，才会对其进行缩放，且绝不会缩放到生成图像的尺寸。
提示词将按原样使用，不应用聊天模板，且长而完整的描述效果最佳。编辑提示词通常会先指明需要保留的内容，再说明需要修改的部分，最后完整描述目标图像。
提示词增强
MiniMax-H3-Image-PE 是 MiniMax 的提示词扩展模型：它将简短的请求重写为图像模型表现最佳的详细描述，并推荐一个宽高比。diffusers/minimax-h3-image-pe-blocks 自定义块将其作为独立的流水线运行。它们需要 xgrammar，以及大约 18 GB 的 GPU 内存。
import torch
from diffusers import ModularPipeline
enhancer = ModularPipeline.from_pretrained("diffusers/minimax-h3-image-pe-blocks", trust_remote_code=True)
enhancer.load_components(dtype=torch.bfloat16, device_map="cuda")
state = enhancer(prompt="a cozy cabin in the snow")
prompt, aspect_ratio = state.get("prompt"), state.get("aspect_ratio")将参考图像作为 image 传入，以扩展编辑指令。然后，将 prompt 传入图像流水线，并使用与 aspect_ratio 匹配的 height 和 width。
图像大小
height 和 width 指定返回图像的尺寸，默认值为 2048。该模型以 400 万像素或更高的分辨率生成图像：如果请求的尺寸较小，系统会在具有相同宽高比的更大画布上生成图像，然后再缩放回请求的尺寸，因此 1024x1024 的请求与 2048x2028 的请求成本相同。min_generation_area 用于设置该像素阈值；传入 1024 可确保始终按请求的尺寸生成。无论哪种情况，画布的边长都会四舍五入到 32 的倍数。
MiniMax 建议 1:1 使用 4096x4096，4:3 使用 4736x3552，3:2 使用 5024x3360，16:9 使用 5472x3072，21:9 使用 6272x2688，或者对于竖版格式，使用相同尺寸但交换高度和宽度。
采样
- 检查点在
sample_sigmas上分 6 步进行采样，且 Transformer 每步有一个输出头，因此没有num_inference_steps。 - 该模型经过引导蒸馏，因此没有 guider、
negative_prompt或guidance_scale。
MiniMaxH3ImageModularPipeline
类 diffusers.MiniMaxH3ImageModularPipeline
< source >( blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = Nonepretrained_model_name_or_path: str | os.PathLike | None = Nonecomponents_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = Nonecollection: str | None = Noneworkflow: str | None = Nonemodular_config_dict: dict[str, typing.Any] | None = Noneconfig_dict: dict[str, typing.Any] | None = None**kwargs )
用于 MiniMax-H3-Image 的 ModularPipeline：文本生成图像（text2image）和参考图像编辑（image_conditioned）。
MiniMax-H3-Image 在一条打包的序列上运行 MiniMax-H3 变换器，该序列包含文本行、参考图像的行以及生成图像的行（即单个潜在帧），且不处理音频。该检查点经过两次蒸馏：引导已融入权重中，因此没有引导器，也没有 negative_prompt 和 guidance_scale；它在固定的六步网格上进行采样，每一步对应变换器的一个输出头，因此也没有 num_inference_steps。
MiniMaxH3ImageBlocks
MiniMax-H3-Image 的模块化流水线模块：text2image，以及在传入 image 时用于参考图像编辑的（image_conditioned）。
支持的工作流：
text2image：需要promptimage_conditioned：需要prompt、image
组件：
image_processor (VaeImageProcessor) text_encoder (Qwen3VLForConditionalGeneration) tokenizer
(Qwen2Tokenizer) processor (Qwen3VLProcessor) vae (AutoencoderKLMiniMaxH3Image) scheduler
(MiniMaxH3Scheduler) transformer (MiniMaxH3ImageTransformer2DModel)
配置： reference_min_short_edge（默认值：1024）reference_max_short_edge（默认值：2048）vision_min_short_edge （默认值：1024）vision_max_short_edge（默认值：1024）sample_sigmas（默认值：[1.0, 0.9675236940383911, 0.8875485062599182, 0.75, 0.5327739119529724, 0.23200887441635132, 0.0]）：检查点中逐步输出头进行蒸馏时所使用的采样网格。
输入：
image (Image | list, 可选)：
编辑的参考图像，或它们的列表。提示词按顺序将它们称为 <Picture 1>、<Picture 2>、……
prompt (str)：
用于引导生成的提示词，为单个字符串。
vision_images (list, 可选)：
为文本编码器调整大小的参考图像。
reference_images (list, 可选)：
为 VAE 调整大小的参考图像。
generator (Generator, 可选)：
请求的生成器。将从中为每个参考图像抽取一个后验样本。
height (int)：
返回图像的高度（以像素为单位）。
width (int)：
返回图像的宽度（以像素为单位）。
min_generation_area (int, 可选，默认为 4194304)：
生成图像的最小面积（以像素为单位）。较小的 height x width 会在放大至该面积的画布上生成，并在解码后重新调整回 height x width。传入 1024 可始终按请求的尺寸生成。
reference_latents (list, 可选)：
参考图像的条件潜变量。它们的形状决定了每个参考图像的几何结构来源。
latents (Tensor)：
形状为 (1, latent_channels, latent_height, latent_width) 的预生成噪声，用于替代抽取操作。
reference_noise (list, 可选)：
参考图像的预生成噪声，每个张量的形状与 reference_latents 中对应条目相同，用于替代抽取操作。
*denoiser_input_fields (None,可选)：
Transformer 按名称读取的打包序列的结构描述：token_tags、position_ids 以及两个行索引张量。
output_type (str,可选*，默认为 pil)：
输出格式：‘pil’、‘np’、‘pt’。
输出：
images (list)：
生成的图像。