tencent/HunyuanImage-3.0-Instruct-Distil

[中文文档](./README_zh_CN.md)

👏 Join our WeChat and Discord | 💻 Official website(官网) Try our model!&nbsp&nbsp

🔥🔥🔥 News

• January 26, 2026: 🚀 [HunyuanImage-3.0-Instruct-Distil](https://huggingface.co/tencent/HunyuanImage-3.0-Instruct-Distil) - Distilled checkpoint for efficient deployment (8 steps sampling recommended).
• January 26, 2026: 🎉 [HunyuanImage-3.0-Instruct](https://huggingface.co/tencent/HunyuanImage-3.0-Instruct) - Release of Instruct (with reasoning) for intelligent prompt enhancement and Image-to-Image generation for creative editing.
• October 30, 2025: 🚀 [HunyuanImage-3.0 vLLM Acceleration](./vllm_infer/README.md) - Significantly faster inference with vLLM support.
• September 28, 2025: 📖 [HunyuanImage-3.0 Technical Report](https://arxiv.org/pdf/2509.23951) - Comprehensive technical documentation now available.
• September 28, 2025: 🎉 [HunyuanImage-3.0 Open Source](https://github.com/Tencent-Hunyuan/HunyuanImage-3.0) - Inference code and model weights publicly available.

🧩 Community Contributions

If you develop/use HunyuanImage-3.0 in your projects, welcome to let us know.

📑 Open-source Plan

• HunyuanImage-3.0 (Image Generation Model)
• [x] Inference
• [x] HunyuanImage-3.0 Checkpoints
• [x] HunyuanImage-3.0-Instruct Checkpoints (with reasoning)
• [x] vLLM Support
• [x] Distilled Checkpoints
• [x] Image-to-Image Generation
• [ ] Multi-turn Interaction

🗂️ Contents

• [🔥🔥🔥 News](#-news)
• [🧩 Community Contributions](#-community-contributions)
• [📑 Open-source Plan](#-open-source-plan)
• [📖 Introduction](#-introduction)
• [✨ Key Features](#-key-features)
• [🚀 Usage](#-usage)
• [📦 Environment Setup](#-environment-setup)
• [📥 Install Dependencies](#-install-dependencies)
• [HunyuanImage-3.0-Instruct](#hunyuanimage-30-instruct-instruction-reasoning-and-image-to-image-generation-including-editing-and-multi-image-fusion)
• [🔥 Quick Start with Transformers](#-quick-start-with-transformers)
• [1️⃣ Download model weights](#1-download-model-weights)
• [2️⃣ Run with Transformers](#2-run-with-transformers)
• [🏠 Local Installation & Usage](#-local-installation--usage)
• [1️⃣ Clone the Repository](#1-clone-the-repository)
• [2️⃣ Download Model Weights](#2-download-model-weights)
• [3️⃣ Run the Demo](#3-run-the-demo)
• [4️⃣ Command Line Arguments](#4-command-line-arguments)
• [5️⃣ For fewer Sampling Steps](#5-for-fewer-sampling-steps)
• [HunyuanImage-3.0 (Text-to-image)](#hunyuanimage-30-text-to-image)
• [🔥 Quick Start with Transformers](#-quick-start-with-transformers-1)
• [1️⃣ Download model weights](#1-download-model-weights-1)
• [2️⃣ Run with Transformers](#2-run-with-transformers-1)
• [🏠 Local Installation & Usage](#-local-installation--usage-1)
• [1️⃣ Clone the Repository](#1-clone-the-repository-1)
• [2️⃣ Download Model Weights](#2-download-model-weights-1)
• [3️⃣ Run the Demo](#3-run-the-demo-1)
• [4️⃣ Command Line Arguments](#4-command-line-arguments-1)
• [🎨 Interactive Gradio Demo](#-interactive-gradio-demo)
• [1️⃣ Install Gradio](#1-install-gradio)
• [2️⃣ Configure Environment](#2-configure-environment)
• [3️⃣ Launch the Web Interface](#3-launch-the-web-interface)
• [4️⃣ Access the Interface](#4-access-the-interface)
• [🧱 Models Cards](#-models-cards)
• [📊 Evaluation](#-evaluation)
• [Evaluation of HunyuanImage-3.0-Instruct](#evaluation-of-hunyuanimage-30-instruct)
• [Evaluation of HunyuanImage-3.0 (Text-to-Image)](#evaluation-of-hunyuanimage-30-text-to-image)
• [🖼️ Showcase](#-showcase)
• [Showcases of HunyuanImage-3.0-Instruct](#showcases-of-hunyuanimage-30-instruct)
• [📚 Citation](#-citation)
• [🙏 Acknowledgements](#-acknowledgements)
• [🌟🚀 Github Star History](#-github-star-history)

---

📖 Introduction

HunyuanImage-3.0 is a groundbreaking native multimodal model that unifies multimodal understanding and generation within an autoregressive framework. Our text-to-image and image-to-image model achieves performance comparable to or surpassing leading closed-source models.

✨ Key Features

• 🧠 Unified Multimodal Architecture: Moving beyond the prevalent DiT-based architectures, HunyuanImage-3.0 employs a unified autoregressive framework. This design enables a more direct and integrated modeling of text and image modalities, leading to surprisingly effective and contextually rich image generation.

• 🏆 The Largest Image Generation MoE Model: This is the largest open-source image generation Mixture of Experts (MoE) model to date. It features 64 experts and a total of 80 billion parameters, with 13 billion activated per token, significantly enhancing its capacity and performance.

• 🎨 Superior Image Generation Performance: Through rigorous dataset curation and advanced reinforcement learning post-training, we've achieved an optimal balance between semantic accuracy and visual excellence. The model demonstrates exceptional prompt adherence while delivering photorealistic imagery with stunning aesthetic quality and fine-grained details.

• 💭 Intelligent Image Understanding and World-Knowledge Reasoning: The unified multimodal architecture endows HunyuanImage-3.0 with powerful reasoning capabilities. It under stands user's input image, and leverages its extensive world knowledge to intelligently interpret user intent, automatically elaborating on sparse prompts with contextually appropriate details to produce superior, more complete visual outputs.

🚀 Usage

📦 Environment Setup

• 🐍 Python: 3.12+ (recommended and tested)
• ⚡ CUDA: 12.8

📥 Install Dependencies

# 1. First install PyTorch (CUDA 12.8 Version)
pip install torch==2.8.0 torchvision==0.23.0 torchaudio==2.8.0 --index-url https://download.pytorch.org/whl/cu128

# 2. Install tencentcloud-sdk for Prompt Enhancement (PE) only for HunyuanImage-3.0 not HunyuanImage-3.0-Instruct
pip install -i https://mirrors.tencent.com/pypi/simple/ --upgrade tencentcloud-sdk-python

# 3. Then install other dependencies
pip install -r requirements.txt

For up to 3x faster inference, install these optimizations:

# FlashInfer for optimized moe inference. v0.5.0 is tested.
pip install flashinfer-python==0.5.0

> 💡Installation Tips: It is critical that the CUDA version used by PyTorch matches the system's CUDA version. > FlashInfer relies on this compatibility when compiling kernels at runtime. > GCC version >=9 is recommended for compiling…