What is a URL Transformation?

A URL transformation expresses media-processing instructions in a request URL so a derived asset can be generated or retrieved during delivery. Signatures and parameter validation can restrict permitted operations.

How URL Transformations work

A URL transformation service reads two things from the request URL: which source asset to use and what to do with it. On a cache miss it fetches the source, runs the processing, stores the result, and returns it; on a hit it returns the stored result without processing again. Cloudflare describes this sequence for its image transformations, and Cloudinary creates the derived file the first time a transformation URL is accessed. The URL therefore describes the work and is the starting point for the cache key, with two qualifications: a service may normalize the URL first, and when the output also depends on request headers, as with automatic format selection, one URL can produce several cached results. Syntax varies by service: Cloudinary and imgproxy put the operations in path segments, imgix uses query parameters, and Transloadit’s Smart CDN names a saved Template in the path and passes its variables as query parameters. Whether the written order of operations matters also varies. Cloudinary executes each slash-separated component on the result of the previous one, while imgproxy and Fastly Image Optimizer accept options in any order and apply them in a fixed internal sequence.

Key facts

What stops someone from requesting thousands of sizes? Nothing, unless you restrict which URLs are valid. Thumbor’s documentation calls this URL tampering and shows a loop over dimensions as the attack, and imgproxy, which leaves signature checking off by default, recommends enabling it in production for the same reason. The usual controls are a signature over the options and the source (imgproxy signs the whole path after the signature, Thumbor signs the options and the image URL) or an allowlist of permitted transformations (Cloudinary’s strict transformations setting). A saved template that exposes a few variables limits which options a caller can change, not how many values each one accepts: a template with an open width variable still allows the loop, so combine it with signing or a fixed list of allowed values. Signing depends on a secret key, so signed URLs have to be issued by your server, not assembled in browser code. A signature blocks new variants only if it covers every option: imgix notes that an unsigned expires value can be changed freely in the query string.
Do two URLs that produce the same output share a cache entry? Do not assume so: it depends on the service’s cache key and on whether it normalizes URLs. CloudFront documents that ?color=red&size=large and ?size=large&color=red are fetched and cached separately when it caches on query string parameters, and that differences in letter case are treated the same way. Cloudflare’s CDN cache treats query strings in a different order as distinct by default and has an optional Query String Sort setting that orders them before the cache lookup. Billing follows its own rules: Cloudinary counts transformations that are written differently, such as the same parameters in a different order, as separate transformations even when the result is identical, and Cloudflare caches and bills each unique combination of source image and parameters separately. Generate URLs from one helper that emits parameters in a fixed order and case, and round requested widths to a short list of sizes.
What happens to existing variants when the source file is replaced? They can keep being served, because their URLs have not changed. Cloudinary states that after an asset is overwritten, delivered versions, with or without transformations, can remain cached on CDN servers unless they are invalidated, and that copies may also remain in browsers and proxies outside its network. It recommends a version component in the URL when the newest file must be delivered immediately. If you also sign URLs, check that invalidation reaches them: Cloudinary does not invalidate signed URLs by default. imgproxy has a cachebuster option that changes the URL without changing the processing, and advises it over a query string because it can be signed. Plan for one of the two before launch: a version in the URL or source path, or an explicit invalidation step.

How Transloadit helps with URL Transformations

Transloadit’s Smart CDN is a URL transformation service built on Templates. In a tlcdn.com URL the hostname names your Workspace, the path names a saved Template and the source file, and the query parameters fill the Assembly Variables that the Template reads, such as ${fields.w} for a width. The processing steps themselves live in the Template, so a caller can change only the values the Template exposes. The documented example passes the w query parameter straight into the resize width, so exposing a variable does not by itself keep callers to the sizes your pages use; Transloadit’s guidance is to define the parameters callers may vary and to authorize requests with signed URLs. The signature is an HMAC that covers the Workspace, the Template name, the file path, and the sorted query parameters, which prevents the parameters from being altered, and it must be generated on your back end because it uses your Auth Secret.

Signing is described as optional, and the linked pages do not explain how unsigned URLs are refused, so confirm that on your own Workspace before relying on signatures to block new variants. The pages also do not describe a purge operation or what happens to a cached result when the source file is replaced under the same path. Storing a replacement under a new path changes the URL; test the unchanged-path case on your own Workspace before relying on it.

Explore Transloadit’s delivery capabilities

What is a URL Transformation?

How URL Transformations work

Key facts

When URL Transformations matter

How Transloadit helps with URL Transformations

Sources

Turn media knowledge into a working pipeline