Subidas, imágenes optimizadas, video codificado y entrega vía tus

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.

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
Confirma que el destino implementa el protocolo tus y define qué hace tras una subida completada.
2
Crea credenciales de Template HTTP para los encabezados estáticos del destino y guarda Templates separados de subida, imagen y video.
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
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.

Subidas de archivos, optimización de imágenes y codificación de video a un servidor tus