Media transformations

Content Hub ONE lets you transform media (such as images, photos, or artwork) by using parameters in the GraphQL IDE, or by appending them to the URL generated when you upload the asset.

Supported formats

The following input file formats are supported for media transformations:

  • JPEG

  • PNG

  • GIF (including animations)

  • WebP (no animations)

The following output file formats are supported:

  • JPEG

  • PNG

  • GIF (including animations)

  • WebP (including animations)

Maximum image sizes

Image transformations support the following maximum sizes:

  • Maximum image dimension - 12,000 pixels.

  • Maximum image area - 100 megapixels (for example, 10,000 × 10,000 pixels).

  • Maximum file size - 70 MB.

  • Maximum GIF animation size - 100 megapixels total (combined size of all frames).

Note

Media transformation parameters are case sensitive. When adding them to the URL format, you must also append transform=true.

background

Adds a background color underneath the image. This parameter applies only to images with transparency (for example, PNG files). You can use a HEX code to specify the background color (for example, background=%23FF0000) or the color itself (for example, background=red).

GraphQL format

RequestResponse

{
 media(id: "KTsF62Q4gg60q6WCsWJw8") {
  name
  url(
   transform: {
    background: "red",
   }
  )
 }
}

URL format

RequestResponse
// [!code word:<Base_URL>] 
// [!code word:<MEDIA_TENANT_ID>] 
// [!code word:<MEDIA_ITEM_ID>] 

<Base_URL>/api/media/v2/delivery/<MEDIA_TENANT_ID>/<MEDIA_ITEM_ID>?background=red&transform=true

background parameter result

blur

Applies blurring to the entire image. The intensity of the blur is determined by the parameter value, which can range from 1 (lowest) to 250 (highest).

GraphQL format

RequestResponse

{
 media(id: "KTsF62Q4gg60q6WCsWJw8") {
  name
  url(
   transform: {
    blur: 50,
   }
  )
 }
}

URL format

RequestResponse
// [!code word:<Base_URL>] 
// [!code word:<MEDIA_TENANT_ID>] 
// [!code word:<MEDIA_ITEM_ID>] 

<Base_URL>/api/media/v2/delivery/<MEDIA_TENANT_ID>/<MEDIA_ITEM_ID>?blur=50&transform=true

blur parameter result

brightness

Multiplies the brightness level of the image by a factor, where a value of 1.0 equals no change, a value of 0.5 equals half brightness, and a value of 2.0 equals twice as bright. The value must be greater than 0.

GraphQL format

RequestResponse

{
 media(id: "KTsF62Q4gg60q6WCsWJw8") {
  name
  url(
   transform: {
    brightness: 5.0,
   }
  )
 }
}

URL format

RequestResponse
// [!code word:<Base_URL>] 
// [!code word:<MEDIA_TENANT_ID>] 
// [!code word:<MEDIA_ITEM_ID>] 

<Base_URL>/api/media/v2/delivery/<MEDIA_TENANT_ID>/<MEDIA_ITEM_ID>?brightness=2.0&transform=true

brightness parameter result

compression

Fetches a version of the image that has low compression, which reduces cache latency but results in a larger, lower-quality image, typically in JPEG format. We do not recommend using this option, except in special cases such as when you need to resize uncacheable dynamically-generated images.

GraphQL format

RequestResponse

{
 media(id: "KTsF62Q4gg60q6WCsWJw8") {
  name
  url(
   transform: {
    compression: FAST,
   }
  )
 }
}

URL format

RequestResponse
// [!code word:<Base_URL>] 
// [!code word:<MEDIA_TENANT_ID>] 
// [!code word:<MEDIA_ITEM_ID>] 

<Base_URL>/api/media/v2/delivery/<MEDIA_TENANT_ID>/<MEDIA_ITEM_ID>?compression=fast&transform=true

contrast

Increases the contrast by a factor, where a value of 1.0 equals no change, a value of 0.5 equals low contrast, and a value of 2.0 equals high contrast. The value must be greater than 0.

GraphQL format

RequestResponse

{
 media(id: "KTsF62Q4gg60q6WCsWJw8") {
  name
  url(
   transform: {
    contrast: 0.5,
   }
  )
 }
}

URL format

RequestResponse
// [!code word:<Base_URL>] 
// [!code word:<MEDIA_TENANT_ID>] 
// [!code word:<MEDIA_ITEM_ID>] 

<Base_URL>/api/media/v2/delivery/<MEDIA_TENANT_ID>/<MEDIA_ITEM_ID>?contrast=0.5&transform=true

contrast parameter result

dpr

Makes it easier to request high-DPI images. The device pixel ratio (DPR) is a multiplier for width and has a default value of 1.

GraphQL format

RequestResponse

{
 media(id: "KTsF62Q4gg60q6WCsWJw8") {
  name
  url(
   transform: {
    dpr: 2,
   }
  )
 }
}

URL format

RequestResponse
// [!code word:<Base_URL>] 
// [!code word:<MEDIA_TENANT_ID>] 
// [!code word:<MEDIA_ITEM_ID>] 

<Base_URL>/api/media/v2/delivery/<MEDIA_TENANT_ID>/<MEDIA_ITEM_ID>?dpr=1&transform=true

fit

Affects how the image is resized. All resizing modes preserve the original aspect ratio. The available modes are:

  • scale-down - similar to contain, but the image is never enlarged. If the image is larger than the given width or height, it will be resized. Otherwise, its original size is kept. With this mode, the URL is https://mms-delivery-beta.sitecorecloud.io/api/media/v2/delivery/<media tenant ID>/<media item ID>?width=250&fit=scale-down&transform=true. In GraphQL, SCALEDOWN must be uppercase.

  • contain - resizes the image to be as large as possible within the given width or height while preserving the aspect ratio. If you only provide a single dimension (for example, only the width), the image is resized to exactly match that dimension. In GraphQL, CONTAIN must be uppercase.

  • cover - resizes the image to fill the entire area of width and height. If the image has an aspect ratio different from the ratio of width and height, it is cropped to fit. In GraphQL, COVER must be uppercase.

  • crop - shrinks and crops the image to fit within the area specified by width and height. The image is never enlarged by this mode. For images smaller than the given dimensions, it is the same as scale-down. For images larger than the given dimensions, it is the same as cover. In GraphQL, CROP must be uppercase.

GraphQL format

RequestResponse

{
 media(id: "KTsF62Q4gg60q6WCsWJw8") {
  name
  url(
   transform: {
    fit: CROP,
   }
  )
 }
}

URL format

RequestResponse
// [!code word:<Base_URL>] 
// [!code word:<MEDIA_TENANT_ID>] 
// [!code word:<MEDIA_ITEM_ID>] 

<Base_URL>/api/media/v2/delivery/<MEDIA_TENANT_ID>/<MEDIA_ITEM_ID>?width=150&fit=crop&transform=true

gamma

Increases the image exposure by a factor, where a value of 1.0 equals no change, a value of 0.5 darkens the image, and a value of 2.0 lightens the image. 0 is ignored.

GraphQL format

RequestResponse

{
 media(id: "KTsF62Q4gg60q6WCsWJw8") {
  name
  url(
   transform: {
    gamma: 0.5,
   }
  )
 }
}

URL format

RequestResponse
// [!code word:<Base_URL>] 
// [!code word:<MEDIA_TENANT_ID>] 
// [!code word:<MEDIA_ITEM_ID>] 

<Base_URL>/api/media/v2/delivery/<MEDIA_TENANT_ID>/<MEDIA_ITEM_ID>?gamma=0.5&transform=true

gamma parameter result

gravity

Use when cropping an image with fit=cover or fit=crop. This parameter defines the side or point that should not be cropped.

Options are:

  • gravity=auto - selects a focal point based on saliency detection (using maximum symmetric surround algorithm).

  • gravity=side - a side (gravity=left, gravity=right, gravity=top, gravity=bottom) or coordinates specified on a scale from 0.0 (top or left) to 1.0 (bottom or right), 0.5 being the center. The X and Y coordinates must be separated by lowercase x in the URL. For example, 0x1 refers to the bottom left corner, 0.5x0.5 refers to the exact center, and 0.5x0.33 refers to a point in the top third of the image.

GraphQL format

RequestResponse

{
 media(id: "KTsF62Q4gg60q6WCsWJw8") {
  name
  url(
   transform: {
    gravity: { side: AUTO },
   }
  )
 }
}

URL format

RequestResponse
// [!code word:<Base_URL>] 
// [!code word:<MEDIA_TENANT_ID>] 
// [!code word:<MEDIA_ITEM_ID>] 

<Base_URL>/api/media/v2/delivery/<MEDIA_TENANT_ID>/<MEDIA_ITEM_ID>?gravity=right&fit=cover&height=150&width=100&transform=true

gravity parameter result

height

Sets the maximum height of the image in pixels. Exact behavior depends on the fit mode.

GraphQL format

RequestResponse

{
 media(id: "KTsF62Q4gg60q6WCsWJw8") {
  name
  url(
   transform: {
    height: 500,
   }
  )
 }
}

URL format

RequestResponse
// [!code word:<Base_URL>] 
// [!code word:<MEDIA_TENANT_ID>] 
// [!code word:<MEDIA_ITEM_ID>] 

<Base_URL>/api/media/v2/delivery/<MEDIA_TENANT_ID>/<MEDIA_ITEM_ID>?height=150&fit=cover&transform=true

rotate

Rotates the image by 90, 180, or 270 degrees.

GraphQL format

RequestResponse

{
 media(id: "KTsF62Q4gg60q6WCsWJw8") {
  name
  url(
   transform: {
    rotate: 90,
   }
  )
 }
}

URL format

RequestResponse
// [!code word:<Base_URL>] 
// [!code word:<MEDIA_TENANT_ID>] 
// [!code word:<MEDIA_ITEM_ID>] 

<Base_URL>/api/media/v2/delivery/<MEDIA_TENANT_ID>/<MEDIA_ITEM_ID>?rotate=90&transform=true

rotate parameter result

sharpen

Applies a sharpening filter to the entire image. The intensity of this filter is determined by the parameter value, which can range from 0 (none) to 10.

GraphQL format

RequestResponse

{
 media(id: "KTsF62Q4gg60q6WCsWJw8") {
  name
  url(
   transform: {
    sharpen: 8,
   }
  )
 }
}

URL format

RequestResponse
// [!code word:<Base URL>] 
// [!code word:<MEDIA_TENANT_ID>] 
// [!code word:<MEDIA_ITEM_ID>] 

<Base URL>/api/media/v2/delivery/<MEDIA_TENANT_ID>/<MEDIA_ITEM_ID>?sharpen=3&transform=true

trim

Trims one or more edges of the image by a specified number of pixels (top;right;bottom;left). This is done before any resizing or rotation of the image, and it takes DPR into account. In the following example, the top of the image is trimmed by 800 pixels.

GraphQL format

RequestResponse

{
 media(id: "KTsF62Q4gg60q6WCsWJw8") {
  name
  url(
   transform: {
    trim: { bottom: 128 },
   }
  )
 }
}

URL format

RequestResponse
// [!code word:<Base_URL>] 
// [!code word:<MEDIA_TENANT_ID>] 
// [!code word:<MEDIA_ITEM_ID>] 

<Base_URL>/api/media/v2/delivery/<MEDIA_TENANT_ID>/<MEDIA_ITEM_ID>?trim=800;0;0;0&transform=true

trim parameter result

width

Sets the maximum width of the image in pixels. Exact behavior depends on the fit mode.

GraphQL format

RequestResponse

{
 media(id: "KTsF62Q4gg60q6WCsWJw8") {
  name
  url(
   transform: {
    width: 100,
   }
  )
 }
}

URL format

RequestResponse
// [!code word:<Base_URL>] 
// [!code word:<MEDIA_TENANT_ID>] 
// [!code word:<MEDIA_ITEM_ID>] 

<Base_URL>/api/media/v2/delivery/<MEDIA_TENANT_ID>/<MEDIA_ITEM_ID>?width=50&fit=cover&transform=true

Do you have some feedback for us?

If you have suggestions for improving this article,