# Asset transformations

This API reference document contains information on asset transformation, file conversion, validating and combining transforms, and alias transforms

## Overview

When fetching assets, you can pass an optional `transformation` argument to the `url` field.

**Note:**

If you want to find out which asset system your project uses and which section of this document applies to you, [click here](https://hygraph.com/classic-docs/api-reference/assets/assets-overview#which-asset-system-does-my-project-use).

## Hygraph Asset Management

### Auto image

This document transformation uses the `auto_image` parameter to determine which [mimetype](https://hygraph.com/classic-docs/api-reference/assets/transformations#file-type-conversion) to serve based on the browsers preference.

| Arg          | Description                                                                                                                                                                                                         |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auto_image` | Determines which mimetype to serve based on the browsers preference. We either send back a `webp` or an `avif`, depending on the **Accept** request header. Without an **Accept** header, we use `jpg` as fallback. |

For example:

  **Query**

```graphql
{
  assets {
    url(
      transformation: {
        document: {output: {format: autoImage}}
        }
      )
  }
}
```

  
  **Response**

```graphql
{
  "data": {
    "assets": [
      {
        "url": "https://REGION.graphassets.com/ENV_ID/auto_image/HANDLE"
      }
    ]
  }
}
```


### Blur

This transformation uses the `blur` parameter to blur your image.

| Arg      | Description                                                        |
| -------- | ------------------------------------------------------------------ |
| `amount` | Blur effect amount. The value must be an integer from `0` to `20`. |

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

  **Query**

```graphql
{
  assets {
    url(
      transformation: {
        image: { blur: {amount: 4} }
      }
    )
  }
}
```

  
  **Response**

```graphql
{
  "data": {
    "assets": [
      {
        "url": "https://REGION.graphassets.com/ENV_ID/blur=amount:4/HANDLE"
      }
    ]
  }
}
```


### Border

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

| Arg          | Description                                                                                                                    |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `width`      | Border width. The value must be an integer from `1` to `1000`.                                                                 |
| `color`      | Border color. The value must be a hexadecimal or shortened hexadecimal color code.                                             |
| `background` | Border color. The value must be a hexadecimal or shortened hexadecimal color code, or a supported color name. See table below. |

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

  **Query**

```graphql
{
  assets {
    url(
      transformation: {
        image: { border: {width: 2, color: "gray15", background: "azure"} }
      }
    )
  }
}
```

  
  **Response**

```graphql
{
  "data": {
    "assets": [
      {
        "url": "https://REGION.graphassets.com/ENV_ID/border=width:2,color:gray15,background:azure/HANDLE"
      }
    ]
  }
}
```


**Pro Tip:**

[Here's a list of color names and their corresponding HEX values](https://hygraph.com/classic-docs/api-reference/assets/border-hex-values) that you can use for your image borders.

### Compress

This transformation compresses PNG & JPG files.

| Arg        | Description                                                                                      |
| ---------- | ------------------------------------------------------------------------------------------------ |
| `compress` | Image compression. You can choose to compress the metadata as well by passing `true` or `false`. |

**Warning:**

- `compress` will only work on `jpg` and `png` file formats, otherwise it returns unchanged.
- Make compress the last transformation in your chain for better results.

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

  **Query**

```graphql
{
  assets {
    url(
      transformation: {
        image:{compress:{metadata:true}}
      }
    )
  }
}
```

  
  **Response**

```graphql
{
  "data": {
    "assets": [
      {
        "url": "https://REGION.graphassets.com/ENV_ID/compress=metadata:true/HANDLE"
      }
    ]
  }
}
```


### 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.

| Arg      | Description                                                                                    |
| -------- | ---------------------------------------------------------------------------------------------- |
| `x`      | The `x` coordinate of the image. The value must be an integer from `0` to `10000`.             |
| `y`      | The `y` coordinate of the image. The value must be an integer from `0` to `10000`.             |
| `width`  | The width in pixels to resize the image to. The value must be an integer from `1` to `10000`.  |
| `height` | The height in pixels to resize the image to. The value must be an integer from `1` to `10000`. |

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

  **Query**

```graphql
{
  assets {
    url(
      transformation: {
        image:{crop:{ x: 100, y: 200, width:300, height: 400 }}
      }
    )
  }
}
```

  
  **Response**

```graphql
{
  "data": {
    "assets": [
      {
        "createdAt": "2024-01-19T13:56:45.723049+00:00",
        "url": "https://REGION.graphassets.com/ENV_ID/crop=dim:[100,200,300,400]/HANDLE"
      }
    ]
  }
}
```


### Quality

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

| Arg     | Description                                                                     |
| ------- | ------------------------------------------------------------------------------- |
| `value` | The quality value of the image. The value must be an integer from `1` to `100`. |

**Note:**

- Only supported for the following formats `jpeg`, `jpg`, `webp`, `gif`, `heif`, `tiff`, `avif`
- You can use this transformation to reduce the file size of your image before a compress task.

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

  **Query**

```graphql
{
  assets {
    url(
      transformation: {
        image: { quality: {value: 50} }
      }
    )
  }
}
```

  
  **Response**

```graphql
{
  "data": {
    "assets": [
      {
        "url": "https://REGION.graphassets.com/ENV_ID/quality=value:50/HANDLE"
      }
    ]
  }
}
```


### Resize

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

The `image` takes the following arguments:

| Arg      | Type       | Description                                                                                                   |
| -------- | ---------- | ------------------------------------------------------------------------------------------------------------- |
| `width`  | `Int`      | The width in pixels to resize the image to. The value must be an integer from `1` to `10000`.                 |
| `height` | `Int`      | The height in pixels to resize the image to. The value must be an integer from `1` to `10000`.                |
| `fit`    | `ImageFit` | The default value for this parameter is `clip`. Check out the following table to look at all possible values. |

The `ImageFit` takes one of the following values:

| Value   | Description                                                                                                                                                                                          |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clip`  | Resizes the image to fit within the specified parameters without distorting, cropping, or changing the aspect ratio.                                                                                 |
| `crop`  | Resizes the image to fit the specified parameters exactly by removing any parts of the image that don't fit within the boundaries.                                                                   |
| `scale` | Resizes the image to fit the specified parameters exactly by scaling the image to the desired size. The aspect ratio of the image is not respected and the image can be distorted using this method. |
| `max`   | Resizes the image to fit within the parameters, but as opposed to `fit:clip` will not scale the image if the image is smaller than the output size.                                                  |

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

  **Query**

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

  
  **Response**

```graphql
{
  "data": {
    "assets": [
      {
        "url": "https://REGION.graphassets.com/ENV_ID/resize=fit:clip,height:50,width:50/HANDLE"
      }
    ]
  }
}
```


### Sharpen

This transformation uses the `sharpen` parameter to sharpen your image.

| Arg      | Description                                                           |
| -------- | --------------------------------------------------------------------- |
| `amount` | Sharpen effect amount. The value must be an integer from `0` to `20`. |

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

  **Query**

```graphql
{
  assets {
    url(
      transformation: {
        image: { sharpen: {amount: 2} }
      }
    )
  }
}
```

  
  **Response**

```graphql
{
  "data": {
    "assets": [
      {
        "url": "https://REGION.graphassets.com/ENV_ID/sharpen=amount:2/HANDLE"
      }
    ]
  }
}
```


### 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. In each case, it indicates whether it's possible - with a checkmark - or if it's not - with a cross.

| Input type | Available output formats                           | Mimetype          |
| ---------- | -------------------------------------------------- | ----------------- |
| `AVIF`     | `JPG`, `PNG`, `WEBP`, `GIF`, `TIFF`                | `image/avif`      |
| `BMP`      | `JPG`, `PNG`, `SVG`, `WEBP`, `GIF`, `TIFF`, `AVIF` | `image/bmp`       |
| `GIF`      | `JPG`, `PNG`, `SVG`, `WEBP`, `TIFF`, `AVIF`        | `image/gif`       |
| `JPG`      | `PNG`, `SVG`, `WEBP`, `GIF`, `TIFF`, `AVIF`        | `image/jpg`       |
| `PDF`      | `JPG`, `GIF`, `WEBP`, `TIFF`, `AVIF`               | `application/pdf` |
| `PNG`      | `JPG`, `SVG`, `WEBP`, `GIF`, `TIFF`, `AVIF`        | `image/png`       |
| `SVG`      | `JPG`, `PNG`, `WEBP`, `GIF`, `TIFF`, `AVIF`        | `image/svg+xml`   |
| `TIFF`     | `JPG`, `PNG`, `SVG`, `WEBP`, `GIF`, `AVIF`         | `image/tiff`      |
| `WEBP`     | `JPG`, `PNG`, `SVG`, `GIF`, `TIFF`, `AVIF`         | `image/webp`      |

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

  **Query**

```graphql
query Assets {
  assets {
    createdAt
    url(transformation: {document: {output: {format: jpg}}})
  }
}
```

  
  **Response**

```graphql
{
  "data": {
    "assets": [
      {
        "createdAt": "2024-01-19T13:56:45.723049+00:00",
        "url": "https://REGION.graphassets.com/ENV_ID/output=format:jpg/HANDLE"
      }
    ]
  }
}
```


### 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
```

## Legacy asset system

### Resize images

The `image` takes the following arguments:

| Arg      | Type       | Description                                                                                    |
| -------- | ---------- | ---------------------------------------------------------------------------------------------- |
| `width`  | `Int`      | The width in pixels to resize the image to. The value must be an integer from `1` to `10000`.  |
| `height` | `Int`      | The height in pixels to resize the image to. The value must be an integer from `1` to `10000`. |
| `fit`    | `ImageFit` | The default value for the fit parameter is `clip`.                                             |

The `ImageFit` takes one of the following values:

| Value   | Description                                                                                                                                                                                          |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clip`  | Resizes the image to fit within the specified parameters without distorting, cropping, or changing the aspect ratio.                                                                                 |
| `crop`  | Resizes the image to fit the specified parameters exactly by removing any parts of the image that don't fit within the boundaries.                                                                   |
| `scale` | Resizes the image to fit the specified parameters exactly by scaling the image to the desired size. The aspect ratio of the image is not respected and the image can be distorted using this method. |
| `max`   | Resizes the image to fit within the parameters, but as opposed to `fit:clip` will not scale the image if the image is smaller than the output size.                                                  |

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

```graphql
{
  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.

| Current file type | Available output formats                                         |
| ----------------- | ---------------------------------------------------------------- |
| PDF               | `jpg`, `odp`, `ods`, `odt`, `png`, `svg`, `txt`, `webp`          |
| DOC               | `docx`, `html`, `jpg`, `odt`, `pdf`, `png`, `svg`, `txt`, `webp` |
| DOCX              | `doc`, `html`, `jpg`, `odt`, `pdf`, `png`, `svg`, `txt`, `webp`  |
| ODT               | `doc`, `docx`, `html`, `jpg`, `pdf`, `png`, `svg`, `txt`, `webp` |
| XLS               | `jpg`, `pdf`, `ods`, `png`, `svg`, `xlsx`, `webp`                |
| XLSX              | `jpg`, `pdf`, `ods`, `png`, `svg`, `xls`, `webp`                 |
| ODS               | `jpg`, `pdf`, `png`, `xls`, `svg`, `xlsx`, `webp`                |
| PPT               | `jpg`, `odp`, `pdf`, `png`, `svg`, `pptx`, `webp`                |
| PPTX              | `jpg`, `odp`, `pdf`, `png`, `svg`, `ppt`, `webp`                 |
| ODP               | `jpg`, `pdf`, `png`, `ppt`, `svg`, `pptx`, `webp`                |
| BMP               | `jpg`, `odp`, `ods`, `odt`, `pdf`, `png`, `svg`, `webp`          |
| GIF               | `jpg`, `odp`, `ods`, `odt`, `pdf`, `png`, `svg`, `webp`          |
| JPG               | `jpg`, `odp`, `ods`, `odt`, `pdf`, `png`, `svg`, `webp`          |
| PNG               | `jpg`, `odp`, `ods`, `odt`, `pdf`, `png`, `svg`, `webp`          |
| WEBP              | `jpg`, `odp`, `ods`, `odt`, `pdf`, `png`, `svg`, `webp`          |
| TIFF              | `jpg`, `odp`, `ods`, `odt`, `pdf`, `png`, `svg`, `webp`          |
| AI                | `jpg`, `odp`, `ods`, `odt`, `pdf`, `png`, `svg`, `webp`          |
| PSD               | `jpg`, `odp`, `ods`, `odt`, `pdf`, `png`, `svg`, `webp`          |
| SVG               | `jpg`, `odp`, `ods`, `odt`, `pdf`, `png`, `webp`                 |
| HTML              | `jpg`, `odt`, `pdf`, `svg`, `txt`, `webp`                        |
| TXT               | `jpg`, `html`, `odt`, `pdf`, `svg`, `webp`                       |

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

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

## Validating 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 permitted.

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

## Combining transforms

It is possible to combine both transformation arguments:

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

## Alias transforms

[GraphQL aliases](https://hygraph.com/classic-docs/api-reference/content-api/queries#graphql-aliases) are great for querying the same asset url with multiple transformations.

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

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