When fetching assets, you can pass an optional transformation argument to the url field. Transformation safeguards apply to certain transformation parameters. Requests that exceed a safeguard return 400 Bad Request with an explicit error message.

#Hygraph Asset Management

#Auto image

This document transformation uses the auto_image parameter to determine which mimetype to serve based on the browsers preference.

For example:

#Blur

This transformation uses the blur parameter to blur your image.

For example, we can query all assets, and blur images to an amount of 4:

#Border

This transformation uses the border parameter to control the width, color and background of your image borders.

For example, we can query all assets, and set the image borders using our chosen characteristics:

#Compress

This transformation compresses PNG & JPG files.

For example, we can query all assets, and compress images along with their metadata:

#Crop

This transformation uses the crop parameter to crop images by entering coordinates and crop dimensions:

• The starting points for X and Y coordinates are [0,0], aligning with the top-left corner of the image.
• The width and height parameters determine the size in pixels of the cropping rectangle. The output will include only the portion of the image within the designated crop area.

For example, we can query all assets, and crop images:

#Quality

Use the quality parameter to set the quality of your image without risking generating a larger file.

For example, we can query all assets, and set the image quality to 50:

#Resize

This transformation uses the resize parameter to adjust the image height, width and fit.

The image takes the following arguments:

The ImageFit takes one of the following values:

For example, we can query all assets, and resize images:

#Sharpen

This transformation uses the sharpen parameter to sharpen your image.

For example, we can query all assets, and sharpen images to an amount of 2:

#File type conversion

The following table shows the original file type you'd be changing from, and the possible formats you'd change it into.

For example, we can query all assets, and convert the images to JPG:

#URL transformations

It is possible to do URL transformations without using the API. You can do this by using the regular URL of an asset and then placing the transformation syntax in it.

You would place the transformation here:

https://REGION.graphassets.dev/ENV_ID/<Transformations go here>/HANDLE

The following example uses resize:

https://REGION.graphassets.dev/ENV_ID/resize=width:400,height:400/HANDLE

You can also chain the transformations. The following example uses resize and sharpen:

https://REGION.graphassets.dev/ENV_ID/resize=width:400,height:400/sharpen=amount:2/HANDLE

#Transformation safeguards

Hygraph applies safeguards on certain transformation parameters. A request that exceeds a safeguard returns 400 Bad Request. The response body always starts with Asset transformation safeguard exceeded: followed by the specific reason. This applies to both GraphQL url(transformation: {...}) queries and direct URL transformations.

#Resize safeguards

resize.width and resize.height are each capped at 10000 px. The value 10000 is accepted, any value above 10000 is rejected.

For example, resize=width:15000 returns Asset transformation safeguard exceeded: resize width 15000 must not exceed 10000

#Multi-page asset safeguards

Multi-page assets include animated image formats and multi-page documents such as animated GIF, animated WebP, APNG, animated AVIF/HEIC/HEIF, multi-page TIFF, and PDF.

The following safeguards apply to all multi-page assets:

A request must satisfy all three safeguards. A request within the 2000 px dimension safeguards can still be rejected if it upscales the original by more than 3.0x.

Example response bodies:

• Asset transformation safeguard exceeded: multi-page width 3000 must not exceed 2000 for gif
• Asset transformation safeguard exceeded: multi-page upscaling factor 15.00 exceeds 3.00 for avif

#Per-transformation repetition cap

Each transformation kind can appear at most 3 times in a single transformation URL. This safeguard is per kind, not per total transformation count.

The counted kinds are: resize, output, blur, sharpen, border, quality, crop, compress, and cache.

A URL containing four resize transformations returns Asset transformation safeguard exceeded: transformation kind - resize with value 4 exceeded its default limit: 3

#Validate transforms

We provide a validation field you can enable to check the combination of transform arguments are valid.

For example, you may query a video, and request to change the file type to PDF. validateOptions: true will warn you that this is not allowed.

{
  assets {
    url(
      transformation: {
        document: { output: { format: pdf } }
        validateOptions: true
      }
    )
  }
}

#Combine transforms

It is possible to combine both transformation arguments:

{
  assets {
    url(
      transformation: {
        image: { resize: { width: 50, height: 50, fit: clip } }
        document: { output: { format: png } }
        validateOptions: true
      }
    )
  }
}

#Alias transforms

GraphQL aliases are great for querying the same asset URL with multiple transformations.

For example, you could transform product images to include a thumbnail.

{
  products {
    images {
      thumbnail: url(
        transformation: {
          image: { resize: { width: 50, height: 50, fit: clip } }
          document: { output: { format: png } }
        }
      )
      url(transformation: { document: { output: { format: png } } })
    }
  }
}

#Legacy asset system

#Resize images

The image takes the following arguments:

The ImageFit takes one of the following values:

For example, we can query all assets, and resize images:

{
  assets {
    url(
      transformation: {
        image: { resize: { width: 50, height: 50, fit: clip } }
      }
    )
  }
}

#Convert file type

Depending on the asset type you're dealing with, it's possible to transform the output to another file type by passing a format value.

For example, let's transform all assets to PDFs:

{
  assets {
    url(transformation: { document: { output: { format: pdf } } })
  }
}