Plataformas e integraciones # Subidas de archivos, optimización de imágenes y codificación de video a un servidor tus Recibe archivos, optimiza imágenes o codifica videos con Transloadit y entrega el resultado seleccionado a un servidor compatible con el protocolo tus. Publicado el 1 de septiembre de 2026 ## Conclusiones clave * Usa `/upload/handle` seguido de `/tus/store` para retransmitir sin cambios un archivo subido a un endpoint compatible con el protocolo tus. * Ejecuta `/image/optimize` antes de `/tus/store` cuando el sistema receptor deba recibir una imagen optimizada. * Ejecuta `/video/encode` con un ajuste preestablecido probado antes de `/tus/store` cuando el destino deba recibir una variante de reproducción. El protocolo tus permite subidas reanudables; no es un producto de almacenamiento de objetos. En estos flujos de trabajo, un cliente primero sube archivos a una Assembly de Transloadit, unos Steps opcionales de imagen o video crean la salida deseada, y `/tus/store` inicia una subida tus saliente independiente hacia el endpoint de destino configurado. Esa distinción es importante para las credenciales, los reintentos, las URL de resultado y la conciliación de la aplicación. ## En esta guía 1. [Modela el protocolo tus como un límite de entrega](#file-uploads-image-optimization-video-encoding-tus-server-section-1) 2. [Retransmite un archivo subido sin transformarlo](#file-uploads-image-optimization-video-encoding-tus-server-section-2) 3. [Optimiza una imagen antes de la entrega mediante tus](#file-uploads-image-optimization-video-encoding-tus-server-section-3) 4. [Codifica un video antes de la entrega mediante tus](#file-uploads-image-optimization-video-encoding-tus-server-section-4) 5. [Elige encabezados, metadatos y URL reportadas de forma deliberada](#file-uploads-image-optimization-video-encoding-tus-server-section-5) 6. [Prueba los reintentos y concilia ambos sistemas](#file-uploads-image-optimization-video-encoding-tus-server-section-6) ## Lo más importante * Guarda los encabezados de autorización del destino en credenciales de Template HTTP en lugar de en Instructions visibles para el navegador. * Concilia la Assembly y la aplicación receptora antes de marcar un recurso como listo en el estado del producto. ## Modela el protocolo tus como un límite de entrega Una subida a Transloadit y una exportación con `/tus/store` son dos transferencias distintas. La primera lleva los bytes del cliente a una Assembly. La Assembly puede dejar el archivo sin cambios o crear un derivado de imagen o video. La segunda transferencia envía el resultado seleccionado desde Transloadit a tu endpoint tus. Esta arquitectura es útil cuando la plataforma receptora ya expone tus, pero de todos modos quieres un procesamiento gestionado antes de la entrega. El destino controla todo lo que ocurre después de la finalización del protocolo. Su aplicación decide si mueve la subida a almacenamiento duradero, crea un registro de recurso, la analiza, la publica o la rechaza más tarde. Registra tanto el ID de la Assembly como la identidad estable del receptor. No asumas que la URL de subida del protocolo tus es un identificador de objeto permanente o una URL de entrega legible a menos que el receptor lo prometa explícitamente. ### Transferencia entrante Cliente → Assembly de Transloadit, usando el método de subida seleccionado por el SDK o la integración. ### Transferencia saliente Resultado de la Assembly → `/tus/store` → el endpoint de destino compatible con tus configurado. ### Límite de durabilidad La persistencia y la publicación del lado receptor quedan fuera del protocolo tus y del flujo de trabajo de Transloadit. ## Retransmite un archivo subido sin transformarlo Usa el Template solo de subida cuando el destino deba recibir el archivo original aceptado por la Assembly. `/upload/handle` expone esa entrada como `:original`, y `/tus/store` la selecciona mediante `use`. El `endpoint` requerido debe ser la URL de destino que crea subidas tus, no la URL de un objeto existente ni la de una página de descarga del navegador. El ejemplo hace referencia a credenciales de Template HTTP para los encabezados estáticos del destino. Mantén `allow_steps_override` en false cuando los clientes no deban reemplazar el endpoint, quitar la autenticación o redirigir un archivo. Si el receptor necesita contexto del inquilino o del recurso, prefiere metadatos no secretos con un endpoint autorizado por el servidor o una credencial de alcance limitado, y valida ese contexto de nuevo en el lado receptor. Retransmitir un archivo subido a un endpoint tus ``` { "allow_steps_override": false, "steps": { ":original": { "robot": "/upload/handle" }, "delivered": { "use": ":original", "robot": "/tus/store", "endpoint": "https://uploads.example.com/files/", "credentials": "my_tus_http_credentials" } } } ``` ## Optimiza una imagen antes de la entrega mediante tus Para un contrato exclusivo de imagen, conecta `/image/optimize` con `:original` y entrega el Step `optimized`. El ejemplo conserva los metadatos y usa optimización PNG sin pérdida (`lossy: false`); esa marca no afecta a la optimización de JPEG, GIF, WebP ni SVG. Evalúa si la eliminación de metadatos o la optimización PNG con pérdida es apropiada antes de cambiar esos ajustes, ya que cualquiera de las dos puede alterar información que la aplicación receptora espera. El `priority: "compression-ratio"` no predeterminado del ejemplo favorece una salida más pequeña sobre la velocidad de procesamiento; `conversion-speed`, el valor predeterminado, hace el intercambio opuesto. Esta receta no cambia el tamaño ni el formato. Agrega `/image/resize` antes de la optimización cuando el receptor requiera dimensiones fijas o un formato específico. Almacena o entrega el original por separado cuando la recuperación y el reprocesamiento futuro importen. Un tipo de imagen no compatible puede pasar por `/image/optimize` sin cambios, así que usa una validación explícita cuando el receptor requiera un formato restringido. Optimizar una imagen y entregarla mediante tus ``` { "allow_steps_override": false, "steps": { ":original": { "robot": "/upload/handle" }, "optimized": { "use": ":original", "robot": "/image/optimize", "priority": "compression-ratio", "preserve_meta_data": true, "lossy": false }, "delivered": { "use": "optimized", "robot": "/tus/store", "endpoint": "https://uploads.example.com/files/", "credentials": "my_tus_http_credentials" } } } ``` ## Codifica un video antes de la entrega mediante tus Para un contrato exclusivo de video, conecta `/video/encode` con la subida y entrega a `/tus/store` el Step codificado. `web/mp4/720p` es un punto de partida concreto de MP4 con resolución definida, no una recomendación universal de ajuste preestablecido. Prueba las dimensiones de origen, la frecuencia de fotogramas, el audio, los subtítulos, la compatibilidad de reproducción, el tiempo de procesamiento y el costo frente a los requisitos reales del receptor. La codificación de video y la transferencia tus saliente pueden extenderse más allá de una solicitud de la aplicación. Usa el Assembly Status o una devolución de llamada de finalización verificada, y luego comprueba el propio estado de finalización de la aplicación receptora. Almacena o retransmite el origen por separado cuando se necesite para una recodificación de mayor calidad, auditoría, recuperación o migración. Codificar un MP4 y entregarlo mediante tus ``` { "allow_steps_override": false, "steps": { ":original": { "robot": "/upload/handle" }, "encoded": { "use": ":original", "robot": "/video/encode", "preset": "web/mp4/720p" }, "delivered": { "use": "encoded", "robot": "/tus/store", "endpoint": "https://uploads.example.com/files/", "credentials": "my_tus_http_credentials" } } } ``` ## Elige encabezados, metadatos y URL reportadas de forma deliberada Usa credenciales de Template HTTP para los encabezados de autorización estáticos. El Robot también acepta `headers` dinámicos, pero firmar las Instructions solo garantiza su integridad, nunca su confidencialidad: un navegador puede leer todo lo que envía. Por lo tanto, los secretos dinámicos nunca deben aparecer en Instructions visibles para el navegador. Consérvalos en credenciales de Template, o envía la Assembly de servidor a servidor para que los valores nunca lleguen al navegador. Los metadatos del destino son un mapa aparte: el Robot reemplaza los valores de `filename`, `basename` y `extension` proporcionados por el llamador con información del archivo procesado, mientras que otras claves pasan tal como se definieron. Mantén los metadatos pequeños, sin secretos y alineados con los campos que el receptor realmente valida, en lugar de tratarlos como autorización. Sin un `url_template`, el Robot informa la URL de subida devuelta por el destino. Un `ssl_url_template` omitido puede reutilizar esa URL solo cuando empieza con HTTPS. Las plantillas cambian la presentación del resultado; no cambian los permisos del receptor, no convierten una URL de subida en un endpoint de descarga ni garantizan estabilidad a largo plazo. Registra el identificador canónico de recurso del receptor después de que procese la subida. ## Prueba los reintentos y concilia ambos sistemas Prueba la autorización expirada, el rechazo del endpoint, las transferencias interrumpidas, los reintentos, las entregas duplicadas, los tiempos de espera agotados del receptor y los fallos de procesamiento del lado del receptor. Haz que el manejo de la finalización sea idempotente, porque una notificación de Assembly o un evento posterior se puede entregar más de una vez. El sistema receptor debería rechazar el contexto entre inquilinos incluso cuando un cliente haya logrado alterar metadatos no secretos. Registra el ID de la Assembly, la clase de endpoint de destino y el ID de recurso del receptor sin registrar los encabezados de autorización. La ventana de aproximadamente 24 horas se aplica solo a la copia temporal del resultado de la Assembly de Transloadit, así que concilia el sistema receptor antes de que esa copia expire. Trata el recurso del producto como listo solo después de que se haya entregado el resultado esperado de la Assembly y el receptor confirme el estado duradero o publicado previsto. Esa conciliación explícita es lo que convierte una entrega de protocolo exitosa en un flujo de trabajo de aplicación confiable. ## Detalles técnicos que conviene conocer * `/tus/store` exporta los archivos seleccionados por `use` a la URL requerida en su parámetro `endpoint`. * El Robot acepta credenciales de Template HTTP para que los encabezados de autorización estáticos puedan enviarse al destino sin aparecer en Instructions. * Los `headers` dinámicos opcionales se envían al destino, pero los secretos visibles para el navegador quedarían expuestos y deberían evitarse. * El Robot siempre establece las claves de metadatos `filename`, `basename` y `extension` a partir del archivo procesado, sobrescribiendo los valores suministrados por el llamador para esas claves; las demás claves de `metadata` pasan tal como se definieron. * Cuando `url_template` está ausente, el resultado usa la URL de subida proporcionada por el servidor tus de destino. * Cuando `ssl_url_template` está ausente, la URL de subida de destino completa el campo `ssl_url` del resultado solo cuando esa URL comienza con HTTPS. * `/image/optimize` deja pasar sin cambios los tipos de imagen no compatibles, así que valida las entradas cuando el destino requiera un resultado optimizado. * `/video/encode` acepta ajustes preestablecidos como `web/mp4/720p`, y cada ajuste preestablecido debe probarse frente a los requisitos de reproducción del destino. * Transloadit normalmente elimina los archivos de resultado temporales de la Assembly alrededor de 24 horas después del procesamiento, mientras que el almacenamiento actual los conserva durante al menos 24 horas sin importar la configuración de retención personalizada; la retención duradera corresponde al destino tus receptor. ## Un enfoque práctico 1. 1\ Confirma que el destino implementa el protocolo tus y define qué hace tras una subida completada. 2. 2\ Crea credenciales de Template HTTP para los encabezados estáticos del destino y guarda Templates separados de subida, imagen y video. 3. 3\ Prueba la autenticación, la recuperación de transferencias interrumpidas, la entrega duplicada, el comportamiento de la URL de resultado y la persistencia del lado del receptor. 4. 4\ Registra el ID de la Assembly junto con la identidad estable de recurso del sistema receptor y concilia la finalización de forma idempotente. Un flujo de trabajo multimedia de cuatro etapas ## Cuándo resulta útil Transloadit Usa `/tus/store` cuando un destino existente acepta subidas mediante el protocolo tus y una Assembly de Transloadit debería entregarle un resultado original o procesado. Usa un Robot de almacenamiento específico del proveedor cuando Transloadit debería entender una API de bucket y ajustes de acceso propios del almacenamiento. ## Límite de la arquitectura `/tus/store` entrega un resultado seleccionado de la Assembly a un endpoint compatible con el protocolo tus. El protocolo tus define la transferencia reanudable, no la durabilidad, el modelo de autorización, la retención, el estado de publicación o la URL de descarga final del destino; esos contratos son responsabilidad del servicio receptor y de tu aplicación. ## Preguntas frecuentes ### ¿El navegador sube los archivos directamente a mi endpoint del protocolo tus? No. En estas recetas, el navegador sube los archivos a una Assembly de Transloadit. Después del procesamiento, `/tus/store` actúa como cliente del protocolo tus y sube el resultado seleccionado a tu endpoint configurado. Las dos transferencias tienen URL, credenciales, progreso y límites de reintento independientes. ### ¿Una subida exitosa mediante tus garantiza un almacenamiento duradero? No. El protocolo tus estandariza la transferencia reanudable. El servidor receptor decide si la subida completada es duradera, cuánto tiempo se conserva, quién puede acceder a ella y si la URL de subida también es una URL de descarga. Concilia un registro de recursos del lado receptor en lugar de inferir esas propiedades a partir de la sola finalización del protocolo. ### ¿Cómo debería autenticar el destino a Transloadit? Usa el tipo de credencial HTTP para encabezados de autorización estáticos y haz referencia al nombre de la credencial desde `/tus/store`. Los `headers` dinámicos se admiten para casos que no pueden usar credenciales estáticas, pero nunca coloques encabezados sensibles en las Instructions de la Assembly visibles para el navegador. ### ¿Puede un único Template gestionar archivos, imágenes y videos? Usa Templates independientes cuando las políticas de validación y de fallos difieran. Un Template deliberadamente mixto puede filtrar y bifurcar según el tipo de medio detectado, y luego darle a cada Step `/tus/store` solo el resultado que crea su bifurcación. ### ¿Qué URL aparece en el resultado de la Assembly? De forma predeterminada, el Robot usa la URL de subida devuelta por el servidor tus. `url_template` y `ssl_url_template` pueden dar forma a las URL reportadas, pero no demuestran que la URL sea de lectura pública ni que permanezca estable. Verifica de forma independiente el contrato de URL del receptor. ## Crea el flujo de trabajo Pasa del concepto a una Assembly probada con documentación de Robots y demos funcionales. ### Robots relevantes * [/tus/store EN (English)](/docs/robots/tus-store.md) * [Exporta archivos a un servidor tus EN (English)](/docs/robots/tus-store.md) * [Recibe subidas de la Assembly](/es/docs/robots/upload-handle.md) * [Optimiza imágenes](/es/docs/robots/image-optimize.md) * [Codifica videos](/es/docs/robots/video-encode.md) * [Protege los encabezados del destino](/es/docs/topics/template-credentials.md) * [Lee la documentación de la API](/es/docs.md) * [Explora demos funcionales EN (English)](/demos.md) * [Crea un Workspace gratuito](/c/signup/) Plataformas e integraciones ## 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 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 de archivos, optimización de imágenes y tu propio bucket S3](/es/guides/file-uploads-image-optimization-s3.md)\ Combina subidas reanudables, optimización de imagen, codificación de video, almacenamiento propio en Amazon S3 y entrega bajo demanda sin servicios aparte. * [Elige almacenamiento externo para un flujo de trabajo multimedia](/es/guides/external-storage-media-workflows.md)\ Elige almacenamiento externo para flujos de Transloadit: modelos, credenciales, controles de acceso, comportamiento de URL y necesidades de importación masiva. * [Procesa imágenes de Google Cloud Storage y vuelve a escribirlas de forma segura](/es/guides/google-storage-image-processing-workflow.md)\ Importa imágenes por lotes desde Google Cloud Storage, crea derivados WebP acotados y expórtalos a un prefijo controlado independiente. * [Normaliza documentos de Supabase Storage a PDF](/es/guides/supabase-document-processing-workflow.md)\ Importa un lote controlado de documentos de Supabase Storage, normaliza los archivos de oficina compatibles a PDF y expórtalos a un prefijo separado.