Basic

To transform and optimize your images and videos on delivery, you can pass the following fields to options.transformations in each build url method call or options in Transformer.transform call.

The list below is basic transformations for both videos and images. See additional image-only fields for image handling, or video-only fields for video handling.

resize

• Type: Resize
  • width: number | string
    • Target width
  • height: number | string
    • Target height
  • type: string
    • Mode to determine how to fit the image/video into the desired size.
    • Accepted value for type: imaggaScale | imaggaCrop | crop | fill | scale | minimumPad | fit | pad | limitFit | thumbnail | limitFill | minimumFit | limitPad | fillPad
  • aspectRatio: string
    • To determine how the asset is adjusted to the new size.

To resize an image/video according a certain width, height, aspect ratio and the desired crop mode.

import { buildImageUrl } from "cloudinary-build-url";

const url = buildImageUrl("example", {
  cloud: {
    cloudName: "demo",
  },
  transformations: {
    resize: {
      type: "scale",
      width: 500,
      height: 500,
      aspectRatio: "1.5",
    },
  },
});

See Resize type for more information.

background

• Type: String

The background color to apply when using pad crop mode or converting to .jpg format.

import { buildImageUrl } from "cloudinary-build-url";

const url = buildImageUrl("example", {
  cloud: {
    cloudName: "demo",
  },
  transformations: {
    background: "#fffff",
    format: "jpg",
  },
});

effect

• Type: Effect or VEffect (for video)
• An available effect or array of effects to apply to asset.

Apply a filter or an effect on the desired asset. SeeEffects for images or Effects for videos for the full list of syntax and available effects.

import { buildImageUrl } from "cloudinary-build-url";

const url = buildImageUrl("example", {
  cloud: {
    cloudName: "demo",
  },
  transformations: {
    effect: {
      name: "grayscale",
    },
  },
});

radius

• Type: String | Number
• Accepted value: max for circular corner, or any pixels.

Round the specified corners of the desired image. If pass only a number or max, all corners will be applied. The syntax for other use cases is as below:

• Using 2 values: top_left_bottom_right_radius:top_right_bottom_left_radius(Example: 20:40)
• Using 3 values: top_left:top_right_bottom_left:bottom_right (Example: 20:30:40)
• Using 4 values: top_left:top_right:bottom_left:bottom_right (Example: 20:0:40:40)

import { buildImageUrl } from "cloudinary-build-url";

const url = buildImageUrl("example", {
  cloud: {
    cloudName: "demo",
  },
  transformations: {
    radius: "20:0:40:40",
  },
});

gravity

• Type: String

Detemine which part of the image to cropped or to place the overlay. See Gravity documentation for list of accepted values and syntax.

import { buildImageUrl } from "cloudinary-build-url";

const url = buildImageUrl("example", {
  cloud: {
    cloudName: "demo",
  },
  transformations: {
    //apply AI to detect the main subject in the image.
    gravity: "auto:subject",
  },
});

rotate

• Type: Rotation
• Accepted values: any degree number, or auto_right | auto_left | ignore | vflip | hflip

To rotate or flip a given asset by certain degrees, or automatically based on orientation.

import { buildImageUrl } from "cloudinary-build-url";

const url = buildImageUrl("example", {
  cloud: {
    cloudName: "demo",
  },
  transformations: {
    rotate: 90,
  },
});

dpr

• Type: String | Number

The target device pixel ratio for the asset. auto means automatically matching the DPR settings in user's device.

import { buildImageUrl } from "cloudinary-build-url";

const url = buildImageUrl("example", {
  cloud: {
    cloudName: "demo",
  },
  transformations: {
    dpr: "2.0",
  },
});

overlay

• Type: String

Create a layer over the base image. This can be use with position.x, position.y, gravity to customize the position of the overlay.

import { buildImageUrl } from "cloudinary-build-url";

const url = buildImageUrl("face_top", {
  cloud: {
    cloudName: "demo",
  },
  transformations: {
    gravity: "north",
    overlay: "text:default_style:Hello+World",
  },
});

format

• Type: String
• Default: auto

Force format conversion of the desired asset to the given format.

import { buildImageUrl } from "cloudinary-build-url";

const url = buildImageUrl("example", {
  cloud: {
    cloudName: "demo",
  },
  transformations: {
    format: "png",
  },
});

quality

• Type: String | Number
• Default: auto

Control the compression quality of the target asset. Scale: 1 to 100 (%)

import { buildImageUrl } from "cloudinary-build-url";

const url = buildImageUrl("example", {
  cloud: {
    cloudName: "demo",
  },
  transformations: {
    quality: 10,
  },
});

if

• Type: String

.Deprecated in 0.1.0. Please use condition instead.

Apply the transformation only if a condition is met.

import { buildImageUrl } from "cloudinary-build-url";

const url = buildImageUrl("example", {
  cloud: {
    cloudName: "demo",
  },
  transformations: {
    if: "w_gt_300",
    effect: {
      name: "e_oil_paint",
    },
  },
});

condition

• Type: Condition
  • if - required
    • Type: ConditionExpression
      • expression - Expression[]
        • characteristic - A string or array of strings with image characteristics
        • operator - Conditional operators ()
        • value - Value of the expression (String or Number)
      • transformations - TransformerOption[]
        • A set of transformations to apply when condition is met.
        • Required
  • else
    • transformations - TransformerOption[]
      • A set of transformations to apply when condition is met.
      • Required

Apply the transformation only if a condition is met.

import { buildImageUrl } from "cloudinary-build-url";

const url = buildImageUrl("example", {
  cloud: {
    cloudName: "demo",
  },
  transformations: {
    condition: {
      if: {
        expression: [{
          characteristic: "width",
          operator: "greaterThan",
          value: 300
        }],
        transformations: [{
          effect: {
            name: "e_oil_paint",
          }
        }]
      }
    },
  },
});

flags

• Type: Flag | VFlag (video)

One of more flags to alter the default transformation behavior. See Flags for Images and Flags for Videos for more information.

import { buildImageUrl } from "cloudinary-build-url";

const url = buildImageUrl("example", {
  cloud: {
    cloudName: "demo",
  },
  transformations: {
    flags: "cutter",
  },
});

colorSpace

• Type: String

Color space to use for the delivery image url. See Color space Documentation for accepted values details.

import { buildImageUrl } from "cloudinary-build-url";

const url = buildImageUrl("example", {
  cloud: {
    cloudName: "demo",
  },
  transformations: {
    colorSpace: "srgb",
  },
});

chaining

• Type: TransfomerOption[] | TransformerVideoOption[] (video)

An array of group transformations to apply to the asset.

import { buildImageUrl } from "cloudinary-build-url";

const url = buildImageUrl("example", {
  cloud: {
    cloudName: "demo",
  },
  transformations: {
    resize: {
      width: 500,
      type: "scale",
      height: 500,
    },
    chaining: [
      {
        effect: {
          name: "grayscale",
        },
      },
    ],
  },
});