Subidas e integración frontend # Integra Transloadit en cinco minutos Instala el SDK de Node, redimensiona una imagen e inspecciona el resultado de una Assembly real en unos cinco minutos. Publicado el 26 de agosto de 2026 ## Conclusiones clave * Mantén el Auth Secret en un servidor de confianza y pásalo mediante variables de entorno. * Crea una Assembly con un Step de subida y un Step de redimensionado de imagen que ajuste la imagen dentro de 400 × 400 píxeles. * Imprime tanto la URL del resultado como el ID de la Assembly para que la primera ejecución sea fácil de inspeccionar. La integración útil más corta con Transloadit es un script del lado del servidor que sube una imagen y produce un derivado. Demuestra que las credenciales, la transferencia de archivos, el procesamiento y el manejo de resultados funcionan antes de agregar un navegador, un destino de almacenamiento, una base de datos o un webhook, lo que añade más piezas móviles. ## En esta guía 1. [Empieza con un único proceso de servidor de confianza](#transloadit-five-minute-integration-section-1) 2. [Instala el SDK y prepara el comando](#transloadit-five-minute-integration-section-2) 3. [Ejecuta la primera Assembly](#transloadit-five-minute-integration-section-3) 4. [Inspecciona el resultado en lugar de detenerte en el éxito](#transloadit-five-minute-integration-section-4) 5. [Convierte la prueba de concepto en una integración de producción](#transloadit-five-minute-integration-section-5) 6. [Expón un estado seguro, protege los diagnósticos y mantén una prueba de humo](#transloadit-five-minute-integration-section-6) ## Lo más importante * Trata el archivo devuelto como temporal hasta que un Step de exportación lo almacene de forma permanente. ## Empieza con un único proceso de servidor de confianza Crea un Workspace gratuito, abre la página de credenciales y genera una Auth Key y un Auth Secret. Necesitas ambos valores para esta guía rápida del lado del servidor. No pegues ninguno de los dos valores en el archivo fuente y nunca envíes el secreto a un navegador. El SDK de Node usa el par para autenticar solicitudes sin transmitir el Auth Secret como credencial de solicitud. Elige una imagen pequeña en formato JPEG, PNG, WebP o AVIF que ya tengas en disco. Una entrada modesta mantiene rápida la primera ejecución y facilita reconocer la salida. El script acepta la ruta del archivo como único argumento de línea de comandos, por lo que el mismo código puede reintentarse con otros datos de prueba sin editarlo. ### Auth Key Identifica la credencial usada para la Assembly y puede ser referenciada de forma segura por código de integración de confianza. ### Auth Secret Permanece en el entorno del servidor y el SDK lo usa para autenticar la solicitud. ### Un archivo local Mantiene esta ejecución centrada en la ruta de la API en lugar del estado de subida del navegador o las importaciones remotas. ## Instala el SDK y prepara el comando Crea un proyecto de módulo ES vacío y añade el SDK actual de Node con npm. En la siguiente sección, guarda el listado de TypeScript como `quickstart.ts`, y luego ejecútalo con el comando que se muestra después del listado. Esta guía rápida ejecuta el archivo TypeScript directamente con el type stripping nativo de Node, por lo que no necesita `tsx` ni `ts-node`. El type stripping nativo está habilitado de forma predeterminada desde Node 22.18 y Node 23.6, así que usa Node 22.18+, Node 23.6+ o Node 24. El SDK y la imagen son las únicas entradas en tiempo de ejecución. Pasa las credenciales al proceso mediante variables de entorno. El historial de la shell, la inspección de procesos, los registros de CI y la política de la máquina local afectan a si las asignaciones de entorno en línea son apropiadas, así que usa tu gestor de secretos habitual para producción. El comando que se muestra aquí es intencionalmente local y de corta duración. Preparar el proyecto e instalar el SDK de Node ``` mkdir transloadit-quickstart cd transloadit-quickstart npm init -y npm pkg set type=module npm install @transloadit/node ``` ### Una sola dependencia `@transloadit/node` gestiona la autenticación, la subida de archivos, el sondeo de estado y las respuestas tipadas. ### Node 24 Ejecuta el archivo TypeScript directamente a la vez que conserva un ejemplo tipado listo para copiar y pegar. ### No se requiere un archivo de secretos La guía rápida lee las dos credenciales del entorno del proceso. ## Ejecuta la primera Assembly Guarda el listado de TypeScript siguiente como `quickstart.ts`. El Step `:original` acepta la subida. El Step `resized` nombra a `:original` en `use`, por lo que se inicia después de que la subida produzca un archivo. Su `resize_strategy` es `fit`, que preserva la relación de aspecto y mantiene ambas dimensiones dentro de 400 píxeles en lugar de recortar la imagen a un cuadrado. Con `waitForCompletion` habilitado, `createAssembly` devuelve el resultado una vez que la Assembly alcanza un estado terminal. Ese comportamiento bloqueante hace que el primer resultado sea evidente, pero es una comodidad didáctica y no una arquitectura predeterminada para videos lentos, lotes grandes o un manejador de solicitudes con un tiempo de espera corto. Subir y redimensionar una imagen ``` import { Transloadit } from '@transloadit/node' async function main(): Promise { const authKey = process.env.TRANSLOADIT_KEY const authSecret = process.env.TRANSLOADIT_SECRET const inputPath = process.argv[2] if (authKey == null || authSecret == null || inputPath == null) { throw new Error( 'Set TRANSLOADIT_KEY and TRANSLOADIT_SECRET, then pass an image path.', ) } const transloadit = new Transloadit({ authKey, authSecret }) const assembly = await transloadit.createAssembly({ files: { image: inputPath }, params: { steps: { ':original': { robot: '/upload/handle', }, resized: { use: ':original', robot: '/image/resize', result: true, width: 400, height: 400, resize_strategy: 'fit', }, }, }, waitForCompletion: true, }) const result = assembly.results?.resized?.[0] if (result == null) { throw new Error(`Assembly ${assembly.assembly_id} produced no resized result.`) } console.log(`Result: ${result.ssl_url}`) console.log(`Assembly: ${assembly.assembly_id}`) } main().catch((error: unknown) => { if (!(error instanceof Error)) { throw new Error(`Was thrown a non-error: ${error}`) } console.error(error.message) process.exit(1) }) ``` Ejecutar la guía rápida ``` env \ TRANSLOADIT_KEY="YOUR_TRANSLOADIT_KEY" \ TRANSLOADIT_SECRET="YOUR_TRANSLOADIT_SECRET" \ node quickstart.ts ./your-image.jpg ``` ### :original El Step de subida reservado que pone los archivos entrantes a disposición de los siguientes Robots. ### resized Un nombre elegido por la integración; también se convierte en la clave que se usa para leer estos archivos de resultado. ### fit Limita la salida sin estirar ni eliminar contenido de la imagen. ## Inspecciona el resultado en lugar de detenerte en el éxito Abre la URL HTTPS del resultado impresa y confirma que las dimensiones y el contenido visible coinciden con la solicitud. Luego abre la Assembly en la Transloadit Console usando su ID. El Assembly Status muestra las subidas, los resultados de los Steps, las marcas de tiempo, los metadatos y cualquier error, lo que lo convierte en el primer lugar para comparar lo que solicitó la aplicación con lo que ejecutó la plataforma. Mantén el ID de la Assembly junto a tu propio identificador de trabajo o de recurso. Una URL por sí sola no basta para solucionar problemas, porque no explica qué entrada, parámetros o Step la produjeron. En producción, guarda de forma persistente los campos de resultado específicos que tu aplicación necesita, en lugar de almacenar o devolver por completo una respuesta sin procesar de terceros. ### Verificación visual Confirma que el flujo de trabajo produjo la variante prevista, y no solo un código de estado correcto. ### Assembly Status Proporciona la traza de procesamiento y los metadatos para depuración y conciliación. ### Registro de la aplicación Conecta el ID externo de la Assembly con el usuario, la entrada y la acción de negocio que la inició. ## Convierte la prueba de concepto en una integración de producción Los archivos temporales de la Assembly se conservan durante aproximadamente 24 horas y están pensados para un número limitado de recuperaciones a corto plazo, no para servirse directamente a los usuarios finales. Añade un Robot de exportación como `/s3/store`, `/azure/store` o el destino que gestione tu aplicación antes de que un resultado se vuelva persistente. Almacena las claves de la nube como credenciales de Template, no como valores literales en el código de la aplicación ni en las Assembly Instructions. A continuación, guarda los Steps como un Template, define `allow_steps_override` en false cuando quienes llaman no deban cambiar el grafo, y envía solo su `template_id` junto con los campos validados. Las subidas desde el navegador necesitan parámetros firmados y con vencimiento generados por un back end. El trabajo en segundo plano debería devolver de inmediato un ID de trabajo de la aplicación, consumir un webhook verificado, aceptar entregas duplicadas de forma segura y conciliar con el Assembly Status cuando falte una notificación. ### Exportación permanente Traslada los resultados fuera de la ventana de retención temporal predeterminada y los lleva a almacenamiento propio. ### Template guardado Mantiene controlado el grafo de procesamiento mientras las integraciones envían un ID de Template compacto. ### Finalización verificada Un webhook firmado y una conciliación periódica hacen recuperables los trabajos de larga duración. ## Expón un estado seguro, protege los diagnósticos y mantén una prueba de humo Una interfaz de producción debería mostrar un estado conciso propiedad de la aplicación, como en cola, procesando, listo o fallido. Los operadores aún necesitan una ruta protegida desde ese registro hasta el ID de la Assembly y diagnósticos saneados. No devuelvas a los usuarios finales errores sin procesar del proveedor, trazas de pila, respuestas de almacenamiento ni URL con credencial, solo porque la guía rápida imprime un resultado en una terminal. Mantén una pequeña imagen conocida como válida y las restricciones de salida esperadas como prueba de humo. Ejecútala tras rotar la credencial o realizar un cambio controlado en el flujo de trabajo, pero no incluyas una Assembly externa de pago en cada ejecución de pruebas unitarias. Las pruebas unitarias deben validar la política y el mapeo locales, mientras que una comprobación de integración explícita demuestra en conjunto la credencial en vivo, la subida, el Robot y la ruta del resultado. ### Estado seguro para el cliente Expón un estado accionable sin filtrar una respuesta de terceros ni una excepción interna. ### Ruta protegida Permite que los operadores autorizados accedan al ID de la Assembly y a los diagnósticos necesarios para investigar. ### Datos de prueba conocidos y válidos Separa los fallos de integración en vivo de los medios inusuales de los clientes cuando se prueba la ruta. ## Detalles técnicos que conviene conocer * Una Assembly es una ejecución de las Assembly Instructions. Cada Step de procesamiento invoca a un Robot y declara su entrada previa con `use`; el Step de subida reservado `:original` es la fuente y no toma `use`. * El SDK de Node genera la autenticación de la solicitud a partir de la Auth Key y el Auth Secret. El secreto debe residir únicamente en un proceso de servidor confiable, nunca en JavaScript de navegador ni en una aplicación móvil. * Establecer `waitForCompletion` en true hace que el SDK sondee hasta que la Assembly alcance un estado terminal, lo cual es conveniente para una primera ejecución pequeña pero inadecuado para manejadores de solicitudes de larga duración. * La bandera `result` marca los archivos de un Step para su inclusión en el objeto `results` de nivel superior de la Assembly. No hace que los archivos sean permanentes. * Los archivos temporales de la Assembly están disponibles durante unas 24 horas y un número limitado de recuperaciones de forma predeterminada. No sirvas sus URL directamente a los usuarios finales; agrega un Robot de exportación para los archivos orientados al usuario. * El ID de la Assembly es una referencia útil para la depuración, incluso cuando una aplicación almacena su propio identificador de trabajo de nivel superior. ## Un enfoque práctico 1. 1\ Crea una Auth Key y elige una imagen local pequeña. 2. 2\ Instala el SDK de Node y ejecuta la guía rápida de TypeScript con las credenciales en el entorno. 3. 3\ Abre la URL del resultado impresa e inspecciona la Assembly en la Consola. 4. 4\ Traslada el flujo de trabajo a un Template guardado y añade almacenamiento permanente antes de usarlo en producción. Un flujo de trabajo multimedia de cuatro etapas ## Cuándo resulta útil Transloadit Usa el SDK de Node para crear una Assembly que contenga /upload/handle e /image/resize. El SDK firma la solicitud con credenciales del lado del servidor, sube el archivo local, espera a que finalice y devuelve la URL del resultado y el ID de la Assembly. ## Límite de la arquitectura Esta guía rápida se ejecuta en un servidor confiable y espera a que termine una imagen pequeña. Una integración en el navegador debe recibir parámetros firmados y de corta duración desde un back end, mientras que el trabajo en segundo plano en producción debería usar un webhook verificado en lugar de mantener abierta una solicitud HTTP. ## Preguntas frecuentes ### ¿Puedo colocar el Auth Secret en JavaScript del navegador para esta guía rápida? No. El ejemplo es del lado del servidor. Un navegador debe solicitar parámetros de Assembly firmados y de corta duración a un back end que mantenga el Auth Secret en privado. ### ¿Por qué el script espera a que finalice? `waitForCompletion` facilita verificar una primera ejecución al devolver el resultado terminado. Los manejadores de solicitudes en producción normalmente deberían iniciar el trabajo en segundo plano y usar un webhook verificado o un sondeo de estado controlado. ### ¿Dónde se almacena la imagen redimensionada? Es un resultado temporal de la Assembly, retenido durante 24 horas de forma predeterminada. Agrega un Robot de almacenamiento para conservarlo de forma permanente en un destino que controles. ### ¿Por qué usar `fit` en lugar de `fillcrop`? `fit` conserva la imagen completa y la ajusta al recuadro solicitado. `fillcrop` llena dimensiones exactas recortando, lo que requiere una decisión de composición intencional. ### ¿Qué debo guardar después de que finalice la Assembly? Guarda el ID de la Assembly, tu propio ID de trabajo o de recurso, los metadatos del resultado seleccionado y la ubicación de almacenamiento persistente, y un estado final saneado. No expongas la respuesta completa sin procesar a los clientes de forma predeterminada. ## Crea el flujo de trabajo Pasa del concepto a una Assembly probada con documentación de Robots y demos funcionales. ### Robots relevantes * [/upload/handle](/es/docs/robots/upload-handle.md) * [/image/resize](/es/docs/robots/image-resize.md) * [Crea una Auth Key](/c/credentials/) * [Lee la documentación del SDK de Node](/es/docs/sdks/node-sdk.md) * [Almacena los resultados de forma permanente](/es/docs/getting-started/saving-conversion-results.md) * [Lee la documentación de la API](/es/docs.md) * [Explora demos funcionales EN (English)](/demos.md) * [Crea un Workspace gratuito](/c/signup/) Subidas e integración frontend ## Continúa con guías relacionadas * [Flujos de trabajo de procesamiento multimedia personalizables con Transloadit](/es/guides/customizable-media-processing-workflows.md)\ Diseña un Template reutilizable con validación, variables, derivados paralelos, almacenamiento seguro y finalización observable. * [Guía de API de subida de archivos: arquitectura, seguridad y selección de proveedores](/es/guides/file-upload-api-guide.md)\ Elige e implementa una API de subida comparando arquitectura, reanudación, transferencia directa a la nube, seguridad, límites de almacenamiento y proveedores. * [Subidas de archivos con React y Uppy: reanudación, vistas previas, validación y procesamiento](/es/guides/react-file-uploads-with-uppy.md)\ Crea una subida React con Uppy: vista previa, validación, progreso accesible, cancelación, transferencia reanudable y traspaso del procesamiento a Transloadit. * [Subidas de archivos, optimización de imágenes y tu propio bucket S3](/es/guides/file-uploads-image-optimization-s3.md)\ Combina subidas reanudables por navegador, optimización de imágenes, almacenamiento en Amazon S3 propio y entrega bajo demanda sin servicios multimedia aparte. * [Cómo aceptar subidas grandes pese a una conexión interrumpida](/es/guides/resumable-uploads-for-large-files.md)\ Acepta subidas de varios gigabytes mediante el protocolo tus, reanúdalas tras perder la conexión y mantén viva la Assembly hasta terminarlas. * [Subidas seguras de archivos en Next.js con Uppy y Templates firmados de Transloadit](/es/guides/secure-file-uploads-nextjs-uppy.md)\ Crea una subida segura con Next.js App Router y Uppy: firma en servidor, Template bloqueado, validación autoritativa, transferencia reanudable, fin asíncrono.