|
Sube una imagen y conviértela automáticamente en un mundo 3D interactivo: un entorno navegable como Gaussian Splat (.spz) generado por World Labs, más un modelo 3D del objeto (.glb) generado por el proveedor que elijas.
💡 ¿Cómo funciona por dentro? En
FAQ.mdexplico paso a paso cómo monta la escena React Three Fiber, el flujo de SSE, el sistema de caché por hash y las decisiones de diseño. El detalle técnico (tipos, endpoints, particularidades de SparkRenderer) está endocs/ARCHITECTURE.md.
El flujo real de la app: la imagen entra por el drop zone, el backend lanza los dos jobs en paralelo y el progreso llega por SSE. El entorno 3D es un Gaussian Splat generado por World Labs. El segundo job —el modelo del objeto (.glb)— necesita la API key de su proveedor, por eso en el GIF aparece en rojo.
No hay demo hospedada — cada proveedor de modelos 3D necesita sus propias credenciales. Para levantarlo en local:
./start.sh- Frontend: http://localhost:5173
- Backend: http://localhost:3001
Con Local TRELLIS self-hosted no hace falta API key para el modelo 3D, pero el entorno (.spz) lo genera siempre World Labs, así que sí necesitas WORLD_LABS_API_KEY.
La escena 3D que genera World Labs a partir de la imagen del GIF:
- Subes una imagen desde el navegador y eliges el proveedor de modelo 3D
- El backend lanza dos jobs en paralelo:
- World Labs → genera el entorno 3D completo como Gaussian Splat (
.spz) - Proveedor de modelo → genera el objeto 3D (
.glb) con el proveedor elegido
- World Labs → genera el entorno 3D completo como Gaussian Splat (
- El frontend muestra el progreso en tiempo real vía Server-Sent Events
- En cuanto cada asset está listo, aparece en la escena 3D — sin esperar al otro
- Cuando ambos terminan, la escena ocupa toda la pantalla con OrbitControls para rotar y explorar
- Si subes la misma imagen otra vez, los assets se sirven desde caché local — sin rellamar a las APIs
Cada imagen genera un hash SHA-256 (16 chars) que es el nombre de la carpeta de caché. El ID del job añade el provider (<hash>-<provider>), porque la misma imagen con otro provider es otro job:
backend/outputs/
└── acf548744b89fc02/
├── source.jpeg ← imagen original (la extensión sale del mimeType)
├── environment.spz ← entorno World Labs (se comparte entre providers)
├── model.meshy.glb ← modelo 3D de Meshy (uno por provider)
├── model.tripo.glb ← modelo 3D de Tripo
└── metadata.json ← assets y providers que han generado cada asset
- Misma imagen + mismo provider → ambos assets desde caché, instantáneo
- Misma imagen + distinto provider → reutiliza el
.spz, regenera solo el.glbde ese provider - Imagen nueva → genera todo y lo guarda
| Proveedor | Estado | Velocidad | Registro |
|---|---|---|---|
| Local TRELLIS | ✅ Gratis (self-hosted) | Depende del hardware | — |
| Meshy | ❌ API de pago | ~60 s | meshy.ai |
| Replicate TRELLIS | ~25 s | replicate.com/account/api-tokens | |
| Tripo3D | ❌ Free wallet no sirve para API | ~30 s | platform.tripo3d.ai |
| Stable Fast 3D | ❌ Créditos agotados rápido | < 1 s | platform.stability.ai |
| FAL Hunyuan3D | ❌ De pago | ~2 min | fal.ai |
El entorno World Labs (
.spz) siempre se genera independientemente del proveedor elegido y funciona correctamente.
Nota sobre Replicate: los tokens de sesión que genera el dashboard expiran en horas. Para uso en la app crea un token permanente en replicate.com/account/api-tokens.
Puedes montar TRELLIS en una máquina con GPU y apuntar la app a ella — sin coste por llamada a API.
El backend envía POST /predictions con la imagen en base64:
{ "image": "data:image/jpeg;base64,..." }El servidor puede responder de dos formas:
Síncrona (resultado inmediato):
{ "output": "http://tu-servidor/model.glb" }o
{ "glb_url": "http://tu-servidor/model.glb" }Asíncrona (procesamiento en background, polling cada 3 s):
// POST /predictions → devuelve id
{ "id": "abc123", "status": "processing" }
// GET /predictions/abc123
{ "status": "succeeded", "output": "http://tu-servidor/model.glb" }El campo output puede ser string o array de strings — se elige automáticamente el primer .glb.
Selecciona Local TRELLIS en el selector de provider y aparece un campo de texto donde puedes cambiar la URL (por defecto http://localhost:8000). La URL se envía al backend en cada petición, no hace falta reiniciar nada.
- Node.js 18.17+ para la app (
sharpno baja de ahí) y 20.6+ paranpm test(node --import). Recomendado: Node 22, la versión que usa CI - API keys en
backend/.env
Un solo comando instala todo y levanta ambos servidores:
./start.sh- Frontend: http://localhost:5173
- Backend: http://localhost:3001
Importante: después de editar
.envreinicia los servidores —tsx watchrecarga el código pero no las variables de entorno.
Edita backend/.env:
WORLD_LABS_API_KEY= # worldlabs.ai → API settings
FAL_KEY= # fal.ai/dashboard → API keys
TRIPO_API_KEY= # platform.tripo3d.ai → API keys
STABILITY_API_KEY= # platform.stability.ai → API keys
REPLICATE_API_TOKEN= # replicate.com/account/api-tokens (token permanente, no de sesión)
MESHY_API_KEY= # meshy.ai → requiere plan de pago
PORT=3001Solo necesitas las keys de los proveedores que vayas a usar. Si una key está vacía, ese proveedor falla con un error claro en la UI. Local TRELLIS no necesita key para el modelo 3D, pero World Labs siempre necesita la suya para el entorno.
Cada generación llama a World Labs y a un proveedor de pago, así que el backend se protege solo:
| Env | Por defecto | Qué hace |
|---|---|---|
RATE_LIMIT_MAX |
10 |
subidas por IP cada 10 min (429 al superarlas) |
MAX_ACTIVE_JOBS |
4 |
generaciones simultáneas (503 al superarlas) |
OUTPUTS_DIR |
backend/outputs |
raíz de la caché en disco |
Si lo expones a internet, ponlo detrás de algo que autentique (Cloudflare Access, un proxy con Basic Auth…). La API no tiene autenticación propia: una SPA de navegador no puede guardar un secreto, así que el límite por IP es lo que protege tu cuota. Con un proxy delante, el problema desaparece.
Backend — Express 5 + TypeScript
POST /api/generate— recibe imagen, calcula hash, comprueba caché, lanza jobs en paralelo (con rate limit por IP y tope de jobs simultáneos)GET /api/status/:jobId— Server-Sent Events con progreso en tiempo realGET /api/assets/:jobId/spz|glb— sirve assets desde buffer en memoria (sin CORS)- Las imágenes se ajustan a un máximo de 1024×1024 px (conservando la relación de aspecto) sólo si superan 1 MP; por debajo de ese tamaño se envían sin modificar (usando
sharp). La API de World Labs recibe la imagen original sin redimensionar - La URL del servidor TRELLIS local se valida antes de pedirla (esquema y rangos link-local bloqueados, y cada redirección se revalida) para que el backend no se convierta en un proxy hacia la red interna
Frontend — Vite + React 19 + TypeScript + Tailwind CSS
useJobSSE— hook que abre unEventSourcey actualiza el estado reactivamenteSplatEnvironment— renderiza el.spzcon@sparkjsdev/spark(integración imperativa en R3F, rotación X corregida para World Labs)GlbObject— carga el.glbconuseGLTFy lo auto-centra/escala en la escenaViewer3D— Canvas de React Three Fiber con OrbitControls
imageTron/
├── start.sh ← instala todo y arranca ambos servidores
├── docs/
│ ├── ARCHITECTURE.md ← arquitectura, tipos, flujo SSE, particularidades de Spark
│ ├── demo.gif ← demo del flujo (imagen → mundo 3D)
│ └── scene-3d.jpg ← captura de la escena 3D generada
├── backend/
│ ├── .env ← tus API keys (no en git)
│ ├── .env.example ← plantilla
│ ├── outputs/ ← assets generados, organizados por hash de imagen (no en git)
│ ├── test/
│ │ ├── outputStore.test.ts ← tests de hash y caché (node --test)
│ │ ├── jobStore.test.ts ← tests del estado de job y del evento SSE
│ │ ├── rateLimit.test.ts ← tests del límite por IP
│ │ └── safeUrl.test.ts ← tests de la validación de URL (SSRF)
│ └── src/
│ ├── index.ts
│ ├── types.ts
│ ├── routes/
│ │ ├── generate.ts ← POST /api/generate (hash + caché + dispatch)
│ │ ├── status.ts ← GET /api/status/:jobId (SSE)
│ │ └── assets.ts ← GET /api/assets/:jobId/:type
│ └── services/
│ ├── jobStore.ts ← estado en memoria + broadcast SSE (con TTL y topes)
│ ├── outputStore.ts ← caché en disco (hash → carpeta, .glb por provider)
│ ├── rateLimit.ts ← límite de subidas por IP
│ ├── safeUrl.ts ← validación de URL (anti-SSRF)
│ ├── imageResize.ts ← ajusta a máx. 1024×1024 (fit inside) si supera 1 MP
│ ├── worldLabs.ts ← World Labs API + polling 15s
│ ├── falApi.ts ← FAL queue API + polling 10s
│ ├── tripoApi.ts ← Tripo3D API + polling 10s
│ ├── stabilityApi.ts ← Stability AI (respuesta directa)
│ ├── replicateApi.ts ← Replicate TRELLIS + polling 5s
│ ├── meshyApi.ts ← Meshy API + polling 8s
│ └── localTrellisApi.ts ← TRELLIS self-hosted + polling 3s
└── frontend/
├── public/
│ └── terminator2.png ← logo (servido por Vite desde frontend/public)
└── src/
├── App.tsx
├── types.ts
├── hooks/
│ ├── useJobSSE.ts
│ └── useImageUpload.ts
├── components/
│ ├── UploadZone.tsx ← drag-drop + selector de provider + URL campo local
│ ├── ProgressPanel.tsx ← barras de progreso en tiempo real
│ └── Viewer3D.tsx ← canvas 3D
└── three/
├── SplatEnvironment.tsx ← Gaussian splat (Y-flip corregido)
└── GlbObject.tsx ← modelo GLB auto-centrado
MIT. Ver LICENSE.
Alejandro Huerta — Senior Frontend / Tools Engineer. Madrid (remoto). github.com/ahuertam · linkedin.com/in/alejandrohuertaengineer


