Cloudinary Transformation Rules

When to Use

Building Cloudinary delivery/transformation URLs
Converting natural language requests to transformation syntax
Debugging transformation URLs that aren't working
Optimizing images or videos with Cloudinary
Applying effects, overlays, resizing, or cropping

Quick Start

Default Best Practice: Always Optimize

Add f_auto/q_auto to the end of nearly every transformation URL (as final components):

Automatically delivers optimal format
Optimizes quality for best balance of visual quality and file size
Reduces bandwidth and improves performance

Example: c_fill,g_auto,w_400,h_300/f_auto/q_auto

Exceptions - Don't add optimization when:

Account has "Optimize By Default" enabled (already applied automatically)
Special quality requirements (use q_auto:best, q_auto:low, or manual q_N instead)
Specific format required (replace f_auto with f_png, f_jpg, etc.)
Delivering exact original with no modifications

Examples of common transformations (with optimization):

Resize: c_scale,w_400/f_auto/q_auto
Smart crop: c_fill,g_auto,h_300,w_400/f_auto/q_auto
Background removal: e_background_removal/f_png/q_auto
Text overlay: co_yellow,l_text:Arial_40:Hello%20World/fl_layer_apply,g_south/f_auto/q_auto
Image overlay: l_logo/c_scale,w_100/fl_layer_apply,g_north_west,x_10,y_10/f_auto/q_auto

Important: All transformation strings shown throughout this skill are illustrative examples to demonstrate syntax and concepts. When generating transformations, choose specific values (dimensions, colors, positions, etc.) based on the user's actual requirements and use case, not the example values shown.

For debugging: See references/debugging.md for detailed troubleshooting steps.

Gathering Requirements

Before generating a transformation URL, if not already specified, clarify these details based on the user's request:

For Resize/Crop Requests

Required:

At least one dimension (width OR height)
Crop behavior if both dimensions specified (fill, pad, scale, limit, etc.)

Clarify:

Focal point/gravity (especially for cropping): Face detection? Center? Smart auto-detection?
Maintain aspect ratio? (if only one dimension, this is automatic)

Example questions:

"What dimensions do you need? (width and/or height)"
"Should this fill the space (may crop) or fit within it (no cropping)?"
"Any important focal point? (faces, center, specific area)"

For AI Transformation Requests

Background removal:

Output format needs (PNG for transparency vs JPG with solid background)
What to do with transparent area (keep transparent, add color, or gen_fill)

Generative fill:

Target dimensions or aspect ratio
How much extension needed

Generative replace:

What object to replace (from)
What to replace it with (to)
Preserve original shape? (for clothing/objects)

Generative remove:

What object(s) to remove
Remove all instances or just one?

Generative background replace:

Describe desired background (or use auto-generation)
Need reproducibility? (consider seed parameter)

For Video Transformation Requests

Trimming:

Start and end time, or duration
Seconds or percentage of video

Codec/format:

Output format needs (MP4, WebM, etc.)
Quality requirements (use vc_auto if unsure)

Audio:

Keep or remove audio track
If for autoplay, suggest removing audio (ac_none)

Always Recommend

Unless user specifies otherwise:

Add f_auto/q_auto at the end of transformation URLs (see Quick Start section for exceptions)
Use g_auto for smart cropping when filling dimensions
Consider cost for AI transformations (inform user of transformation credits)

Quick Reference

URL Structure

https://res.cloudinary.com/<cloud_name>/<asset_type>/<delivery_type>/<transformations>/<version>/<public_id>.<ext>

Key Rules:

Commas (,) separate parameters within a component
Slashes (/) separate components between transformations
Each component acts on the output of the previous one

Parameter Types

Action parameters: Perform transformations (one action per component: each action transformation should be separated by a slash) Qualifier parameters: Modify action behavior (in the same component as the action, using commas as separators)

Check the Transformation Reference to determine if a parameter is an action or qualifier.

Core Transformations

Resize & Crop

Dimension value formats:

Whole numbers (e.g., w_400, h_300) = pixels
Decimal values (e.g., w_0.5, h_1.0) = percentage of original dimensions (0.5 = 50%, 1.0 = 100%)

Choosing the right crop mode:

Use c_scale when:

Resizing while maintaining original aspect ratio
Specify only ONE dimension (width OR height)
No cropping needed
The user intentionally wants to stretch or squash an image by changing the aspect ratio

Use c_fill when:

Must fit exact dimensions (e.g., thumbnail grid, fixed layout)
Okay to crop parts of image
Combine with g_auto for smart cropping, or g_face for portraits

Use c_fit when:

Image must fit within dimensions without cropping
Okay to have empty space
Maintaining full image content is critical

Use c_pad when:

Must fit exact dimensions without cropping
Need to fill empty space with background color/blur/AI-generated pixels
Use with b_<color> or b_auto (blurred background) or b_gen_fill

Use c_limit when:

Set maximum dimensions but don't upscale small images
Preserving original quality of small images matters

Use c_thumb when:

Creating thumbnails (typically avatars)
Use with g_face for face-centered crops

Use c_auto when:

Cloudinary should intelligently crop to interesting content
Combine with g_auto for best results
Good for dynamic content where focal point varies

Examples:

c_scale,w_400                      # Resize width to 400px, maintain aspect ratio
c_scale,w_0.5                      # Resize to 50% of original width
c_fill,g_auto,h_300,w_400          # Fill 400x300px dimensions, smart crop
c_fit,h_300,w_400                  # Fit within dimensions, no crop
c_pad,b_white,h_300,w_400          # Pad to exact size with white background
c_pad,w_1.0                        # Pad to original width (100%)
c_limit,w_1000                     # Limit max width, no upscale
c_thumb,g_face,h_150,w_150         # Face-centered square thumbnail
c_auto,g_auto,w_800                # Auto crop to interesting area

Important: Always specify a crop mode explicitly. Avoid using both dimensions with c_scale (will distort if aspect ratios don't match) - prefer one dimension to maintain aspect ratio.

Gravity (Focal Point)

Gravity determines which part of the image to focus on when cropping:

g_auto - Smart detection (recommended for varied content; detects faces, objects, contrast)
g_face - Face detection (portraits, avatars)
g_center - Center position (centered subjects, logos)
g_north, g_south_east, etc. - Compass positions (fixed locations, overlay positioning)
x_N,y_N - Custom offsets (integers = pixels, floats = percentage: 0.8 = 80%)

Examples:

c_fill,g_auto,w_400,h_300                      # Smart crop
c_thumb,g_face,w_200,h_200                     # Face-centered
l_logo/fl_layer_apply,g_south_east,x_10,y_10  # Logo bottom-right

Important:

g_auto only works with c_fill, c_lfill, c_crop, c_thumb, c_auto
When using x, y, h, w together, use all integers OR all floats (don't mix)

Format & Quality

Recommended defaults:

f_auto/q_auto - Use for most production images (WebP to supported browsers, optimized file size)

Specific formats (when requirements dictate):

f_png - Transparency needed (e.g., after background removal)
f_jpg - Force JPEG (remove transparency)
q_N - Manual quality 1-100 (e.g., q_60 for thumbnails, q_90 for hero images)
dpr_auto - Retina displays (Chromium-only, requires Client Hints - see limitations below)

Examples:

f_auto/q_auto           # Recommended default
f_png/q_auto            # PNG with transparency
q_80                    # Manual 80% quality

Best Practice: Use / to separate format and quality as distinct components.

Responsive Images (`dpr_auto`, `w_auto`)

dpr_auto - Automatically adapts to device pixel ratio (Retina displays)

Chromium-only (Chrome, Edge, Opera, Samsung Internet)
Requires Client Hints configuration
Falls back to dpr_1.0 on other browsers
Does NOT work inside named transformations

Alternative for universal support: Use explicit dpr_2.0 or <img srcset> with 1x/2x variants

For Client Hints configuration, browser compatibility, responsive breakpoints, and framework integration, see references/responsive-images.md

Effects

Common effects:

e_grayscale - Black and white (artistic, accessibility)
e_sepia - Vintage/nostalgic feel
e_blur:N - Blur (privacy, placeholders; N typically 300-2000)
e_sharpen - Enhance clarity (useful after resizing)
e_cartoonify - Illustrated style
co_rgb:RRGGBB,e_colorize:N - Color tint (N = intensity 0-100, for brand theming)
e_background_removal - See AI Transformations section

Examples:

e_blur:800                       # Blur effect
e_sharpen                        # Enhance clarity
co_rgb:0044ff,e_colorize:40      # Blue tint at 40%

Note: Color (co_) is a qualifier - use in same component as e_colorize.

Overlays & Underlays

Use for:

l_<public_id> - Image overlays (logos, watermarks, badges)
u_<public_id> - Image underlays (custom backgrounds behind transparent subjects)
l_text:font_size:text - Text overlays (labels, social cards, dynamic text)

Pattern:

Declare: l_<public_id> or u_<public_id> or l_text:Arial_40:Hello%20World
Transform (optional): e.g. /c_scale,w_100/ or /o_50/ (opacity)
Apply: /fl_layer_apply,g_<position>,x_<offset>,y_<offset>

Critical: Using fl_relative for overlay dimensions:

Without fl_relative: Dimensions are relative to the overlay's original size
- Example: w_1.0 = 100% of the overlay image's width (not useful for small images)
With fl_relative: Dimensions are relative to the base image's size
- Example: w_1.0 = 100% of the base image's width (covers entire width)
- Always use fl_relative when sizing overlays as a percentage of the base image

Examples:

l_logo/c_scale,w_100/fl_layer_apply,g_north_west,x_10,y_10                # Logo at 100px
l_logo/c_scale,fl_relative,w_0.25/fl_layer_apply,g_north_west,x_10,y_10  # Logo at 25% of image width
l_docs:one_black_pixel/c_scale,fl_relative,h_1.0,w_1.0/o_50/fl_layer_apply # Full-image semi-transparent overlay
co_yellow,l_text:Arial_40:Hello%20World/fl_layer_apply,g_south            # Text overlay
u_background/e_background_removal                                          # Custom background

Important:

Color (co_) is a qualifier — use in the same component as text overlay declaration
Always use fl_relative when you want overlay dimensions as a percentage of the base image

Borders & Rounding

r_N - Rounded corners (N = radius in pixels; for modern UI, cards)
r_max - Perfect circle (use with square dimensions; avatars, icons)
bo_NNpx_solid_color - Border (frame images, separate from background)

Examples:

r_20                           # 20px rounded corners
r_max                          # Perfect circle
bo_5px_solid_black             # 5px black border
r_20,bo_5px_solid_rgb:0066ff   # Rounded with border (same component)

Important: For borders that follow rounded corners, use border as qualifier in same component.

Background Color

b_color,c_pad - Fill empty space with solid color (product images, letterboxing)
b_auto,c_pad - Blurred original as background (elegant alternative to solid)
b_gen_fill,c_pad - AI-extended background (change aspect ratio without cropping; see AI Transformations for cost)

Examples:

b_lightblue,c_pad,w_1.0         # Light blue background
b_auto,c_pad,ar_16:9            # Blurred background, 16:9
b_gen_fill,c_pad,ar_1:1         # AI-extended to square

Critical: Background (b_) is a qualifier - use with pad crop in same component: b_color,c_pad,w_X, NOT /b_color/.

Rotation & Flips

a_90, a_180, a_270 - Rotate in 90° increments (correct orientation)
a_N - Rotate by degrees (e.g., a_-2 to straighten crooked photos)
a_hflip - Horizontal flip (mirror selfies, directional images)
a_vflip - Vertical flip (reflections)
a_auto_right/a_auto_left - Auto-rotate based on EXIF orientation

Examples:

a_90                    # Rotate 90° clockwise
a_-2                    # Straighten slight tilt
a_hflip                 # Mirror horizontally
a_auto_right            # Auto-fix from EXIF

Named Transformations

Named transformations (t_<name>) save transformation chains for reuse. Suggest for:

Transformations used across multiple assets
Complex transformation chains
Expensive operations (to enable baseline transformations and reduce costs)

Baseline transformations (bl_<name>) cache expensive named transformations so they don't need to be regenerated. Use bl_ instead of t_ for AI transformations (background removal, generative AI) that will have variations applied. This can reduce costs from 75-230 tx per variation down to 1 tx each after the initial baseline is generated.

Example: bl_bg_removed/c_scale,w_500 - Uses cached background removal result, only pays for resize (1 tx instead of 75 tx)

Important: f_auto, dpr_auto, and w_auto don't work inside named transformations - use them directly in URLs: t_avatar/f_auto/q_auto

For complete details, limitations, and baseline transformation examples, see references/named-transformations.md

Generative AI Transformations

Proactively suggest these AI transformations when appropriate:

Note: Numbers in parentheses (e.g., 75 tx) indicate additional transformation credits consumed per use. Standard transformations = 1 tx.

e_background_removal (75 tx) - Remove backgrounds (e-commerce, profiles; combine with f_png or b_color,c_pad)
b_gen_fill (50 tx) - Extend backgrounds (change aspect ratio without cropping; use with c_pad)
e_gen_background_replace:prompt_<text> (230 tx) - AI-generated backgrounds (custom environments, seasonal variations; high cost)
e_gen_replace:from_<obj>;to_<new> (120 tx) - Swap objects (product variations, colors; use ;preserve_geometry_true for clothing)
e_gen_remove:prompt_<text> (50 tx) - Remove objects (clean up distractions)
e_auto_enhance (100 tx) - Improve quality (fix poor lighting/exposure)
e_upscale (10-100 tx) - Enlarge without quality loss (low-res to high-res)

Important: AI transformations cost significantly more (50-230 tx vs 1 tx). Inform users of costs and consider baseline transformations (e.g., bl_bg_removed/c_scale,w_500) to avoid re-processing expensive operations - see references/named-transformations.md and references/transformation-costs.md for details.

For complete details, syntax, and powerful combinations, see references/ai-transformations.md

Video-Specific Transformations

Critical: Use f_auto:video (not just f_auto) to ensure video output - plain f_auto may return an image thumbnail.

vc_auto - Automatic codec (recommended; optimal for browser/device)
so_N/eo_M - Trim (start/end in seconds; create clips, remove intro/outro)
ac_none - Remove audio (essential for autoplay; reduces file size)
fps_N - Set frame rate (lower = smaller file; standardize rates)
Video resizing - Same crop modes as images (c_fill, c_scale, c_pad)

Common patterns:

vc_auto/ac_none/f_auto:video/q_auto                      # Autoplay-ready
so_0/du_10/vc_auto/f_auto:video/q_auto                   # First 10 seconds
c_scale,w_720/vc_auto/f_auto:video/q_auto                # Resize to 720p width
c_fill,g_auto,h_720,w_1280/vc_auto/f_auto:video/q_auto  # 720p HD, smart crop

For complete details including codecs, trimming strategies, and video concatenation, see references/video-transformations.md

Variables & Conditionals

Variables reuse values and create templates:

$size_300/c_fill,h_$size,w_$size        # Reuse value
$iw/w_$iw_div_2                         # Half original width (arithmetic)

Conditionals adapt transformations dynamically:

if_w_gt_1000/c_scale,w_1000/if_end                          # Responsive sizing
if_ar_gt_1.0/c_fill,w_800,h_450/if_else/c_fill,w_450,h_800/if_end  # Orientation handling

Key rules:

Variable names: alphanumeric, start with letter, no underscores
Conditionals: Must close with if_end
Arithmetic: add, sub, mul, div (left-to-right evaluation)

For complete syntax, arithmetic operations, nested conditionals, and real-world patterns, see references/advanced-features.md

Self-Validation Checklist

Before returning a transformation URL, verify:

✅ URL structure is complete (cloud_name, asset_type /image/ or /video/ or /raw/, delivery_type, public_id)
✅ Each component has only one action parameter (e.g., one crop mode per component)
✅ Crop mode is explicit (don't rely on defaults; avoid both dimensions with c_scale)
✅ Overlays end with fl_layer_apply in separate component
✅ Text strings are URL-encoded (spaces = %20, special chars encoded)
✅ Variable names follow rules (alphanumeric, start with letter, no underscores)
✅ g_auto compatibility (only works with c_fill, c_lfill, c_crop, c_thumb, c_auto)
✅ Background as qualifier (use with pad crop: b_color,c_pad,w_X, not /b_color/)
✅ Format/quality at end (prefer f_auto/q_auto as final components)

Quick syntax check:

Commas separate parameters within a component: c_fill,g_auto,w_400
Slashes separate components: c_fill,w_400/f_auto/q_auto
Actions vs qualifiers: Only one action per component, qualifiers modify that action

See references/debugging.md for detailed examples of each check.

Debugging Checklist

When a transformation isn't working:

Verify URL structure: Check that all required URL parts are present:
- Cloud name: /<cloud_name>/
- Asset type: /image/ or /video/ or /raw/
- Delivery type: /upload/ or /fetch/ etc.
- Public ID at the end
Check the X-Cld-Error header: Cloudinary reports errors in the X-Cld-Error HTTP response header
Check parameter names against Transformation Reference
Check crop mode: Specify crop mode explicitly; avoid both dimensions with c_scale (causes distortion if aspect ratios don't match)
Verify gravity compatibility: g_auto doesn't work with c_scale, c_fit, c_limit, c_pad
Check action vs qualifier: Only one action per component, qualifiers in same component
Verify overlay pattern: Must end with fl_layer_apply component
Check variable names: No underscores, must start with letter
Verify URL encoding: Text overlays need URL-encoded strings (spaces = %20)
Check auto parameters in named transformations: f_auto, dpr_auto, and w_auto don't work inside named transformations - use them directly in URLs
Verify Client Hints for dpr_auto/w_auto: These only work on Chromium browsers with Client Hints enabled; fallback to dpr_1.0 otherwise (see references/responsive-images.md for configuration)
Video returns image instead of video: Use f_auto:video (not just f_auto) for video transformations - plain f_auto may return an image thumbnail

Checking X-Cld-Error Header

The X-Cld-Error header contains error details when a transformation fails. To check it:

Using browser DevTools:

Open Developer Tools (Network tab)
Request the transformation URL
Look for X-Cld-Error in Response Headers

Using code (fetch the URL):

fetch('https://res.cloudinary.com/demo/image/upload/w_abc/sample.jpg')
  .then(response => {
    const error = response.headers.get('x-cld-error');
    if (error) {
      console.log('Cloudinary Error:', error);
    }
  });

Common X-Cld-Error messages:

Invalid width - abc - Width parameter expects a number
Invalid transformation syntax - Malformed transformation string
Resource not found - Asset doesn't exist or public ID is incorrect
Transformation limit exceeded - Account transformation quota reached

Online tool: Use the X-Cld-Error Inspector to check any Cloudinary URL

For more details, see Error Handling

Transformation Costs

Important: Warn users about high-cost transformations before generating URLs. AI effects cost significantly more than standard transformations (50-230 tx vs 1 tx).

For complete cost details and cost reduction strategies, see references/transformation-costs.md

Additional Resources

Skill References (Progressive Disclosure)

references/debugging.md - Use when transformations return errors or unexpected results
references/ai-transformations.md - Use when you need AI transformation prompt syntax, cost details, or complex AI combinations
references/video-transformations.md - Use when working with video codecs, trimming strategies, or concatenation
references/advanced-features.md - Use when building complex logic with variables, conditionals, or arithmetic
references/responsive-images.md - Use when implementing responsive images, configuring Client Hints, or using dpr_auto/w_auto
references/transformation-costs.md - Use when optimizing for cost or explaining cost implications to users
references/named-transformations.md - Use when creating reusable transformations or reducing costs for repeated operations
references/examples.md - Use when you need real-world examples beyond the Quick Start (social cards, e-commerce, responsive images)

Core Cloudinary Documentation

Transformation Reference - All parameters

Image Transformations

Video Transformations

Common Mistakes & Best Practices

Avoid:

❌ w_400,h_300 → ✅ c_scale,w_400 (both dimensions with c_scale distorts image; prefer one dimension)
❌ c_scale,g_auto,w_400 → ✅ c_fill,g_auto,w_400 (g_auto doesn't work with c_scale)
❌ l_logo/fl_layer_apply,g_north_west → ✅ l_logo/c_scale,w_100/fl_layer_apply,g_north_west
❌ b_lightblue/e_trim → ✅ b_lightblue,c_pad,w_1.0/e_trim (background as qualifier)

Always:

Prefer f_auto/q_auto in separate components over f_auto,q_auto
Use g_auto for smart cropping unless specific focal point needed
Specify crop mode with width/height; prefer one dimension with c_scale
Never guess parameter names - verify against documentation

cloudinary-transformations

Cloudinary Transformation Rules

When to Use

Quick Start

Default Best Practice: Always Optimize

Gathering Requirements

For Resize/Crop Requests

For AI Transformation Requests

For Video Transformation Requests

Always Recommend

Quick Reference

URL Structure

Parameter Types

Core Transformations

Resize & Crop

Gravity (Focal Point)

Format & Quality

Responsive Images (`dpr_auto`, `w_auto`)

Effects

Overlays & Underlays

Borders & Rounding

Background Color

Rotation & Flips

Named Transformations

Generative AI Transformations

Video-Specific Transformations

Variables & Conditionals

Self-Validation Checklist

Debugging Checklist

Checking X-Cld-Error Header

Transformation Costs

Additional Resources

Skill References (Progressive Disclosure)

Core Cloudinary Documentation

Image Transformations

Video Transformations

Common Mistakes & Best Practices

More from cloudinary-devs/skills

cloudinary-docs

cloudinary-react

cloudinary-transformations

Cloudinary Transformation Rules

When to Use

Quick Start

Default Best Practice: Always Optimize

Gathering Requirements

For Resize/Crop Requests

For AI Transformation Requests

For Video Transformation Requests

Always Recommend

Quick Reference

URL Structure

Parameter Types

Core Transformations

Resize & Crop

Gravity (Focal Point)

Format & Quality

Responsive Images (dpr_auto, w_auto)

Effects

Overlays & Underlays

Borders & Rounding

Background Color

Rotation & Flips

Named Transformations

Generative AI Transformations

Video-Specific Transformations

Variables & Conditionals

Self-Validation Checklist

Debugging Checklist

Checking X-Cld-Error Header

Transformation Costs

Additional Resources

Skill References (Progressive Disclosure)

Core Cloudinary Documentation

Image Transformations

Video Transformations

Common Mistakes & Best Practices

More from cloudinary-devs/skills

cloudinary-docs

cloudinary-react

Responsive Images (`dpr_auto`, `w_auto`)