Migrar de Cloudinary a Transloadit

Cloudinary centra el procesamiento de medios en los ajustes preestablecidos de subida, las URL de transformación y su biblioteca de recursos. Transloadit centra el procesamiento en las Assembly Instructions: flujos de trabajo explícitos que ejecutan Robots para subir, importar, transformar, optimizar, almacenar y servir archivos.

Esta guía muestra cómo traducir los patrones habituales de Cloudinary a Templates de Transloadit.

Mapa de migración

Empieza por el flujo de trabajo, no por la URL

Las URL de Cloudinary suelen codificar la transformación en línea. En Transloadit, coloca esa transformación en un Template y llámalo desde tu aplicación. Así las reglas de procesamiento quedan en un único lugar del lado del servidor. Mantén las definiciones de los Templates en tu propio control de versiones, junto al código de tu aplicación.

Por ejemplo, una URL de imagen de Cloudinary que recorta, redimensiona, convierte y optimiza puede convertirse en este Template:

{
  "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"
    }
  }
}

Sustituye 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 del 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 del 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 cambiar 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 los produce. Conserva únicamente los resultados con is_temp_url: false; las URL temporales de Transloadit caducan después de 24 horas y no son URL de entrega. Consulta guardar los resultados de conversión.

Reemplaza las URL dinámicas de imágenes

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

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

Para páginas con mucho tráfico, es preferible generar y almacenar las variantes canónicas de antemano. Para bibliotecas de recursos muy grandes con patrones de acceso de cola larga, Smart CDN puede reducir el trabajo de preprocesamiento.

Smart CDN necesita un Template aparte compuesto únicamente por 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.

Importa los recursos existentes de Cloudinary

Si los medios existentes están disponibles a través de URL HTTPS, usa 🤖/http/import en lugar de subirlos de nuevo:

{
  "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 la Assembly cloudinary_url, seleccionada por tu backend a partir de tu inventario de recursos. Una URL de Cloudinary transformada importa esa variante, no automáticamente el original. Conserva el ID y la URL del recurso antiguo hasta que la exportación completada sea accesible a través de la ruta de entrega prevista y sus dimensiones y calidad cumplan tus requisitos. Este Template de importación devuelve los archivos exportados en results.imported y results.thumbnail. Un objeto privado de S3 sigue necesitando una descarga autorizada o tu CDN configurado.

Lista de verificación

1. Enumera las transformaciones de Cloudinary que tu aplicación usa realmente.
2. Agrupa las transformaciones similares en Templates de Transloadit.
3. Crea credenciales de terceros para tu proveedor de almacenamiento de destino.
4. Añade Assembly Notifications para que tu aplicación pueda almacenar las URL de almacenamiento exportadas.
5. Procesa retroactivamente los recursos existentes con /http/import en lotes acotados; su parámetro url también acepta un array.
6. Actualiza el código de entrega para que lea desde tu almacenamiento/CDN o desde Smart CDN.