Migra de Cloudinary a Transloadit

Cloudinary soporta ajustes preestablecidos de subida⁠, URL de transformación⁠ y una biblioteca de activos⁠. Transloadit centra el procesamiento en torno a Assembly Instructions: flujos de trabajo explícitos que ejecutan Robots para subir, importar, transformar, optimizar, almacenar y entregar archivos.

Transloadit ofrece archivos alojados mediante Transloadit Storage EN (English) (actualmente en beta). Tu propio bucket de almacenamiento es opcional cuando usas Transloadit Storage. File Library (versión preliminar) ofrece gestión de activos digitales para explorar visualmente, organizar, previsualizar y descargar archivos en Transloadit Storage. El acceso a File Library se habilita por Workspace; consúltanos sobre su disponibilidad.

Esta guía demuestra la ruta con almacenamiento propio: migra las subidas y el procesamiento a Templates y exporta los activos a tu bucket. Mantén el catálogo de activos de tu aplicación junto a ese almacenamiento. Migrar las carpetas y los metadatos existentes del DAM, trasladar la entrega en producción a URL de Smart CDN en tlcdn.com, y reemplazar los flujos de aprobación, la gestión de derechos, los selectores de activos o las integraciones con CMS requieren su propio plan de migración. La disponibilidad de File Library no implica compatibilidad uno a uno con todas las funciones del DAM de Cloudinary.

Mapa de migración

Decisiones antes de migrar. Esta tabla relaciona tareas, no API intercambiables. Recrea la validación de ajustes preestablecidos, el nombrado y las reglas de acceso en tu backend. La selección automática de formato y calidad⁠ de Cloudinary y el recorte basado en gravedad⁠ necesitan comparaciones de salida; el recorte fijo en WebP a continuación no reproduce el comportamiento de f_auto, q_auto ni g_auto. Inventaría las transformaciones nombradas, las superposiciones, los efectos de IA y los add-ons por separado, y decide cuáles reconstruir, conservar o dejar fuera. Esta guía no ofrece equivalentes para esos efectos.

Empieza por el flujo de trabajo, no por la URL

Las URL de transformación de Cloudinary⁠ codifican los parámetros de procesamiento en la ruta de entrega. En Transloadit, coloca los Steps de procesamiento necesarios en un Template y llámalo desde tu aplicación. Mantén las definiciones de Template en control de versiones junto con el código de tu aplicación y los activos de regresión.

Por ejemplo, este Template produce un recorte fijo en WebP de 1600 × 900 y optimiza esa salida. Compara su apariencia y tamaño de archivo con la versión de Cloudinary que estás reemplazando:

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "hero": {
      "use": ":original",
      "robot": "/image/resize",
      "width": 1600,
      "height": 900,
      "resize_strategy": "fillcrop",
      "format": "webp"
    },
    "optimized": {
      "use": "hero",
      "robot": "/image/optimize",
      "result": true
    },
    "exported": {
      "use": "optimized",
      "robot": "/s3/store",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "path": "media/${unique_prefix}/${file.url_name}",
      "url_prefix": "https://cdn.example.com/",
      "acl": "bucket-default"
    }
  }
}

Reemplaza YOUR_AWS_CREDENTIALS por credenciales de terceros guardadas. Este ejemplo asume que tu CDN sirve la raíz del bucket y tiene permiso para leer sus objetos; url_prefix solo cambia las URL devueltas, no la configuración de la CDN ni los permisos de acceso. acl: "bucket-default" no envía ninguna ACL de objeto; configura el acceso mediante la política de tu bucket y el acceso de origen de la CDN.

Tu backend crea una solicitud de Assembly firmada con el template_id guardado y un notify_url para Assembly Notifications. Verifica la firma de la notificación y exige ASSEMBLY_COMPLETED antes de actualizar los registros de la aplicación. En este ejemplo, lee los archivos exportados desde results.optimized: el Step de almacenamiento actualiza las URL del Step que lo produce. Persiste únicamente los resultados con is_temp_url: false; las URL temporales de Transloadit caducan a las 24 horas y no son URL de entrega. Consulta cómo guardar los resultados de conversión.

Reemplaza las URL de imágenes dinámicas

Si tu aplicación depende de URL de transformación dinámicas, hay dos rutas de migración comunes:

1. Usa un Template por familia de transformaciones y activa una Assembly cuando se cree o modifique el activo.
2. Usa Smart CDN con URL firmadas para transformaciones bajo demanda que deban almacenarse en caché en el borde.

Para páginas de alto tráfico, prefiere generar y almacenar las variantes canónicas por adelantado. Para bibliotecas de activos muy grandes con patrones de acceso de larga cola, Smart CDN puede reducir el trabajo de preprocesamiento.

Smart CDN necesita un Template independiente compuesto solo de Robots compatibles, con una rama de respuesta que termine en /file/serve. Por ejemplo, importa una imagen, redimensiónala y sirve esa salida. /video/encode y /video/adaptive no son compatibles con Smart CDN; genera las URL firmadas de Smart CDN en tu backend.

Reemplaza las referencias de entrega. Mantén un mapeo de cada URL de versión original y usada a su destino verificado, incluidas las referencias en registros de base de datos, srcset, CSS, plantillas de correo electrónico y contenido de CMS. Las URL de entrega de Cloudinary⁠ codifican el nombre de la nube, los tipos de recurso y de entrega, y el ID público, con componentes opcionales de transformación y versión; cambiar solo el nombre de host no puede traducir esas rutas. Reemplaza las referencias incrustadas de res.cloudinary.com en tu aplicación. Coloca las redirecciones en una ruta de aplicación o un nombre de host de medios que tú controles, preserva la autorización para medios restringidos y conserva el servicio de origen mientras los enlaces antiguos aún lo necesiten.

Importa los activos existentes de Cloudinary

Construye primero el inventario. Usa la API de administración⁠ de Cloudinary para listar los tipos de recurso y tipos de entrega que usa tu cuenta, sigue next_cursor a través de todas las páginas, y solicita explícitamente tags, context y metadata. Si restringes la respuesta con fields, incluye también esos campos ahí. Respeta el límite de solicitudes de la API de administración de la cuenta. Registra asset_id, public_id, tipo, versión, URL de origen, tamaño en bytes y el mapeo de destino en tu propio manifiesto. Incluye los registros de activos que solo existen en la aplicación y que el inventario de Cloudinary no puede proporcionar.

Preserva la organización por separado. Descargar un archivo no transfiere su catálogo de activos:

Reconstruye las relaciones del catálogo y los permisos en tu aplicación. El Template de importación a continuación copia el binario seleccionado y una miniatura; no crea un catálogo DAM alojado ni migra metadatos, colecciones o historial de versiones. El componente de versión de una URL de entrega⁠ controla la actualización de la caché de la CDN; usa el mecanismo de descarga de copias de seguridad para exportar los archivos anteriores conservados.

Si el medio seleccionado está disponible mediante una URL HTTPS autorizada, usa 🤖/http/import en lugar de volver a subirlo:

{
  "steps": {
    "imported": {
      "robot": "/http/import",
      "url": "${fields.cloudinary_url}"
    },
    "thumbnail": {
      "use": "imported",
      "robot": "/image/resize",
      "width": 400,
      "height": 400,
      "resize_strategy": "fillcrop",
      "result": true
    },
    "exported": {
      "use": ["imported", "thumbnail"],
      "robot": "/s3/store",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "path": "cloudinary-import/${unique_prefix}/${file.url_name}",
      "acl": "bucket-default"
    }
  }
}

Pasa una URL de origen autorizada como el campo de Assembly cloudinary_url, seleccionado por tu backend a partir de tu inventario de activos. Una URL transformada de Cloudinary⁠ importa esa versión; selecciona el original de forma deliberada cuando lo necesites. Para activos restringidos⁠, genera la descarga autorizada correspondiente en tu backend y permite suficiente tiempo para la importación. Conserva el ID y la URL del activo antiguo hasta que la exportación completada sea accesible mediante tu ruta de entrega prevista y sus dimensiones y calidad cumplan con tus requisitos. Este Template de importación devuelve los archivos exportados bajo results.imported y results.thumbnail. Un objeto privado de S3 sigue necesitando una descarga autorizada o tu CDN configurada.

Widget de subida y automatización. Reemplaza el widget de subida de Cloudinary⁠ por Uppy y sigue la guía de integración firmada en el servidor⁠. Actualiza los callbacks para persistir los resultados verificados de la Assembly. Un selector de Media Library de Cloudinary⁠ selecciona activos existentes del DAM; reemplazar ese selector y su integración con el CMS requiere un explorador de activos y un catálogo independientes, más allá de reemplazar la interfaz de subida.

Las notificaciones⁠ de Cloudinary cubren múltiples eventos de activos, incluidas notificaciones de transformación eager independientes. Mapea la finalización del procesamiento a Assembly Notifications y gestiona en tu aplicación los eventos de renombrado, eliminación, catálogo y moderación. Reescribe la verificación de firmas para el formato de notificación de Transloadit, confirma la recepción solo después de un manejo duradero, y deduplica las actualizaciones por ID de la Assembly. Prueba los fallos y la gestión de reintentos usando la documentación de la API de Webhooks, y registra las importaciones fallidas en el manifiesto antes de reintentarlas.

Decisiones de seguridad. Cloudinary soporta subidas firmadas y no firmadas⁠; el esquema de firma no es intercambiable con la autenticación de Transloadit. Autoriza a los usuarios y firma solo los Templates y campos permitidos en tu backend. Trata el acceso de entrega por separado: el tipo de entrega privado⁠ de Cloudinary protege los originales pero permite los activos derivados de forma predeterminada, mientras que su tipo autenticado protege ambos. Recrea la política deseada en tu bucket y CDN; una subida firmada o una URL de procesamiento firmada no es una ACL para un objeto exportado.

Si usas el add-on de detección de malware Perception Point⁠ de Cloudinary, planifica el escaneo y la cuarentena antes de la entrega pública en el pipeline de reemplazo. Ninguno de los ejemplos aquí habilita el escaneo de malware ni la moderación de contenido. Esta guía no configura un sistema de cuarentena, una política de moderación de contenido, DRM ni una implementación completa de control de acceso.

Agentes y ejecución repetible. Las herramientas de agentes y servidores MCP⁠ de Cloudinary exponen operaciones de activos, transformación, análisis y entorno a clientes de IA. Inventaría cualquier agente que llame a esas herramientas como dependencia de la aplicación. Haz que los agentes propongan Template Instructions con control de versiones, y luego revisa y ejecuta el flujo de trabajo guardado con entradas acotadas y variantes de salida. Conserva los IDs de las Assemblies, los motivos de fallo y los mapeos de destino para soporte y reejecución; añadir un agente no migra el catálogo de activos ni garantiza píxeles idénticos. Esta guía no porta herramientas MCP ni integraciones de agentes individuales.

Lista de verificación

Estimación de esfuerzo. Como margen de planificación, reserva varios días de ingeniería para una ruta de subida, algunas transformaciones fijas y la entrega pública, seguidos de tiempo de backfill. Una aplicación con un uso intensivo de DAM que incluya historial, efectos personalizados, entrega restringida e integraciones de CMS puede requerir semanas o más. Estas son estimaciones, no puntos de referencia de migración medidos. Mide un lote representativo para estimar el tiempo de transferencia y el costo de procesamiento; incluye los cargos de descarga de origen, los costos de almacenamiento/CDN de destino y un período de solapamiento. Un reemplazo de DAM alojado necesita una estimación independiente.

1. Inventaría los activos, metadatos, transformaciones usadas, integraciones de widget/selector y reglas de autorización.
2. Crea Templates con control de versiones y credenciales de terceros; compara salidas representativas.
3. Define tamaños de lote acotados, concurrencia, límites de reintento y un presupuesto de migración. Confirma con tu equipo la región de ejecución, la región de almacenamiento, la retención y los requisitos de cumplimiento antes de mover datos.
4. Ejecuta un piloto pequeño; verifica la finalización, las URL duraderas, las dimensiones, los tamaños de archivo, los mapeos de metadatos, el acceso privado y la recuperación de errores.
5. Activa las subidas nuevas detrás de un feature flag y realiza el backfill de los activos existentes en lotes acotados. Registra cada éxito y fallo para que los reintentos no creen activos duplicados sin seguimiento.
6. Reemplaza las referencias de entrega o añade redirecciones en infraestructura que controles; prueba páginas reales, enlaces de correo electrónico y contenido en caché.
7. Conserva los identificadores de Cloudinary y la ruta de entrega para una posible reversión hasta que termine el período de solapamiento acordado y el inventario cuadre. Da de baja el servicio solo después de resolver los activos faltantes y los enlaces antiguos.