# Cloudinary Transformation Rules This skill helps you create valid Cloudinary transformation URLs from natural language instructions and debug transformation issues. ## When to Use This Skill - 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 ## 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` for automatic format/quality optimization - 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//////. ``` **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](https://cloudinary.com/documentation/transformation_reference.md) 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_` 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) ``` g_auto # Smart detection (works with c_fill, c_lfill, c_crop, c_thumb, c_auto) g_face # Face detection g_center # Center position g_north_west # Compass positions x_20,y_30 # Pixel offsets x_0.8,y_0.2 # Percentage offsets (0.8 = 80%, 0.2 = 20%) ``` **Coordinate value formats (x, y):** - **Integers** (e.g., `x_20`, `y_30`) = pixels - **Float values** (e.g., `x_0.8`, `y_0.2`) = percentage in relation to 1.0 (0.8 = 80%, 0.2 = 20%) - **Important**: When using x, y, h, and w together, use either integers or floats for all values. Do not mix types. **Note**: `g_auto` does NOT work with `c_scale`, `c_fit`, `c_limit`, `c_pad`, or overlay positioning. ### Format & Quality ``` f_auto/q_auto # Automatic optimization (best practice: separate components) f_webp # Specific format q_80 # Quality level dpr_auto # Retina displays (see important notes below) ``` **Best Practice**: Format and quality parameters should be in separate components using `/`. While `f_auto,q_auto` works, separating them (e.g., `f_auto/q_auto`) is cleaner and more maintainable. #### Important Notes About `dpr_auto` `dpr_auto` automatically matches the Device Pixel Ratio (DPR) of the user's device, but has several important limitations: **Browser Compatibility:** - **Only works on Chromium-based browsers** (Chrome, Edge, Opera, Samsung Internet) - Requires [Client Hints](https://cloudinary.com/documentation/responsive_server_side_client_hints) to be enabled - If Client Hints aren't supported or available, the URL is treated as `dpr_1.0` **Named Transformation Limitation:** - ❌ **Does NOT work inside named transformations** (similar to `f_auto`) - The client or CDN won't "see" `dpr_auto` when it's inside a named transformation - ✅ Use `dpr_auto` directly in the URL, not within `t_` **To enable Client Hints**, add to your HTML `` before any ``, `