Migrate from Cloudinary to Transloadit

Cloudinary centers media processing around upload presets, transformation URLs, and its asset library. Transloadit centers processing around Assembly Instructions: explicit workflows that run Robots for uploading, importing, transforming, optimizing, storing, and serving files.

This guide shows how to translate common Cloudinary patterns into Transloadit Templates.

Migration map

Start with the workflow, not the URL

Cloudinary URLs often encode the transformation inline. In Transloadit, put that transformation into a Template and call it from your app. That keeps processing rules in one server-side place. Keep Template definitions in your own version control alongside your application code.

For example, a Cloudinary image URL that crops, resizes, converts, and optimizes can become this 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"
    }
  }
}

Replace YOUR_AWS_CREDENTIALS with saved Third-party Credentials. This example assumes your CDN serves the bucket root and has permission to read its objects; url_prefix only changes returned URLs, not CDN configuration or access permissions. acl: "bucket-default" sends no object ACL; configure access through your bucket policy and CDN origin access.

Your backend creates a signed Assembly request with the saved template_id and a notify_url for Assembly Notifications. Verify the notification signature and require ASSEMBLY_COMPLETED before switching application records. In this example, read the exported files from results.optimized: the storage Step updates the producing Step’s URLs. Persist only results with is_temp_url: false; temporary Transloadit URLs expire after 24 hours and are not delivery URLs. See saving conversion results.

Replace dynamic image URLs

If your app relies on dynamic transformation URLs, there are two common migration paths:

1. Use a Template per transformation family, then trigger an Assembly when the asset is created or changed.
2. Use Smart CDN with signed URLs for on-demand transformations that should be cached at the edge.

For high-traffic pages, prefer generating and storing canonical variants up front. For very large asset libraries with long-tail access patterns, Smart CDN can reduce pre-processing work.

Smart CDN needs a separate Template made only of compatible Robots, with a response branch ending in /file/serve. For example, import an image, resize it, and serve that output. /video/encode and /video/adaptive are not Smart CDN-compatible; generate signed Smart CDN URLs on your backend.

Import existing Cloudinary assets

If existing media is available through HTTPS URLs, use 🤖/http/import instead of uploading it again:

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

Pass an authorized source URL as the Assembly field cloudinary_url, selected by your backend from your asset inventory. A transformed Cloudinary URL imports that rendition, not automatically the original. Keep the old asset ID and URL until the completed export is accessible through your intended delivery path and its dimensions and quality meet your requirements. This import Template returns exported files under results.imported and results.thumbnail. A private S3 object still needs an authorized download or your configured CDN.

Checklist

1. List the Cloudinary transformations your application actually uses.
2. Group similar transformations into Transloadit Templates.
3. Create Third-party Credentials for your target storage provider.
4. Add Assembly Notifications so your app can store the exported storage URLs.
5. Backfill existing assets with /http/import in bounded batches; its url parameter also accepts an array.
6. Update delivery code to read from your storage/CDN or Smart CDN.