# Source: https://docs.pinata.cloud/gateways/image-optimizations.md

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Image Optimizations

Pinata image optimizations provides image optimization functionality directly through your [Gateway](/gateways/retrieving-files). These capabilities that can significantly improve the load time and experience when viewing image content.

## Usage

To use image optimizations on files you've uploaded simply add on the queries listed in the [reference](#reference) to your full Gateway url, which might look something like this:

```
https://example-gateway.mypinata.cloud/files/{cid}?img-width=500&img-height=500
```

There are differences when using image optmizations for public files vs private files, so be sure to visit the [retrieving files](/gateways/retrieving-files) for more information!

## Reference

At least one option must be specified. Options are comma-separated (spaces are not allowed anywhere). Names of options can be specified in full or abbreviated.

<ParamField query="img-width" type="string">
  Specifies maximum width of the image in pixels. Exact behavior depends on the fit mode (described below).
</ParamField>

<ParamField query="img-height" type="string">
  Specifies maximum height of the image in pixels. Exact behavior depends on the fit mode (described below).
</ParamField>

<ParamField query="img-dpr=x" type="string">
  Device Pixel Ratio. Default 1. Multiplier for width/height that makes it easier to specify higher-DPI sizes in .
</ParamField>

<ParamField query="img-fit" type="string">
  Affects interpretation of width and height. All resizing modes preserve aspect ratio. Available modes are:

  * `img-fit=scale-down` Image will be shrunk in size to fully fit within the given width or height, but won’t be enlarged.

  * `img-fit=contain` Image will be resized (shrunk or enlarged) to be as large as possible within the given width or height while preserving the aspect ratio.

  * `img-fit=cover` Image will be resized to exactly fill the entire area specified by width and height, and will cropped if necessary.

  * `img-fit=crop` Image will be shrunk and cropped to fit within the area specified by width and height. The image won’t be enlarged. For images smaller than the given dimensions it’s the same as scale-down. For images larger than the given dimensions, it’s the same as cover.

  * `img-fit=pad` Image will be resized (shrunk or enlarged) to be as large as possible within the given width or height while preserving the aspect ratio, and the extra area will be filled with a background color (white by default). Transparent background may be very expensive, and it’s better to use fit=contain and CSS object-fit: contain property instead.
</ParamField>

<ParamField query="img-gravity" type="string">
  When cropping with `fit=cover`, specifies the most important side or point in the image that shouldn’t be cropped off.

  * `img-gravity=auto` The point will be guessed by looking for areas that stand out the most from image background

  * `img-gravity=side` and `img-gravity=XxY`
    If a side (left, right, top, 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 are separated by lowercase x, e.g. 0x1 means left and bottom, 0.5x0.5 is the center, 0.5x0.33 is a point in the top third of the image.
</ParamField>

<ParamField query="img-quality" type="string">
  Specifies quality for images in JPEG, WebP and AVIF formats. The quality is in 1-100 scale, but useful values are between 50 (low quality, small file size) and 90 (high quality, large file size). 85 is the default. When using the PNG format, an explicit quality setting allows use of PNG8 (palette) variant of the format.
</ParamField>

<ParamField query="img-format" type="string" default="auto">
  Allows serving of the WebP format to browsers that support it. If this option is not specified, a standard format like JPEG or PNG will be used.
</ParamField>

<ParamField query="img-anim" type="string">
  Reduces animations to still images. This setting is recommended to avoid surprisingly large animGIF files, or flashing images.
</ParamField>

<ParamField query="img-sharpen" type="string">
  Specifies strength of sharpening filter. The value is a floating-point number between 0 (no sharpening) and 10 (max). 1 is a recommended value.
</ParamField>

<ParamField query="img-onerror" type="string">
  In case of a fatal error that prevents the image from being resized use `img-onerror=redirect` to redirect to the unresized source image URL. This may be useful in case some images require user authentication and cannot be fetched. This option shouldn’t be used if the source images may be very large. This option is ignored if the image is from another domain (subdomains are OK).

  * `img-onerror=redirect` Redirects to original source url
</ParamField>

<ParamField query="img-metadata" type="string">
  Controls amount of invisible metadata (EXIF data) that should be preserved. Color profiles and EXIF rotation are applied to the image even if the metadata is discarded. Note that if the Polish feature is enabled, all metadata may have been removed already and this option may have no effect.

  * `img-metadata=keep` Preserve most of the image metadata (including GPS location) when possible.

  * `img-metadata=copyright` Discard all metadata except EXIF copyright tag. This is the default for JPEG images. img-metadata=none Discard all invisible metadata.
</ParamField>

## Formats and limitations

Read JPEG, PNG, GIF (including animations), and WebP images. SVG is not supported, since this format is inherently scalable and does not need resizing. Resize and generate JPEG and PNG images, and optionally AVIF or WebP. AVIF format is supported on a best-effort basis. Images that cannot be compressed as AVIF will be served as WebP instead.

## SDK Method Reference

Image Optimizations are built into both [`get`](/sdk/gateways/public/get) and [`createAccessLink`](/sdk/gateways/private/create-access-link) methods of the SDK.

```typescript  theme={null}
type OptimizeImageOptions = {
  width?: number;
  height?: number;
  dpr?: number;
  fit?: "scaleDown" | "contain" | "cover" | "crop" | "pad";
  gravity?: "auto" | "side" | string;
  quality?: number;
  format?: "auto" | "webp";
  animation?: boolean;
  sharpen?: number;
  onError?: boolean;
  metadata?: "keep" | "copyright" | "none";
};
```

```typescript  theme={null}
const data = await pinata.gateways.public
  .get("bafkreih5aznjvttude6c3wbvqeebb6rlx5wkbzyppv7garjiubll2ceym4")
  .optimizeImage({
    width: 500,
    height: 500,
    format: "webp"
  })
```