From cloudinary
Create and debug Cloudinary transformation URLs from natural language instructions. Use when building Cloudinary delivery URLs, applying image/video transformations, optimizing media, or debugging transformation syntax errors.
npx claudepluginhub anthropics/claude-plugins-official --plugin cloudinaryThis skill uses the workspace's default tool permissions.
- Building Cloudinary delivery/transformation URLs
Guides Next.js Cache Components and Partial Prerendering (PPR): 'use cache' directives, cacheLife(), cacheTag(), revalidateTag() for caching, invalidation, static/dynamic optimization. Auto-activates on cacheComponents: true.
Guides building MCP servers enabling LLMs to interact with external services via tools. Covers best practices, TypeScript/Node (MCP SDK), Python (FastMCP).
Share bugs, ideas, or general feedback.
Add f_auto/q_auto to the end of nearly every transformation URL (as final components):
Example: c_fill,g_auto,w_400,h_300/f_auto/q_auto
Exceptions - Don't add optimization when:
q_auto:best, q_auto:low, or manual q_N instead)f_auto with f_png, f_jpg, etc.)Examples of common transformations (with optimization):
c_scale,w_400/f_auto/q_autoc_fill,g_auto,h_300,w_400/f_auto/q_autoe_background_removal/f_png/q_autoco_yellow,l_text:Arial_40:Hello%20World/fl_layer_apply,g_south/f_auto/q_autol_logo/c_scale,w_100/fl_layer_apply,g_north_west,x_10,y_10/f_auto/q_autoImportant: 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.
Before generating a transformation URL, if not already specified, clarify these details based on the user's request:
Required:
Clarify:
Example questions:
Background removal:
Generative fill:
Generative replace:
Generative remove:
Generative background replace:
Trimming:
Codec/format:
vc_auto if unsure)Audio:
ac_none)Unless user specifies otherwise:
f_auto/q_auto at the end of transformation URLs (see Quick Start section for exceptions)g_auto for smart cropping when filling dimensionshttps://res.cloudinary.com/<cloud_name>/<asset_type>/<delivery_type>/<transformations>/<version>/<public_id>.<ext>
Key Rules:
,) separate parameters within a component/) separate components between transformationsAction 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.
Dimension value formats:
w_400, h_300) = pixelsw_0.5, h_1.0) = percentage of original dimensions (0.5 = 50%, 1.0 = 100%)Choosing the right crop mode:
Use c_scale when:
Use c_fill when:
g_auto for smart cropping, or g_face for portraitsUse c_fit when:
Use c_pad when:
b_<color> or b_auto (blurred background) or b_gen_fillUse c_limit when:
Use c_thumb when:
g_face for face-centered cropsUse c_auto when:
g_auto for best resultsExamples:
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 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_autoRecommended 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.
dpr_auto, w_auto)dpr_auto - Automatically adapts to device pixel ratio (Retina displays)
dpr_1.0 on other browsersAlternative 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
Common effects:
e_grayscale - Black and white (artistic, accessibility)e_sepia - Vintage/nostalgic feele_blur:N - Blur (privacy, placeholders; N typically 300-2000)e_sharpen - Enhance clarity (useful after resizing)e_cartoonify - Illustrated styleco_rgb:RRGGBB,e_colorize:N - Color tint (N = intensity 0-100, for brand theming)e_background_removal - See AI Transformations sectionExamples:
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.
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:
l_<public_id> or u_<public_id> or l_text:Arial_40:Hello%20World/c_scale,w_100/ or /o_50/ (opacity)/fl_layer_apply,g_<position>,x_<offset>,y_<offset>Critical: Using fl_relative for overlay dimensions:
fl_relative: Dimensions are relative to the overlay's original size
w_1.0 = 100% of the overlay image's width (not useful for small images)fl_relative: Dimensions are relative to the base image's size
w_1.0 = 100% of the base image's width (covers entire width)fl_relative when sizing overlays as a percentage of the base imageExamples:
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:
co_) is a qualifier — use in the same component as text overlay declarationfl_relative when you want overlay dimensions as a percentage of the base imager_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.
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/.
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 orientationExamples:
a_90 # Rotate 90° clockwise
a_-2 # Straighten slight tilt
a_hflip # Mirror horizontally
a_auto_right # Auto-fix from EXIF
Named transformations (t_<name>) save transformation chains for reuse. Suggest for:
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
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
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)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 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:
if_endadd, sub, mul, div (left-to-right evaluation)For complete syntax, arithmetic operations, nested conditionals, and real-world patterns, see references/advanced-features.md
Before returning a transformation URL, verify:
/image/ or /video/ or /raw/, delivery_type, public_id)c_scale)fl_layer_apply in separate component%20, special chars encoded)g_auto compatibility (only works with c_fill, c_lfill, c_crop, c_thumb, c_auto)b_color,c_pad,w_X, not /b_color/)f_auto/q_auto as final components)Quick syntax check:
c_fill,g_auto,w_400c_fill,w_400/f_auto/q_autoSee references/debugging.md for detailed examples of each check.
When a transformation isn't working:
/<cloud_name>//image/ or /video/ or /raw//upload/ or /fetch/ etc.X-Cld-Error HTTP response headerc_scale (causes distortion if aspect ratios don't match)g_auto doesn't work with c_scale, c_fit, c_limit, c_padfl_layer_apply component%20)f_auto, dpr_auto, and w_auto don't work inside named transformations - use them directly in URLsdpr_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)f_auto:video (not just f_auto) for video transformations - plain f_auto may return an image thumbnailThe X-Cld-Error header contains error details when a transformation fails. To check it:
Using browser DevTools:
X-Cld-Error in Response HeadersUsing 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 numberInvalid transformation syntax - Malformed transformation stringResource not found - Asset doesn't exist or public ID is incorrectTransformation limit exceeded - Account transformation quota reachedOnline tool: Use the X-Cld-Error Inspector to check any Cloudinary URL
For more details, see Error Handling
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
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_westb_lightblue/e_trim → ✅ b_lightblue,c_pad,w_1.0/e_trim (background as qualifier)Always:
f_auto/q_auto in separate components over f_auto,q_autog_auto for smart cropping unless specific focal point neededc_scale