How to Build Cloudinary URLs

Cloudinary URLs let you transform images and videos by adding parameters to the URL. Resize, crop, add filters, and optimize delivery—all without editing the original file.

URL Structure

Cloudinary URLs follow a predictable pattern: your cloud name, asset type, delivery type, transformations, and finally the file path. Understanding this structure lets you construct URLs programmatically and debug transformation issues by inspecting each URL segment.

The table below breaks down each segment of the URL. Your cloud name is assigned when you create your Cloudinary account—you can find it in your dashboard.

With the URL structure clear, let's explore the most common transformations you will use daily: resizing and cropping.

Resizing Images

Resizing is the most frequently used transformation. You can specify width, height, crop mode, and aspect ratio to control exactly how your image fits into the target dimensions. Cloudinary handles the math and caching for you.

Crop Modes

The crop mode determines how Cloudinary handles images that do not match your target dimensions. Choosing the right mode prevents awkward stretching or unwanted cropping of important content.

Beyond basic resizing, Cloudinary offers transformations for nearly any image manipulation you might need. Let's look at some common patterns used in production applications.

Common Transformations

These transformation examples cover the most frequent use cases: responsive images for web performance, profile thumbnails, and visual effects. Each example includes the complete URL so you can see the transformation syntax in context.

Responsive Image

Square Thumbnail

Blurred Background

Rounded Corners

Chaining Transformations

When you need multiple transformations, you can chain them together using slashes. Each slash-separated segment represents a transformation step, applied in order from left to right. This is useful for complex effects that combine resizing, filters, and overlays.

This URL first resizes the image to 400x300 with c_fill, then applies a grayscale filter, and finally adds 20-pixel rounded corners. The order matters—resizing happens before the other effects are applied.

Automatic Optimization

Cloudinary's automatic optimization features can significantly reduce file sizes without visible quality loss. Using f_auto and q_auto together typically reduces image sizes by 40-60% compared to unoptimized originals.

# Auto format - serves WebP, AVIF, or JPEG based on browser support
f_auto

# Auto quality - optimizes compression without visible quality loss
q_auto

# Combine both for best results
f_auto,q_auto

The f_auto parameter detects browser support and serves WebP or AVIF where supported, falling back to JPEG or PNG for older browsers. The q_auto parameter analyzes image content and applies optimal compression.

Building URLs Dynamically

In your application code, you will need to construct Cloudinary URLs dynamically based on context—different sizes for thumbnails versus detail views, different crops for mobile versus desktop. Here is a utility function that handles the common cases.

function buildCloudinaryUrl(options) {
  const {
    cloudName,
    publicId,
    transformations = [],
    format = 'auto'
  } = options;

  const transformString = transformations.join('/');
  const formatParam = format === 'auto' ? 'f_auto,q_auto' : '';

  const parts = [
    `https://res.cloudinary.com/${cloudName}/image/upload`,
    formatParam,
    transformString,
    publicId
  ].filter(Boolean);

  return parts.join('/');
}

// Usage
const url = buildCloudinaryUrl({
  cloudName: 'my-cloud',
  publicId: 'products/shirt.jpg',
  transformations: ['w_400', 'h_400', 'c_fill']
});
// https://res.cloudinary.com/my-cloud/image/upload/f_auto,q_auto/w_400/h_400/c_fill/products/shirt.jpg

This function accepts an options object and constructs the URL by joining the parts. It automatically includes format and quality optimization, with transformations inserted in the correct position between /upload/ and the public ID.

React Component

For React applications, wrapping Cloudinary URL generation in a component makes your code cleaner and ensures consistent image optimization across your app. The component below accepts common transformation props and handles URL construction internally.

interface CloudinaryImageProps {
  cloudName: string;
  publicId: string;
  width?: number;
  height?: number;
  crop?: 'fill' | 'fit' | 'limit' | 'thumb';
  gravity?: 'face' | 'auto' | 'center';
  className?: string;
  alt: string;
}

function CloudinaryImage({
  cloudName,
  publicId,
  width,
  height,
  crop = 'fill',
  gravity,
  className,
  alt
}: CloudinaryImageProps) {
  const transforms = ['f_auto', 'q_auto'];

  if (width) transforms.push(`w_${width}`);
  if (height) transforms.push(`h_${height}`);
  if (crop) transforms.push(`c_${crop}`);
  if (gravity) transforms.push(`g_${gravity}`);

  const src = `https://res.cloudinary.com/${cloudName}/image/upload/${transforms.join(',')}}/${publicId}`;

  return <img src={src} alt={alt} className={className} />;
}

// Usage
<CloudinaryImage
  cloudName="my-cloud"
  publicId="products/shirt.jpg"
  width={400}
  height={400}
  crop="fill"
  gravity="face"
  alt="Product image"
/>

The component builds the transformation string from props, joining them with commas. Using TypeScript ensures you only pass valid crop modes and gravity values, preventing URL typos at compile time.

Video Transformations

Cloudinary also transforms videos using the same URL pattern. You can resize, trim, and transcode videos on-the-fly. The syntax is similar to images, with additional parameters for temporal editing like start and end offsets.

The table below lists video-specific parameters. These can be combined with the standard resize parameters to create thumbnails, previews, or optimized versions of your video content.

Try the URL Builder

Use our Cloudinary Transform template to build image URLs interactively. You can experiment with different transformation parameters and see how they affect the URL structure in real time.