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).
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
{
media(id: "KTsF62Q4gg60q6WCsWJw8") {
name
url(
transform: {
background: "red",
}
)
}
}
URL format
<Base_URL>/api/media/v2/delivery/<MEDIA_TENANT_ID>/<MEDIA_ITEM_ID>?background=red&transform=true
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
{
media(id: "KTsF62Q4gg60q6WCsWJw8") {
name
url(
transform: {
blur: 50,
}
)
}
}
URL format
<Base_URL>/api/media/v2/delivery/<MEDIA_TENANT_ID>/<MEDIA_ITEM_ID>?blur=50&transform=true
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
{
media(id: "KTsF62Q4gg60q6WCsWJw8") {
name
url(
transform: {
brightness: 5.0,
}
)
}
}
URL format
<Base_URL>/api/media/v2/delivery/<MEDIA_TENANT_ID>/<MEDIA_ITEM_ID>?brightness=2.0&transform=true
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
{
media(id: "KTsF62Q4gg60q6WCsWJw8") {
name
url(
transform: {
compression: FAST,
}
)
}
}
URL format
<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
{
media(id: "KTsF62Q4gg60q6WCsWJw8") {
name
url(
transform: {
contrast: 0.5,
}
)
}
}
URL format
<Base_URL>/api/media/v2/delivery/<MEDIA_TENANT_ID>/<MEDIA_ITEM_ID>?contrast=0.5&transform=true
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
{
media(id: "KTsF62Q4gg60q6WCsWJw8") {
name
url(
transform: {
dpr: 2,
}
)
}
}
URL format
<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 ishttps://mms-delivery-beta.sitecorecloud.io/api/media/v2/delivery/<media tenant ID>/<media item ID>?width=250&fit=scale-down&transform=true. In GraphQL,SCALEDOWNmust 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,CONTAINmust 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,CROPmust be uppercase.
GraphQL format
{
media(id: "KTsF62Q4gg60q6WCsWJw8") {
name
url(
transform: {
fit: CROP,
}
)
}
}
URL format
<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
{
media(id: "KTsF62Q4gg60q6WCsWJw8") {
name
url(
transform: {
gamma: 0.5,
}
)
}
}
URL format
<Base_URL>/api/media/v2/delivery/<MEDIA_TENANT_ID>/<MEDIA_ITEM_ID>?gamma=0.5&transform=true
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.5being the center. The X and Y coordinates must be separated by lowercase x in the URL. For example,0x1refers to the bottom left corner,0.5x0.5refers to the exact center, and 0.5x0.33 refers to a point in the top third of the image.
GraphQL format
{
media(id: "KTsF62Q4gg60q6WCsWJw8") {
name
url(
transform: {
gravity: { side: AUTO },
}
)
}
}
URL format
<Base_URL>/api/media/v2/delivery/<MEDIA_TENANT_ID>/<MEDIA_ITEM_ID>?gravity=right&fit=cover&height=150&width=100&transform=true
height
Sets the maximum height of the image in pixels. Exact behavior depends on the fit mode.
GraphQL format
{
media(id: "KTsF62Q4gg60q6WCsWJw8") {
name
url(
transform: {
height: 500,
}
)
}
}
URL format
<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
{
media(id: "KTsF62Q4gg60q6WCsWJw8") {
name
url(
transform: {
rotate: 90,
}
)
}
}
URL format
<Base_URL>/api/media/v2/delivery/<MEDIA_TENANT_ID>/<MEDIA_ITEM_ID>?rotate=90&transform=true
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
{
media(id: "KTsF62Q4gg60q6WCsWJw8") {
name
url(
transform: {
sharpen: 8,
}
)
}
}
URL format
<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
{
media(id: "KTsF62Q4gg60q6WCsWJw8") {
name
url(
transform: {
trim: { bottom: 128 },
}
)
}
}
URL format
<Base_URL>/api/media/v2/delivery/<MEDIA_TENANT_ID>/<MEDIA_ITEM_ID>?trim=800;0;0;0&transform=true
width
Sets the maximum width of the image in pixels. Exact behavior depends on the fit mode.
GraphQL format
{
media(id: "KTsF62Q4gg60q6WCsWJw8") {
name
url(
transform: {
width: 100,
}
)
}
}
URL format
<Base_URL>/api/media/v2/delivery/<MEDIA_TENANT_ID>/<MEDIA_ITEM_ID>?width=50&fit=cover&transform=true