# HunyuanImage 3.0

HunyuanImage 3.0 de Tencent es el **modelo de generación de imágenes de código abierto más grande del mundo** con 80B parámetros totales (13B activos durante la inferencia). Lanzado el 26 de enero de 2026, rompe el molde al unificar generación, edición y comprensión de imágenes en un solo modelo autorregresivo — ya no hay canalizaciones separadas para texto a imagen e imagen a imagen. Genera imágenes fotorrealistas, realiza ediciones precisas que preservan elementos, maneja transferencias de estilo e incluso fusiona múltiples imágenes, todo desde un solo modelo.

**HuggingFace:** [tencent/HunyuanImage-3.0-Instruct](https://huggingface.co/tencent/HunyuanImage-3.0-Instruct) **GitHub:** [Tencent-Hunyuan/HunyuanImage-3.0](https://github.com/Tencent-Hunyuan/HunyuanImage-3.0) **Licencia:** Licencia Comunitaria Tencent Hunyuan (gratuita para uso de investigación y comercial bajo 100M MAU)

## Características clave

* **80B totales / 13B parámetros activos** — mayor modelo MoE de imagen de código abierto; activa solo 13B parámetros por inferencia
* **Arquitectura multimodal unificada** — texto a imagen, edición de imágenes, transferencia de estilo y composición multiimagen en un solo modelo
* **Edición impulsada por instrucciones** — describe lo que deseas cambiar en lenguaje natural, preservando los elementos no modificados
* **Punto de control destilado disponible** — `HunyuanImage-3.0-Instruct-Distil` se ejecuta en solo 8 pasos de muestreo para una generación más rápida
* **Aceleración vLLM** — soporte nativo de vLLM para una inferencia significativamente más rápida en producción
* **Marco autorregresivo** — a diferencia de los modelos basados en DiT (FLUX, SD3.5), usa un enfoque AR unificado tanto para la comprensión como para la generación

## Variantes de modelo

| Modelo                               | Caso de uso                             | Pasos | HuggingFace                                |
| ------------------------------------ | --------------------------------------- | ----- | ------------------------------------------ |
| **HunyuanImage-3.0**                 | Solo texto a imagen                     | 30–50 | `tencent/HunyuanImage-3.0`                 |
| **HunyuanImage-3.0-Instruct**        | Texto a imagen + edición + multi-imagen | 30–50 | `tencent/HunyuanImage-3.0-Instruct`        |
| **HunyuanImage-3.0-Instruct-Distil** | Inferencia rápida (8 pasos)             | 8     | `tencent/HunyuanImage-3.0-Instruct-Distil` |

## Requisitos

| Configuración | GPU única (offloading)      | Recomendado  | Producción multi-GPU |
| ------------- | --------------------------- | ------------ | -------------------- |
| GPU           | 1× RTX 4090 24GB            | 1× A100 80GB | 2–3× A100 80GB       |
| VRAM          | 24GB (con offload de capas) | 80GB         | 160–240GB            |
| RAM           | 128GB                       | 128GB        | 256GB                |
| Disco         | 200GB                       | 200GB        | 200GB                |
| CUDA          | 12.0+                       | 12.0+        | 12.0+                |

**Configuración recomendada para Clore.ai:**

* **Mejor valor:** 1× A100 80GB (\~$2–4/día) — ejecuta el modelo completo cómodamente sin offloading
* **Opción económica:** 1× RTX 4090 (\~$0.5–2/día) — funciona con offloading a CPU (más lento, pero funcional)
* **Producción rápida:** 2× A100 80GB (\~$4–8/día) — para generación por lotes y el modelo Instruct

## Inicio rápido

### Instalación

```bash
# Clonar el repositorio
git clone https://github.com/Tencent-Hunyuan/HunyuanImage-3.0.git
cd HunyuanImage-3.0

# Crear entorno
pip install -r requirements.txt
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

# Descargar pesos del modelo
huggingface-cli download tencent/HunyuanImage-3.0-Instruct --local-dir ./ckpts/HunyuanImage-3-Instruct
```

### Texto a imagen con Transformers

```python
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

# Cargar modelo (requiere ~80GB de VRAM para precisión completa)
model_path = "./ckpts/HunyuanImage-3-Instruct"
model = AutoModelForCausalLM.from_pretrained(
    model_path,
    torch_dtype=torch.bfloat16,
    device_map="auto",
    trust_remote_code=True,
)

# Generar una imagen a partir de texto
prompt = "Un sereno jardín japonés en otoño, carpas koi nadando en un estanque cristalino, hojas de arce doradas cayendo, estilo pintura en acuarela"
output = model.generate_image(prompt, num_inference_steps=30)
output.save("japanese_garden.png")
```

### Usando la interfaz web Gradio

La forma más fácil de experimentar con todas las funciones:

```bash
cd HunyuanImage-3.0

# Instalar Gradio
pip install gradio

# Lanzar la interfaz web
python gradio_demo.py \
    --model-path ./ckpts/HunyuanImage-3-Instruct \
    --server-name 0.0.0.0 \
    --server-port 7860
```

Luego accede vía túnel SSH: `ssh -L 7860:localhost:7860 root@<clore-ip>`

## Ejemplos de uso

### 1. Generación Texto a Imagen (CLI)

```bash
cd HunyuanImage-3.0

python inference.py \
    --model-path ./ckpts/HunyuanImage-3-Instruct \
    --prompt "Paisaje urbano cyberpunk de noche, rascacielos iluminados por neón reflejados en calles empapadas por la lluvia, coches voladores, niebla volumétrica, 8K" \
    --output-path output.png \
    --num-inference-steps 30 \
    --guidance-scale 5.0
```

### 2. Edición de imágenes con lenguaje natural

Una de las funciones destacadas de HunyuanImage 3.0 — edita imágenes existentes describiendo los cambios:

```bash
python inference.py \
    --model-path ./ckpts/HunyuanImage-3-Instruct \
    --prompt "Cambia la estación a invierno con nieve cubriendo los árboles" \
    --image-path input_photo.jpg \
    --output-path edited_winter.png \
    --num-inference-steps 30
```

### 3. Generación rápida con el modelo destilado (8 pasos)

```bash
# Descargar punto de control destilado
huggingface-cli download tencent/HunyuanImage-3.0-Instruct-Distil \
    --local-dir ./ckpts/HunyuanImage-3-Instruct-Distil

# Generar con solo 8 pasos (5-6× más rápido)
python inference.py \
    --model-path ./ckpts/HunyuanImage-3-Instruct-Distil \
    --prompt "Retrato de un astronauta montando un caballo en Marte, fotorrealista" \
    --output-path astronaut.png \
    --num-inference-steps 8
```

## Comparación con otros modelos de imagen

| Función                      | HunyuanImage 3.0      | FLUX.2 Klein              | SD 3.5 Large              |
| ---------------------------- | --------------------- | ------------------------- | ------------------------- |
| Parámetros                   | 80B MoE (13B activos) | 32B DiT                   | 8B DiT                    |
| Arquitectura                 | MoE autorregresivo    | Transformador de difusión | Transformador de difusión |
| Edición de imágenes          | ✅ Nativo              | ❌ Requiere ControlNet     | ❌ Requiere img2img        |
| Fusión de múltiples imágenes | ✅ Nativo              | ❌                         | ❌                         |
| Transferencia de estilo      | ✅ Nativo              | ❌ Requiere LoRA           | ❌ Requiere LoRA           |
| VRAM mínima                  | \~24GB (offloaded)    | 16GB                      | 8GB                       |
| Velocidad (A100)             | \~15–30 seg           | \~0.3 seg                 | \~5 seg                   |
| Licencia                     | Comunidad Tencent     | Apache 2.0                | Stability AI CL           |

## Consejos para usuarios de Clore.ai

1. **Usa el modelo destilado para velocidad** — `HunyuanImage-3.0-Instruct-Distil` genera en 8 pasos en lugar de 30–50, reduciendo el tiempo de inferencia entre 4–6×. La calidad se mantiene sorprendentemente cercana al modelo completo.
2. **A100 80GB es el punto óptimo** — Una sola A100 80GB (\~$2–4/día en Clore.ai) ejecuta el modelo Instruct sin trucos de offloading. Esto es mucho más rápido que una RTX 4090 con offloading a CPU.
3. **Pre-descarga los modelos** — El checkpoint Instruct completo tiene \~160GB. Descárgalo una vez a un volumen persistente de Clore.ai para evitar volver a descargarlo cada vez que inicies una nueva instancia.
4. **Usa tunelización SSH para Gradio** — No expongas el puerto 7860 públicamente. Usa `ssh -L 7860:localhost:7860` para acceder a la interfaz web de forma segura desde tu navegador.
5. **Prueba el backend vLLM para trabajo por lotes** — Si estás generando muchas imágenes, la ruta de inferencia vLLM (en la `vllm_infer/` carpeta) ofrece un rendimiento significativamente mejor.

## Solución de problemas

| Problema                                            | Solución                                                                                                                                  |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `CUDA fuera de memoria` en RTX 4090                 | Usa `device_map="auto"` para habilitar offloading a CPU, o cambia al modelo Distil                                                        |
| La descarga falla / muy lenta                       | Configura `HF_TOKEN` variable env; usa `huggingface-cli download` con `--resume-download`                                                 |
| No se puede cargar el modelo vía ID de modelo de HF | Debido al punto en el nombre, clona localmente primero: `huggingface-cli download tencent/HunyuanImage-3.0-Instruct --local-dir ./ckpts/` |
| Salidas borrosas o de baja calidad                  | Aumente `--num-inference-steps` a 40–50; incrementa `--guidance-scale` a 7.0                                                              |
| La edición de imagen ignora las instrucciones       | Sé específico sobre qué cambiar y qué preservar; usa prompts cortos y claros                                                              |
| La interfaz Gradio no se inicia                     | Asegúrate de que `gradio>=4.0` esté instalado; verifica que la ruta del modelo apunte al directorio correcto                              |

## Lecturas adicionales

* [Repositorio de GitHub](https://github.com/Tencent-Hunyuan/HunyuanImage-3.0) — Código oficial, scripts de inferencia, demo de Gradio
* [HunyuanImage 3.0-Instruct (HuggingFace)](https://huggingface.co/tencent/HunyuanImage-3.0-Instruct) — Pesos completos del modelo
* [Checkpoint destilado](https://huggingface.co/tencent/HunyuanImage-3.0-Instruct-Distil) — Inferencia rápida en 8 pasos
* [Informe técnico (arXiv)](https://arxiv.org/pdf/2509.23951) — Detalles de la arquitectura y benchmarks
* [Integración con ComfyUI](https://github.com/bgreene2/ComfyUI-Hunyuan-Image-3) — Nodo personalizado Community ComfyUI