> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-es/generacion-de-imagenes/hunyuan-image3.md).

# HunyuanImage 3.0

Ejecuta HunyuanImage 3.0: el modelo multimodal de generación y edición de imágenes MoE de 80B de Tencent en GPUs de Clore.ai

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 de parámetros totales (13B activos durante la inferencia). Lanzado el 26 de enero de 2026, rompe el molde al unificar la generación, edición y comprensión de imágenes en un único modelo autoregresivo — ya no hay más canalizaciones separadas para texto a imagen e imagen a imagen. Genera imágenes fotorrealistas, realiza ediciones precisas preservando elementos, maneja transferencias de estilo e incluso hace fusión de 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 Hunyuan de Tencent (gratuita para investigación y uso comercial por debajo de 100M MAU)

## Características clave

* **80B de parámetros totales / 13B activos** — el mayor modelo MoE de imágenes 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 de múltiples imágenes en un solo modelo
* **Edición guiada por instrucciones** — describe lo que quieres cambiar en lenguaje natural, preservando los elementos no tocados
* **Checkpoint 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** — compatibilidad nativa con vLLM para una inferencia significativamente más rápida en producción
* **Marco autoregresivo** — 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 del 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 + múltiples imágenes | 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

{% hint style="warning" %}
**Los equipos multinodo de clase 80GB no aparecen listados en el marketplace de Clore.ai.** Los equipos más grandes listados hoy son 4× RTX PRO 6000 Blackwell (96GB cada una, 380GB en total) y 8–11× RTX 5090 (32GB cada una). La capacidad A100 / H200 / B200 se vende como [bare metal](https://clore.ai/bare-metal) bajo pedido. Consulta [Precios y disponibilidad de GPU](/guides/guides_v2-es/primeros-pasos/pricing.md) antes de dimensionar un despliegue.
{% endhint %}

| Configuración | Una sola GPU (offloading)    | Recomendado  | Producción con múltiples GPU |
| ------------- | ---------------------------- | ------------ | ---------------------------- |
| GPU           | 1× RTX 4090 24GB             | 1× A100 80GB | 2–3× A100 80GB               |
| VRAM          | 24GB (con offload por capas) | 80 GB        | 160–240GB                    |
| RAM           | 128GB                        | 128GB        | 256GB                        |
| Disco         | 200GB                        | 200GB        | 200GB                        |
| CUDA          | 12.8+                        | 12.8+        | 12.8+                        |

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

* **La mejor relación calidad-precio en el mercado:** 1× RTX PRO 6000 Blackwell 96GB ($0.92–1.38/h) — ejecuta el modelo completo cómodamente sin offloading. Una A100 80GB es la opción clásica, pero solo está disponible como [bare metal](https://clore.ai/bare-metal)
* **Opción económica:** 1× RTX 4090 ($0.14–0.42/h) — funciona con offloading de CPU (más lento, pero funcional)
* **Producción rápida:** 2× A100 80GB ([bare metal](https://clore.ai/bare-metal)) — para generación por lotes y el modelo Instruct

## Inicio rápido

### Instalación

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

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

# Descarga los 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

# Carga el 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,
)

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

### Usando la interfaz web de Gradio

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

```bash
cd HunyuanImage-3.0

# Instala Gradio
pip install gradio

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

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

## Ejemplos de uso

### 1. Generación de texto a imagen (CLI)

```bash
cd HunyuanImage-3.0

python inference.py \
    --model-path ./ckpts/HunyuanImage-3-Instruct \\
    --prompt "Paisaje urbano ciberpunk por la 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 características 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 al 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 modelo destilado (8 pasos)

```bash
# Descarga el checkpoint destilado
huggingface-cli download tencent/HunyuanImage-3.0-Instruct-Distil \\
    --local-dir ./ckpts/HunyuanImage-3-Instruct-Distil

# Genera 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 imágenes

| Función                      | HunyuanImage 3.0         | FLUX.2 Klein            | SD 3.5 Large            |
| ---------------------------- | ------------------------ | ----------------------- | ----------------------- |
| Parámetros                   | MoE de 80B (13B activos) | DiT de 32B              | DiT de 8B               |
| Arquitectura                 | MoE autoregresivo        | Transformer de difusión | Transformer 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 (con offloading)  | 16GB                    | 8GB                     |
| Velocidad (A100)             | \~15–30 seg              | \~0.3 seg               | \~5 seg                 |
| Licencia                     | Comunidad de Tencent     | Apache 2.0              | Stability AI CL         |

## Consejos para usuarios de Clore.ai

1. **Usa el modelo destilado para mayor velocidad** — `HunyuanImage-3.0-Instruct-Distil` genera en 8 pasos en lugar de 30–50, reduciendo el tiempo de inferencia entre 4 y 6 veces. La calidad sigue siendo sorprendentemente cercana a la del modelo completo.
2. **Una tarjeta de 96GB es el punto óptimo** — Una sola RTX PRO 6000 Blackwell (o una A100 80GB mediante [bare metal](https://clore.ai/bare-metal)) ejecuta el modelo Instruct sin trucos de offloading. Esto es mucho más rápido que una RTX 4090 con offloading de CPU.
3. **Predescarga los modelos** — El checkpoint Instruct completo pesa \~160GB. Descárgalo una vez en un volumen persistente de Clore.ai para evitar volver a descargarlo cada vez que inicies una nueva instancia.
4. **Usa túnel SSH para Gradio** — No expongas públicamente el puerto 7860. Usa `ssh -L 7860:localhost:7860` para acceder a la interfaz web de forma segura desde tu navegador.
5. **Prueba el backend vLLM para trabajos 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 sin memoria` en la RTX 4090                            | Usa `device_map="auto"` para habilitar el offloading de CPU, o cambia al modelo Distil                                                      |
| La descarga falla / es muy lenta                             | Establece `HF_TOKEN` variable de entorno; usa `huggingface-cli download` con `--resume-download`                                            |
| No se puede cargar el modelo mediante el ID del modelo de HF | Debido al punto en el nombre, clónalo localmente primero: `huggingface-cli download tencent/HunyuanImage-3.0-Instruct --local-dir ./ckpts/` |
| Resultados borrosos o de baja calidad                        | Aumenta `--num-inference-steps` a 40–50; aumenta `--guidance-scale` a 7.0                                                                   |
| La edición de imágenes ignora las instrucciones              | Sé específico sobre qué cambiar y qué preservar; usa prompts cortos y claros                                                                |
| La interfaz de Gradio no se inicia                           | Asegúrate de `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 de 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 comunitario de ComfyUI


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.