中文阅读

  🤗 HuggingFace   | 💻 官方网站（官网）试用我们的模型！  

👏 加入我们的微信和Discord

---

本仓库包含我们HunyuanImage-2.1的PyTorch模型定义、预训练权重以及推理/采样代码。您可以在官方网站（官网）上直接试用我们的模型,并在我们的项目页面上找到更多可视化效果。

🔥🔥🔥 最新动态

• 2025年9月18日：✨ 试用PromptEnhancer-32B模型，获得更高质量的提示词增强！​。
• 2025年9月18日：✨ HunyuanImage-2.1的ComfyUI工作流现已可用！
• 2025年9月16日：👑 我们在Arena的文生图开源模型排行榜上夺得第一名。排行榜
• 2025年9月12日：🚀 发布了FP8量化模型！现在仅需24GB显存即可生成2K图像！
• 2025年9月8日：🚀 发布了HunyuanImage-2.1的推理代码和模型权重。

简介

我们非常高兴地推出HunyuanImage-2.1，这是一款170亿参数的文生图模型，能够生成2K（2048 × 2048）分辨率的图像。

我们的架构分为两个阶段：

1. 基础文生图模型：第一阶段是一个文生图模型，使用了两个文本编码器：一个多模态大语言模型（MLLM），用于提升图像与文本的对齐效果；另一个是多语言、字符感知编码器，用于增强多种语言下的文本渲染能力。
2. 精修模型：第二阶段引入了一个精修模型，进一步提升图像质量和清晰度，同时减少伪影。

👑 我们在Arena的文生图开源模型排行榜上获得了第一名。

🎉 HunyuanImage-2.1 主要特性

• 高质量生成：高效生成超高清（2K）图像，构图极具电影感。
• 多语言支持：原生支持中文和英文提示词。
• 先进架构：基于多模态、单流与双流结合的DiT（扩散Transformer）骨干网络。
• 字形感知处理：利用ByT5的文本渲染能力，提升文本生成的准确性。
• 灵活的宽高比：支持多种图像宽高比（1:1、16:9、9:16、4:3、3:4、3:2、2:3）。
• 提示词增强：自动改写提示词，以提高描述准确性和视觉质量。

📜 系统要求

硬件和操作系统要求：

• 支持CUDA的NVIDIA GPU。

  目前最低要求： 生成2048×2048图像需24GB显存。

  注意： 上述显存要求是在启用模型CPU卸载和FP8量化的情况下测得的。如果您的显存充足，可以关闭卸载以提升推理速度。

• 支持的操作系统：Linux。

🛠️ 依赖与安装

1. 克隆仓库：

git clone https://github.com/Tencent-Hunyuan/HunyuanImage-2.1.git
cd HunyuanImage-2.1

2. 安装依赖：

pip install -r requirements.txt
pip install flash-attn==2.7.3 --no-build-isolation

🧱 下载预训练模型

预训练模型的下载详情请见此处。

🔑 使用方法

提示词增强

提示词增强在使我们的模型生成高质量图像方面起着关键作用。通过撰写更长、更详细的提示词，生成的图像将得到显著提升。我们鼓励您编写全面且富有描述性的提示词，以获得最佳的图像质量。

我们强烈推荐您试用PromptEnhancer-32B模型，以获得更高质量的提示词增强效果。

文生图

HunyuanImage-2.1仅支持2K图像生成（例如，1:1图像为2048×2048，16:9图像为2560×1536等）。生成1K分辨率的图像会导致伪影。

此外，我们强烈建议使用完整的生成流程以获得更好的质量（即启用提示词增强和精修）。

模型类型	模型名称	描述	num_inference_steps	guidance_scale	shift
基础文生图模型	hunyuanimage2.1	未蒸馏模型，用于获得最佳质量。	50	3.5	5
蒸馏文生图模型	hunyuanimage2.1-distilled	蒸馏模型，用于更快的推理	8	3.25	4
精修模型	hunyuanimage-refiner	精修模型	N/A	N/A	N/A

import os
os.environ['PYTORCH_CUDA_ALLOC_CONF'] = 'expandable_segments:True'
import torch
from hyimage.diffusion.pipelines.hunyuanimage_pipeline import HunyuanImagePipeline

# 支持的模型名称：hunyuanimage-v2.1，hunyuanimage-v2.1-distilled
model_name = "hunyuanimage-v2.1"
pipe = HunyuanImagePipeline.from_pretrained(model_name=model_name，use_fp8=True)
pipe = pipe.to("cuda")

# 输入提示
prompt = "一只可爱、卡通风格的拟人企鹅毛绒玩具，有着蓬松柔软的毛发，正站在一间画室里，戴着一条红色针织围巾和一顶印有‘腾讯’二字的红色贝雷帽，神情专注地拿着画笔，正在绘制一幅蒙娜丽莎的油画，画面以写实的摄影风格呈现。"


# 使用不同宽高比生成图像
aspect_ratios = {
    "16:9": (2560, 1536),
    "4:3": (2304, 1792),
    "1:1": (2048, 2048),
    "3:4": (1792, 2304),
    "9:16": (1536, 2560),
}

width, height = aspect_ratios["1:1"]

image = pipe(
    prompt=prompt,
    width=width,
    height=height,
    # 如果已经使用提示增强功能来优化提示，则禁用重新提示
    use_reprompt=False,  # 启用提示增强功能（可能会增加显存占用）
    use_refiner=True,   # 启用精修模型
    # 对于蒸馏模型，使用8步以加快推理速度。
    # 对于非蒸馏模型，使用50步以获得更好的质量。
    num_inference_steps=8 if "distilled" in model_name else 50, 
    guidance_scale=3.25 if "distilled" in model_name else 3.5,
    shift=4 if "distilled" in model_name else 5,
    seed=649151,
)

image.save("generated_image.png")

更多案例

我们的模型能够遵循复杂的指令，生成高质量、富有创意的图像。

我们建议使用更长、更详细的提示词。您也可以尝试我们提供的提示词。

序号	用户提示	图像
1	一座宏伟教堂的内部，穹顶下方的中央矗立着一尊小巧的维纳斯雕像，微微侧对镜头。雕像没有双手，布满裂纹，表面若干古老的水泥片剥落，露出内部真人质感的牛奶肌肤。雕像穿着薄薄的白色婚纱，在雕像的身后，一只浮空水泥断手轻轻提起长长的婚纱拖尾；在雕像的头顶上方，另一只浮空水泥断手正为她戴上一个由白色花朵组成的花环，雕像本身是没有双手的。教堂穹顶上布满彩色玻璃窗，一束阳光从上往下照射到雕像上，形成丁达尔效应，光斑点点洒在雕像的脸庞和胸前。充满神性的光辉，背景微微虚化，物体的边缘模糊柔和。拉斐尔前派的梦幻朦胧美学风格。
2	一张超写实的照片，展示了一个水晶球立体模型，它坐落在柔软的森林苔藓之上，周围洒满了散射的阳光。模型内部精细地还原了一间腾讯会议室、一座会说话的聊天气泡雕塑，以及几只欢快的企鹅——其中一只戴着毕业帽，其余的则在踢足球并挥舞着小旗帜。水晶球的底座上用醒目的白色立体大字写着“腾讯”。背景柔和地虚化，充满焦外光斑效果，更加突出了球体中那些可爱而生动的细节。
3	一位年迈意大利男士的特写肖像，他皮肤深深褶皱，眼神深邃而富有表现力，留着修剪整齐的白色小胡子。他的橄榄色肤色透露出岁月与阳光的痕迹，头戴一顶微微歪向一侧的平顶帽。他嘴角微扬，流露出温暖与智慧，手中端着一小杯浓缩咖啡。背景是柔和虚化的质朴石墙，上面爬满了常春藤，整体以写实的摄影风格呈现。
4	一只打开的复古旅行箱，置于中性且光线柔和的背景之上。箱子由深棕色的旧皮革制成，表面可见明显的磨损和折痕，内衬则是深色的柔软织物。箱内精心打造了一幅中国微型景观，其中包括蜿蜒于模型山峦之间的长城、故宫的宝塔屋顶，以及兵马俑的缩影，这些元素与生机勃勃的绿色稻田交织在一起。箱子侧面还标注着“China”字样。整个场景沐浴在温暖而空灵的光线下，镜头晕影营造出梦幻般的氛围，亮点柔和而明亮。写实风格，纹理极其细腻，光影极具电影感。

为提升生成图像的质量和细节，我们使用了一个提示重写模型。该模型会自动增强用户提供的文本提示，添加详细且描述性的信息。

序号	用户提示	增强后的提示	图像
1	塞伦盖蒂平原的野生动物海报。大眼睛的Q版探险家骑着友好的小狮子。“塞伦盖蒂：冒险的咆哮”采用奇幻风格字体。“梦想在此肆意奔腾”标语。温暖的黄色和柔和的棕色。	这是一张以塞伦盖蒂平原为主题的野生动物海报设计，画面中央是一位骑在小狮子背上的Q版探险家，背景则是起伏的山丘。构图顶部用大号、充满趣味的装饰性卷曲字母写着标题“塞伦盖蒂：冒险的咆哮”。主体场景中，一位大头小身的Q版探险家戴着绿色的探险帽，背着背包，双手抓住小狮子的鬃毛，面带惊喜地向前望去。小狮子则有着浅棕色的鬃毛和微笑的表情，正迈步向前，身体以温暖的橙色为主色调。背景部分描绘了塞伦盖蒂平原的连绵丘陵与稀树草原，整体色调为温暖的黄色和柔和的棕色。主图下方用较小而优雅的字体写着标语“梦想在此肆意奔腾”。整幅作品呈现出一种将可爱Q版插画风格与俏皮奇幻字体相结合的海报设计感。
2	纽约市活力四射的海报。动漫风格的女商人正在路边招手拦出租车，周围是摩天大楼和时代广场的广告牌。“纽约：璀璨抱负”采用都市涂鸦字体。“成就每一个梦想”标语。饱和的黄色、红色和鲜明的蓝色。	这是一张充满活力的纽约市海报，画面中央是一位正在招手拦出租车的动漫风格女商人。她有着大而富有表现力的眼睛，一头黑色短发，身穿带有动感线条的职业蓝色西装套装，站在繁忙的街道上，双臂伸展呼唤一辆迎面驶来的经典黄色出租车。背景中，高耸入云的摩天大楼拥有流畅的动漫风格建筑造型，上面布满了时代广场标志性的鲜艳发光广告牌和霓虹灯招牌。海报顶部用大型、风格化的都市涂鸦字体写着“纽约：璀璨抱负”，边缘仿佛喷漆效果一般。在这句主标题下方，用较小而简洁的字体写着标语“成就每一个梦想”。整个画面运用了饱和度极高的色彩，以明亮的黄色、红色和锐利的蓝色为主调。整体呈现出动漫插画与平面设计相融合的效果。
3	一幅艺术工作室人像，捕捉到一位高级时装模特极具冲击力的动态姿势。她的脸庞宛如一块前卫妆容的画布，以大胆的几何形状和原色点缀。她身着一件雕塑感十足的非常规服装，强调干净利落的线条与形态。现场由戏剧性的灯光照明，形成强烈的明暗对比，使她的面部特征在抽象模糊的彩色背景中格外突出。照片以写实风格呈现。	一幅艺术工作室人像，拍摄了一位高级时装模特极具冲击力的动态姿势，她身体扭转，一只手臂高高举起，展现出力量与动感。她的脸部成为前卫妆容的画布，以大胆的几何图形和原色进行创作：额头处绘有鲜艳的黄色三角形，眼窝周围则用电光蓝线条勾勒。她身着一件由硬挺哑光白色面料制成的雕塑感十足的非常规服装，不对称的衣片环绕躯干，凸显出干净利落的线条与形态。摄影师使用了戏剧性的灯光效果，侧方强光投下清晰的阴影，将她的面部轮廓与身体曲线从紫色和橙色交织的抽象模糊背景中凸显出来，营造出散景般的视觉效果。照片以写实风格呈现。
4	一位厨师的环境肖像，定格在他专注神情的繁忙厨房之中。他手中握着厨具，目光牢牢锁定在工作上，尽显热情与创造力。背景则是一片流动的模糊影像，不锈钢操作台等元素若隐若现，在温暖的环境光映衬下显得格外柔和。照片以写实风格呈现。	一张男性厨师在繁忙厨房中工作的环境肖像。作为画面主体，厨师自胸部以上被拍摄，他眉头紧锁，目光低垂，专注地看着手中的厨具。他身着白色厨师服和传统厨师帽，脸上和衣服上还沾着些许面粉。他的手中握着一把巨大的厨师刀和一把金属铲，似乎正准备在看不见的烹饪台上施展厨艺。背景则是一片动态模糊的影像，不锈钢操作台、锅具等厨房设备的轮廓若隐若现，暗示着这里一片忙碌的景象。头顶暖光灯散发出金色光芒，为厨师的制服和工具镀上一层光晕。照片采用写实风格，通过浅景深突出主体，同时传达出厨房内的活力与创意。

📈 对比

SSAE 评估

SSAE（结构化语义对齐评估）是一种基于先进多模态大语言模型（MLLM）的智能图像-文本对齐评估指标。我们提取了12个类别下的3500个关键点，然后利用多模态大语言模型，通过比较生成的图像与这些关键点，并根据图像的视觉内容进行自动评估和打分。平均图像准确率表示所有关键点上的逐张图像平均得分，而全局准确率则直接计算所有关键点的平均得分。

模型	开源	平均图像准确率	全局准确率	主要主体				次要主体			场景		其他
				名词	关键属性	其他属性	动作	名词	属性	动作	名词	属性	镜头	风格	构图
FLUX-dev	✅	0.7122	0.6995	0.7965	0.7824	0.5993	0.5777	0.7950	0.6826	0.6923	0.8453	0.8094	0.6452	0.7096	0.6190
Seedream-3.0	❌	0.8827	0.8792	0.9490	0.9311	0.8242	0.8177	0.9747	0.9103	0.8400	0.9489	0.8848	0.7582	0.8726	0.7619
Qwen-Image	✅	0.8854	0.8828	0.9502	0.9231	0.8351	0.8161	0.9938	0.9043	0.8846	0.9613	0.8978	0.7634	0.8548	0.8095
GPT-Image	❌	0.8952	0.8929	0.9448	0.9289	0.8655	0.8445	0.9494	0.9283	0.8800	0.9432	0.9017	0.7253	0.8582	0.7143
HunyuanImage 2.1	✅	0.8888	0.8832	0.9339	0.9341	0.8363	0.8342	0.9627	0.8870	0.9615	0.9448	0.9254	0.7527	0.8689	0.7619

从SSAE评估结果来看，我们的模型目前在语义对齐方面已达到开源模型中的最优水平，且与闭源商用模型（GPT-Image）的表现非常接近。

GSB 评估

我们采用了GSB评估方法，该方法常用于从整体图像感知的角度评估两个模型之间的相对性能。总共使用了1000个文本提示，在一次运行中为所有对比模型生成了相同数量的图像样本。为了公平比较，我们对每个提示仅进行一次推理，避免挑选最佳结果。与基线方法比较时，我们保持所有选定模型的默认设置不变。评估由超过100名专业评估员完成。 结果显示，HunyuanImage 2.1相对于Seedream3.0（闭源）的相对胜率为-1.36%，而优于Qwen-Image（开源）2.89%。GSB评估结果表明，作为一款开源模型，HunyuanImage 2.1的图像生成质量已达到与闭源商用模型（Seedream3.0）相当的水平，同时在与同类开源模型（Qwen-Image）的比较中展现出一定优势。这充分验证了HunyuanImage 2.1在文生图任务中的技术先进性和实际价值。

联系方式

欢迎加入我们的Discord服务器或微信交流群——不仅可交流想法、探讨合作，还可提出任何疑问。您也可以在GitHub上提交问题或拉取请求。您的反馈对我们至关重要，将推动HunyuanImage不断向前发展。感谢您成为我们社区的一员！

🔗 BibTeX

如果您发现本项目对您的研究和应用有所帮助，请引用如下：

@misc{HunyuanImage-2.1,
  title={HunyuanImage 2.1: 高分辨率（2K）文生图的高效扩散模型},
  author={腾讯混元团队},
  year={2025},
  howpublished={\url{https://github.com/Tencent-Hunyuan/HunyuanImage-2.1}},
}

致谢

我们衷心感谢以下开源项目和社区为开放研究与探索所作出的贡献：Qwen、FLUX、diffusers以及HuggingFace。

GitHub 星标历史

HunyuanImage-2.1 快速上手指南

HunyuanImage-2.1 是腾讯混元团队开源的高效扩散模型，支持生成高达 2K (2048×2048) 分辨率的高质量图像。该模型原生支持中英文提示词，具备优秀的图文对齐能力和细节渲染能力。

环境准备

系统要求

• 操作系统: Linux
• GPU: 支持 CUDA 的 NVIDIA 显卡
• 显存要求:
  • 最低 24 GB 显存（需开启 FP8 量化和 CPU Offloading）可生成 2K 图像。
  • 若显存充足，可关闭 Offloading 以提升推理速度。

前置依赖

• Python 3.8+
• PyTorch (支持 CUDA)
• Git

安装步骤

1. 克隆仓库

git clone https://github.com/Tencent-Hunyuan/HunyuanImage-2.1.git
cd HunyuanImage-2.1

2. 安装依赖

建议先配置国内 pip 镜像源以加速下载：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install flash-attn==2.7.3 --no-build-isolation -i https://pypi.tuna.tsinghua.edu.cn/simple

注意: flash-attn 需要编译环境，请确保已安装对应的 CUDA Toolkit 和 C++ 编译器。

3. 下载预训练模型

模型权重文件较大，请参考官方文档 ckpts/checkpoints-download.md 下载权重文件至本地指定目录。 主要包含以下模型：

• hunyuanimage-v2.1: 基础模型（50 步，画质最佳）
• hunyuanimage-v2.1-distilled: 蒸馏模型（8 步，推理更快）
• hunyuanimage-refiner: 精修模型（用于提升细节）

基本使用

以下是最小化的 Python 推理示例。代码默认启用 FP8 量化 以节省显存，并自动加载精修模型以获得最佳效果。

import os
# 设置 PyTorch CUDA 内存分配策略，防止显存碎片化
os.environ['PYTORCH_CUDA_ALLOC_CONF'] = 'expandable_segments:True'

import torch
from hyimage.diffusion.pipelines.hunyuanimage_pipeline import HunyuanImagePipeline

# 选择模型名称："hunyuanimage-v2.1" (高质量) 或 "hunyuanimage-v2.1-distilled" (快速)
model_name = "hunyuanimage-v2.1"

# 初始化管道，use_fp8=True 可在 24GB 显存下运行 2K 生成
pipe = HunyuanImagePipeline.from_pretrained(model_name=model_name, use_fp8=True)
pipe = pipe.to("cuda")

# 输入提示词 (支持中文或英文，建议描述详细)
prompt = "一只可爱的卡通风格拟人企鹅毛绒玩具，毛茸茸的，站在绘画工作室里，戴着红色针织围巾和一顶写有'Tencent'字样的红色贝雷帽，手持画笔，表情专注地绘制蒙娜丽莎的油画，照片级写实风格。"

# 设置分辨率 (2K 规格)
# 支持比例：1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3
aspect_ratios = {
    "1:1": (2048, 2048),
    "16:9": (2560, 1536),
    "9:16": (1536, 2560),
}
width, height = aspect_ratios["1:1"]

# 执行生成
image = pipe(
    prompt=prompt,
    width=width,
    height=height,
    use_reprompt=False,  # 若已手动优化提示词可设为 False，否则设为 True 启用自动改写
    use_refiner=True,    # 启用精修模型以提升画质
    # 根据模型类型调整步数和参数
    num_inference_steps=8 if "distilled" in model_name else 50, 
    guidance_scale=3.25 if "distilled" in model_name else 3.5,
    shift=4 if "distilled" in model_name else 5,
    seed=649151,         # 固定随机种子以保证结果可复现
)

# 保存图像
image.save("generated_image.png")
print("图像生成完毕：generated_image.png")

使用建议

1. 提示词优化: 模型对长且详细的提示词响应更好。如需更佳效果，可结合 PromptEnhancer-32B 模型先对提示词进行扩充。
2. 分辨率限制: 请严格使用 2K 级别 的分辨率（如 2048x2048）。尝试生成 1K 分辨率图像可能会导致画面伪影。
3. 显存优化: 如遇显存不足（OOM），请确保 use_fp8=True 已开启，并检查系统是否支持 CPU Offloading。