Subidas e integración frontend # Subidas de archivos, optimización de imágenes y tu propio bucket S3 Combina subidas reanudables por navegador, optimización de imágenes, almacenamiento en Amazon S3 propio y entrega bajo demanda sin servicios multimedia aparte. Publicado el 28 de agosto de 2026 ## Conclusiones clave * Usa una Assembly para recibir una subida, validarla, crear salidas fijas y exportar los originales o derivados seleccionados a S3. * Usa Smart CDN para importar un objeto existente de S3 mediante un Template guardado, transformarlo ante un fallo de caché y almacenar en caché el resultado entregado. * Mantén las credenciales de AWS en credenciales de Template con permisos acotados y genera la autorización de subida o de Smart CDN en un servidor de confianza. Una solicitud de «subida de archivos, optimización de imágenes y nuestro propio bucket de S3» esconde dos momentos de procesamiento distintos. Algunas salidas deben validarse, aprobarse y almacenarse antes de la publicación. Otros tamaños o formatos resultan más económicos de crear solo cuando un navegador los solicita. Transloadit admite ambas rutas, pero tienen límites distintos de almacenamiento, latencia, caché y seguridad. ## En esta guía 1. [Separa el trabajo en el momento de la subida del trabajo en el momento de la solicitud](#file-uploads-image-optimization-s3-section-1) 2. [Recibe, valida, optimiza y exporta la subida](#file-uploads-image-optimization-s3-section-2) 3. [Transforma un original de S3 bajo demanda mediante Smart CDN](#file-uploads-image-optimization-s3-section-3) 4. [Decide qué almacenar de forma permanente y qué generar bajo demanda](#file-uploads-image-optimization-s3-section-4) 5. [Protege la aplicación, el bucket y la superficie de transformación](#file-uploads-image-optimization-s3-section-5) 6. [Compara esto con un pipeline nativo de AWS de forma justa](#file-uploads-image-optimization-s3-section-6) ## Lo más importante * Trata S3 como el sistema de registro persistente, no como prueba de que los bytes del archivo nunca pasan por la infraestructura de procesamiento y caché de Transloadit. * Preprocesa las salidas que deban existir antes de la publicación; usa variantes limitadas bajo demanda cuando la demanda de derivados sea impredecible. * Almacena originales, derivados fijos o ambos según los requisitos de recuperación y migración de la aplicación. ## Separa el trabajo en el momento de la subida del trabajo en el momento de la solicitud Empieza con dos rutas en lugar de un vago «pipeline de optimización». En la ruta del momento de la subida, un navegador envía un archivo mediante Uppy y el protocolo tus a una Assembly de Transloadit. El Template guardado valida el archivo observado, crea las salidas que deban existir de inmediato y exporta los archivos seleccionados a S3. La aplicación almacena el ID de la Assembly y la identidad persistente del objeto en S3 junto con su registro del recurso. En la ruta del momento de la solicitud, un navegador solicita una URL de Smart CDN. La URL identifica un Template guardado y una ruta de entrada en S3. En caso de fallo de caché, Transloadit importa ese objeto, aplica el Template con las Assembly Variables permitidas y entrega un resultado a través de `/file/serve`. La capa de entrega almacena en caché la respuesta; una solicitud en caliente puede reutilizar el derivado sin volver a ejecutar la transformación. ### Ruta del momento de la subida Navegador → Uppy/tus → Assembly → validación y transformaciones fijas → S3 del cliente. ### Ruta del momento de la solicitud Navegador → URL de Smart CDN → fallo de caché → importación desde S3 y transformación → caché de borde → navegador. ### Límite de propiedad El S3 del cliente aloja los objetos persistentes de la aplicación; los archivos temporales de procesamiento y los derivados en caché tienen contratos de retención independientes. ## Recibe, valida, optimiza y exporta la subida Usa un Template de subida guardado para limitar lo que el código del navegador puede solicitar. `/upload/handle` recibe el archivo, `/file/filter` puede rechazar archivos cuyas propiedades detectadas no cumplan la política, y `/image/resize` crea un derivado fijo. `/s3/store` exporta entonces exactamente los Steps indicados por su valor `use`. Apúntalo solo a `optimized` para guardar el derivado, solo a `accepted_images` para guardar el original aceptado, o a ambos para conservar los dos objetos. Uppy es la capa de subida del navegador, no el límite de autorización. Permite que el plugin de Transloadit solicite al servidor de la aplicación parámetros de Assembly firmados y de corta duración. Mantén `allow_steps_override` deshabilitado cuando el navegador no deba reemplazar los Steps guardados ni seleccionar otro destino. El ejemplo establece deliberadamente `acl: "private"` en `/s3/store`, porque el valor predeterminado del Robot es `public-read`. Reemplaza el `bucket_region` de ejemplo por la región de AWS del bucket; establecerlo evita un permiso `GetBucketLocation` y la búsqueda adicional. Considera la subida completa para el producto solo después de que la aplicación haya conciliado el resultado de la Assembly con las claves persistentes de S3. Exportar el original aceptado y un derivado WebP fijo a S3 ``` { "allow_steps_override": false, "steps": { ":original": { "robot": "/upload/handle" }, "accepted_images": { "use": ":original", "robot": "/file/filter", "accepts": [["${file.mime}", "regex", "^(image/jpeg|image/png|image/gif|image/webp|image/avif)$"]], "error_on_decline": true }, "optimized": { "use": "accepted_images", "robot": "/image/resize", "resize_strategy": "fit", "width": 1600, "height": 1600, "format": "webp" }, "stored": { "use": ["accepted_images", "optimized"], "robot": "/s3/store", "credentials": "my_s3_credentials", "bucket_region": "us-east-1", "acl": "private", "path": "images/${file.id}/${file.url_name}" } } } ``` ## Transforma un original de S3 bajo demanda mediante Smart CDN Una integración con Smart CDN también comienza con un Template guardado. `/s3/import` resuelve la ruta de entrada usando credenciales de Template acotadas, `/image/resize` lee el valor `${fields.w}` proporcionado por la URL y el valor `${browser.wanted_image_format}` negociado por la solicitud, y `/file/serve` selecciona la respuesta. Transloadit normalmente deriva el formato a partir de los pesos de calidad `Accept` de la solicitud. Un edge de Smart CDN puede, en su lugar, establecer un encabezado `x-tl-image-format` de confianza y ya normalizado, que se resuelve al mismo valor `avif`, `webp` o `jpg` sin volver a analizar `Accept`. Una URL como `https://my-workspace.tlcdn.com/responsive-image/images/a8d3eeeb67479f11f8b091b04f6181ad/canoe.jpg?w=640` proporciona `images/a8d3eeeb67479f11f8b091b04f6181ad/canoe.jpg` como el `${fields.input}` implícito (la ruta después del nombre del Template, sin barra inicial) y `640` como `${fields.w}`. Esa entrada coincide exactamente con la clave escrita por el ejemplo de subida, por lo que `/s3/import` lee directamente el objeto almacenado. Conserva el prefijo `images/` completo en la URL; no lo añadas de nuevo en el Template. Los valores de la consulta de Smart CDN llegan como cadenas de texto, por lo que la lista de anchos permitidos se compara con los literales de cadena `"320"` y `"640"`; un ancho no coincidente recurre a 1280. No interpoles una ruta, un ancho, una calidad o un formato sin restricciones solo porque puedan llegar como un campo. Restringe la credencial de S3 a un prefijo previsto, haz que la aplicación de confianza busque la clave exportada en su registro del recurso y firma una URL que contenga esa clave exacta. Sustituye el `bucket_region` de ejemplo por la región de AWS del bucket; establecerlo evita un permiso `GetBucketLocation` y la búsqueda adicional. Valida o asigna los valores de transformación en el Template. Las expresiones complejas de Dynamic Evaluation invocan `/script/run` y generan sus propios costos. La expresión de formato asigna el valor de reserva `jpg` a `null`, de modo que las solicitudes sin preferencia por un formato moderno conservan el formato original en lugar de aplanar la transparencia o la animación mediante una recodificación innecesaria. Consulta la entrada `${browser.wanted_image_format}` en la [referencia de Assembly Variables](/es/docs/topics/assembly-variables.md). Mide la primera transformación sin caché por separado de la entrega en caché posterior. Importar un original de S3 usando credenciales con permisos restringidos a un prefijo y una clave firmada y validada por el servidor ``` { "steps": { "imported": { "robot": "/s3/import", "credentials": "my_s3_credentials", "bucket_region": "us-east-1", "path": "${fields.input}" }, "optimized": { "use": "imported", "robot": "/image/resize", "resize_strategy": "fit", "width": "${fields.w === '320' ? 320 : fields.w === '640' ? 640 : 1280}", "format": "${browser.wanted_image_format === 'jpg' ? null : browser.wanted_image_format}" }, "served": { "use": "optimized", "robot": "/file/serve", "cache_duration": 604800 } } } ``` ## Decide qué almacenar de forma permanente y qué generar bajo demanda Conservar un original en S3 proporciona una fuente estable para reprocesar, pero no obliga a almacenar cada variante responsiva. Exporta las salidas canónicas que el producto necesite independientemente de una caché: un máster aprobado, una imagen de listado de marketplace, un recurso de impresión o un derivado inmutable de una versión publicada. Deja que Smart CDN cree variantes de presentación acotadas cuyas dimensiones dependan del dispositivo o del diseño solicitante. Por el contrario, no dependas solo de una ruta bajo demanda cuando la primera solicitud no pueda tolerar la latencia de procesamiento, un editor deba aprobar los píxeles exactos, o los sistemas posteriores requieran un objeto persistente antes de la publicación. En ese caso, crea y exporta el derivado en la Assembly del momento de la subida. La misma aplicación puede usar ambos enfoques para distintas clases de salida sin cambiar quién conserva de forma persistente la fuente. ### Originales persistentes Conserva las fuentes necesarias para futuras transformaciones, recuperación, auditoría o migración. ### Derivados fijos Almacena las salidas que deben revisarse, ser referenciadas por otros sistemas o estar disponibles sin una transformación en frío. ### Derivados bajo demanda Almacena en caché variantes de presentación seguras cuyas combinaciones son limitadas pero difíciles de predecir antes de que un usuario las solicite. ## Protege la aplicación, el bucket y la superficie de transformación Crea credenciales de Template independientes con privilegios mínimos cuando las exportaciones de subida y las importaciones de Smart CDN necesiten acciones o prefijos de AWS distintos. Mantén las claves de AWS sin procesar, el Auth Secret de Transloadit y las Instructions sin restricciones fuera de los paquetes del navegador. El servidor de la aplicación debe autorizar al usuario, seleccionar el Template y emitir únicamente los parámetros de subida de corta duración o la URL firmada de Smart CDN adecuados para ese recurso. Una subida exitosa o una firma válida no es una aprobación de publicación. Valida el tipo MIME y el tamaño detectados en la Assembly, asocia los callbacks de forma idempotente con el inquilino y la Assembly esperados, y expón un resultado solo después de que el objeto persistente y el registro de la aplicación concuerden. Para Smart CDN, diseña juntos el versionado de fuentes, el vencimiento de la URL, la duración de la caché y la eliminación, para que reemplazar una clave de S3 no pueda dejar activa una dirección de derivado no deseada. ## Compara esto con un pipeline nativo de AWS de forma justa Un diseño nativo puede subir a través de una URL prefirmada de S3, reaccionar a eventos de creación de objetos, procesar con Lambda u otro servicio de cómputo, almacenar derivados y entregarlos a través de una CDN. Eso puede encajar bien cuando la carga de trabajo se mantiene dentro de los límites de tiempo de ejecución admitidos y el equipo quiere operar por su cuenta la autorización, los reintentos, las colas, los códecs, la concurrencia, la observabilidad y la recuperación ante fallos. Compara rutas de producción completas en lugar de un solo redimensionamiento exitoso. Prueba subidas interrumpidas, fuentes grandes, imágenes con formato incorrecto, orientación y color, eventos duplicados, exportaciones parciales, picos de concurrencia, transformaciones en frío, invalidación de caché, latencia regional y eliminación. Incluye el tiempo de ingeniería y operaciones junto con los costos de subida, procesamiento, almacenamiento, solicitudes y salida de datos. La decisión relevante es qué responsabilidades operativas quiere asumir el equipo. ## Detalles técnicos que conviene conocer * El plugin de Transloadit para Uppy crea una Assembly y sube los archivos a su endpoint del protocolo tus, mientras que el código de la aplicación puede solicitar parámetros de Assembly firmados a un back end confiable. * Un Template de Assembly puede conectar `/upload/handle`, Steps de validación o transformación, y `/s3/store`; las relaciones `use` determinan si se exporta el original, los derivados o ambos. * Las credenciales de Template almacenan el acceso a AWS por separado de las Assembly Instructions, y la política de IAM de S3 debe conceder solo las rutas del bucket y las operaciones que cada Template necesite. * Una URL de Smart CDN identifica un Workspace, un Template, una ruta de entrada y campos de URL opcionales. La ruta de entrada está disponible para el Template como `${fields.input}`. En caso de fallo de caché, el Template se ejecuta y `/file/serve` entrega la respuesta que la capa de entrega almacena en caché. * Un Template de Smart CDN puede usar `/s3/import` para leer un objeto del S3 propiedad del cliente, `/image/resize` para transformarlo y `/file/serve` para devolver el derivado seleccionado. * En las solicitudes de Smart CDN, los parámetros de consulta de la URL completan `${fields.*}`, mientras que la ruta después del nombre del Template se convierte en el valor implícito `${fields.input}`. Esto difiere de los campos de formulario del momento de la subida y de la clave `fields` de la Assembly. El Template decide qué valores lee, pero cada uno necesita igualmente validación, mapeo o autorización mediante una URL firmada. * El almacenamiento temporal de resultados de Transloadit no es almacenamiento permanente de la aplicación. Los resultados se conservan durante al menos 24 horas independientemente de la configuración; el almacenamiento actual en R2 no admite su eliminación antes de ese plazo. Los flujos de trabajo de producción deben exportar todo objeto que deba persistir. * Un derivado en caché de Smart CDN es independiente del original persistente en S3. El reemplazo de la fuente, el versionado de URL, el vencimiento de la firma y la duración de la caché deben diseñarse juntos. ## Un enfoque práctico 1. 1\ Traza las rutas de subida, procesamiento, almacenamiento y entrega, incluyendo quién posee cada objeto persistente y cada URL pública. 2. 2\ Crea credenciales de Template con privilegios mínimos y Templates guardados para el trabajo en el momento de la subida y bajo demanda. 3. 3\ Prueba las exportaciones fijas, los fallos de caché en frío de Smart CDN, los aciertos de caché en caliente, los parámetros inválidos, las fuentes reemplazadas y los orígenes no disponibles. 4. 4\ Registra los ID de las Assemblies y las versiones estables de los objetos de S3 en la aplicación, y luego supervisa por separado los costos de procesamiento, exportación, caché y entrega. Un flujo de trabajo multimedia de cuatro etapas ## Cuándo resulta útil Transloadit Usa Transloadit cuando un producto necesite subidas mediante Uppy y el protocolo tus, flujos de trabajo de imágenes asíncronos, exportaciones a su propio bucket de S3 y variantes opcionales controladas por URL a través de Smart CDN. Usa solo las partes que la aplicación necesite: una Assembly puede preprocesar y exportar recursos fijos, mientras que un Template de Smart CDN puede importar un original desde S3 y crear un derivado acotado bajo demanda. ## Límite de la arquitectura Tu aplicación es responsable de la autorización de usuarios, los registros de recursos, la política de publicación y las copias persistentes en S3. Transloadit recibe o importa archivos, retiene temporalmente los datos mientras los procesa, ejecuta el flujo de trabajo guardado, exporta los resultados seleccionados y puede almacenar en caché derivados de Smart CDN. Por lo tanto, un almacenamiento propiedad del cliente no significa que los bytes permanezcan exclusivamente dentro de la cuenta de AWS del cliente. ## Preguntas frecuentes ### ¿Usar mi propio bucket de S3 mantiene cada byte dentro de mi cuenta de AWS? No. S3 puede seguir siendo el sistema de registro persistente, pero las subidas, los originales importados, los resultados temporales y los derivados de Smart CDN pasan por la infraestructura de Transloadit según el flujo de trabajo configurado. Los resultados temporales se conservan durante al menos 24 horas independientemente de la configuración, y el almacenamiento actual en R2 no permite eliminarlos antes. La retención del Assembly Status JSON se configura por separado, con opciones que van desde No Save hasta 90 días; 90 días es el valor predeterminado. Conservar el Status JSON durante 90 días no convierte los archivos de resultados temporales en almacenamiento persistente. Smart CDN almacena en caché los resultados servidos por separado. ### ¿Debo almacenar la imagen original, los derivados optimizados o ambos? Exporta el original cuando se necesite para reprocesamiento, auditoría o migración de proveedor. Exporta derivados fijos cuando deban existir antes de la publicación o revisarse. Puedes exportar ambos dando a `/s3/store` los dos Steps como su entrada `use`. ### ¿Es Smart CDN un sistema de procesamiento independiente de las Assemblies? No. Una Assembly del momento de la subida y una solicitud de Smart CDN usan el mismo modelo de ejecución de Template y Robot, aunque cada ruta define su propio Template. La ruta de la subida se ejecuta cuando llegan los bytes y puede exportar resultados persistentes. La ruta de Smart CDN ejecuta su Template ante un fallo de caché y entrega un resultado seleccionado mediante `/file/serve`. ### ¿Cuándo debo preprocesar en lugar de transformar bajo demanda? Preprocesa los recursos que necesiten aprobación, disponibilidad determinista, varios resultados persistentes o una latencia predecible en la primera visualización. Transforma bajo demanda cuando los tamaños solicitados sean difíciles de predecir y un conjunto acotado de variables de URL pueda expresar las variantes seguras. Muchas aplicaciones preprocesan una imagen canónica y crean tamaños de presentación bajo demanda. ### ¿Cómo debe recibir Transloadit el acceso a un bucket privado de S3? Almacena las credenciales de AWS como credenciales de Template con privilegios mínimos, haz referencia a su nombre desde un Template guardado e impide que los navegadores proporcionen Assembly Instructions o destinos de almacenamiento arbitrarios. Firma los parámetros de subida y las URL protegidas de Smart CDN en un servidor de confianza. ### ¿Tengo que usar Transloadit para usar Uppy? No. Uppy es software de subida de código abierto y puede usar muchos back ends. El plugin mantenido de Transloadit es la integración directa cuando las subidas deben crear una Assembly, usar transferencia mediante el protocolo tus e informar el progreso o los resultados del procesamiento. ## Crea el flujo de trabajo Pasa del concepto a una Assembly probada con documentación de Robots y demos funcionales. * [Explora las subidas de archivos administradas](/es/services/handling-uploads.md) * [Explora Smart CDN](/es/services/content-delivery.md) * [Conecta un bucket de Amazon S3](/es/docs/faq/how-to-set-up-an-amazon-s3-bucket.md) * [Protege las credenciales de almacenamiento](/es/docs/topics/template-credentials.md) * [Valida campos con Dynamic Evaluation](/es/docs/topics/dynamic-evaluation.md) * [Consulta las Assembly Variables](/es/docs/topics/assembly-variables.md) * [Comprende la retención temporal de archivos](/es/docs/faq/temporary-purge-sooner.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 * [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. * [Cómo servir imágenes responsivas desde una sola URL](/es/guides/serve-responsive-images-from-one-url.md)\ Genera cada tamaño de imagen desde una URL canónica, almacena los resultados en caché perimetral y mantén estable el costo de codificación al crecer el tráfico. * [Las mejores API de imágenes para cargas de trabajo de producción](/es/guides/best-image-apis-2026.md)\ Compara API de imágenes líderes en 2026 por su rol en el ciclo de vida: subida, flujos, transformación de URL, almacenamiento, entrega y gestión de recursos. * [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. * [Mejores bibliotecas JavaScript para subir archivos: Uppy vs FilePond vs Dropzone](/es/guides/best-javascript-file-upload-libraries.md)\ Compara Uppy, FilePond y Dropzone según el protocolo de transferencia, el modelo de interfaz, la recuperación, la integración y el mantenimiento a largo plazo.