Hunyuan3D 2.1

Genera mallas 3D a partir de texto o imágenes con Tencent Hunyuan3D 2.1 en Clore.ai

Hunyuan3D 2.1 de Tencent es un modelo de generación 3D de dos etapas: primero predice la geometría (forma) y luego sintetiza texturas PBR. Acepta tanto prompts de texto como imágenes de referencia como entrada y genera mallas listas para producción en formato GLB, OBJ o PLY. Con más de 3 millones de descargas en HuggingFace, es uno de los modelos de generación 3D de código abierto más adoptados.

Todos los ejemplos se ejecutan en servidores GPU alquilados a través de Marketplace de CLORE.AI.

Características clave

• Texto a 3D e imagen a 3D — ambos modos de entrada en un solo modelo

• Flujo de trabajo en dos etapas — generación de geometría seguida de síntesis de texturas PBR

• Salida de alta fidelidad — geometría detallada con mapas de albedo, normales y rugosidad

• Múltiples formatos de exportación — GLB, OBJ, PLY

• Interfaz web de Gradio — interacción basada en navegador, no requiere programación

• 16–24 GB de VRAM — funciona en RTX 3090 y RTX 4090

• Más de 3 millones de descargas en HuggingFace — comunidad activa y actualizaciones continuas

Requisitos

Componente	Mínimo	Recomendado
GPU	RTX 3090 24 GB	RTX 4090 24 GB
VRAM	16 GB	24 GB
RAM	16 GB	32 GB
Disco	50 GB	100 GB
CUDA	12.8+	12.8+
Python	3.10	3.11

Precios de Clore.ai: RTX 4090 ≈ $0.14–0.42/h · RTX 3090 ≈ $0.07–0.21/h

Inicio rápido

1. Clonar e instalar

git clone https://github.com/Tencent/Hunyuan3D-2.git
cd Hunyuan3D-2

# Crear entorno
conda create -n hunyuan3d python=3.10 -y
conda activate hunyuan3d

# Instalar PyTorch
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128

# Instalar dependencias
pip install -r requirements.txt

# Descargar pesos del modelo (se descargan automáticamente en la primera ejecución, ~15 GB en total)
python -c "from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline; Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2')"

2. Iniciar la interfaz web de Gradio

python gradio_app.py --port 7860 --share

La interfaz proporciona:

• Campo de entrada de texto para generación de texto a 3D

• Carga de imagen para generación de imagen a 3D

• Deslizadores para pasos de inferencia, escala de guía y semilla

• Vista previa del modelo 3D con controles de órbita

• Botones de descarga para GLB/OBJ/PLY

3. Generar mediante la API de Python

from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline
from hy3dgen.texgen import Hunyuan3DPaintPipeline

# Etapa 1: generación de geometría
shape_pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(
    "tencent/Hunyuan3D-2",
    subfolder="shapegen",
)
shape_pipeline.to("cuda")

# Generar malla a partir de texto
mesh = shape_pipeline(
    prompt="una espada medieval detallada con mango ornamentado",
    num_inference_steps=30,
    guidance_scale=7.5,
    seed=42,
)[0]

mesh.export("sword_shape.glb")

4. Añadir texturas (Etapa 2)

# Etapa 2: síntesis de texturas
texture_pipeline = Hunyuan3DPaintPipeline.from_pretrained(
    "tencent/Hunyuan3D-2",
    subfolder="texgen",
)
texture_pipeline.to("cuda")

textured_mesh = texture_pipeline(
    mesh=mesh,
    prompt="una espada medieval detallada con mango ornamentado",
    num_inference_steps=20,
    seed=42,
)[0]

textured_mesh.export("sword_textured.glb")

Ejemplos de uso

Generación de imagen a 3D

from PIL import Image

# Cargar imagen de referencia
image = Image.open("reference_chair.png")

# Generar geometría a partir de la imagen
mesh = shape_pipeline(
    image=image,
    num_inference_steps=30,
    guidance_scale=7.5,
    seed=42,
)[0]

# Aplicar textura
textured = texture_pipeline(
    mesh=mesh,
    image=image,
    num_inference_steps=20,
    seed=42,
)[0]

textured.export("chair.glb")

Procesamiento por lotes

from pathlib import Path

prompts = [
    "un coche deportivo rojo, recurso de videojuego low-poly",
    "un cofre del tesoro de madera, material PBR",
    "un casco de ciencia ficción con visor, superficie dura",
]

output_dir = Path("/workspace/3d-output")
output_dir.mkdir(exist_ok=True)

for i, prompt in enumerate(prompts):
    mesh = shape_pipeline(prompt=prompt, num_inference_steps=30, seed=42)[0]
    textured = texture_pipeline(mesh=mesh, prompt=prompt, num_inference_steps=20, seed=42)[0]
    textured.export(str(output_dir / f"asset_{i:03d}.glb"))
    print(f"Generado: asset_{i:03d}.glb — {prompt[:40]}")

Exportar a múltiples formatos

# GLB (recomendado — incluye texturas, formato universal)
textured_mesh.export("model.glb")

# OBJ (con archivo de material MTL)
textured_mesh.export("model.obj")

# PLY (colores de vértices, compatible con nubes de puntos)
textured_mesh.export("model.ply")

Referencia de rendimiento

GPU	Geometría (30 pasos)	Textura (20 pasos)	Total
RTX 4090	~20 seg	~15 seg	≈35 s
RTX 3090	~30 s	~25 s	≈55 s
A100 40G	~18 seg	~12 s	~30 s

Consejos

• Elimina los fondos de imagen antes de imagen a 3D — usa rembg para una segmentación limpia

• Los prompts de texto se benefician de la especificidad — "una espada medieval low-poly con mango envuelto en cuero" produce mejores resultados que "espada"

• Reduce num_inference_steps a 15–20 para vistas previas más rápidas durante la iteración

• Aumenta guidance_scale (8–12) para una mayor fidelidad al prompt a costa de la diversidad

• GLB es el mejor formato de exportación — agrupa geometría, texturas y materiales en un solo archivo

• Usa --share al iniciar Gradio en Clore.ai para acceso remoto desde el navegador

• Los pesos del modelo son ~15 GB — asegúrate de tener suficiente espacio en disco antes de la primera ejecución

• Para recursos de videojuegos, genera con alta calidad y luego reduce la malla en Blender para niveles LOD

Solución de problemas

Problema	Solución
CUDA sin memoria	Usa una RTX 3090 o superior (24 GB). Reduce el tamaño del lote o los pasos de inferencia
La descarga del modelo se detiene	Comprueba el espacio en disco. Usa huggingface-cli download tencent/Hunyuan3D-2 manualmente
La interfaz de Gradio no es accesible	Pasa --share la opción --share, o reenvía el puerto 7860 desde el panel de Clore.ai
Calidad de geometría deficiente	Aumenta num_inference_steps a 40 o más, prueba distintas semillas
Artefactos de textura	Asegúrate de que la malla de la geometría esté limpia antes de la etapa de textura
Errores de importación en una instalación nueva	Ejecuta pip install -r requirements.txt de nuevo — algunas dependencias se compilan desde el código fuente
Generación lenta en la primera ejecución	Es esperado — la compilación del modelo y la carga de pesos se almacenan en caché después de la primera inferencia

Recursos

• Hunyuan3D-2 en GitHub

• Modelo de HuggingFace

• Marketplace de CLORE.AI