# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-es/generacion-de-imagenes/hunyuan-image3.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.