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

# Product Images

> Resize, pad, and format-convert product images from Snappy's CDN by appending query parameters to any image URL.

Product images in Snappy are served from **`https://image.snappy.com`**. You can request resized, padded, or format-converted versions of any product image by appending query parameters to the image URL.

No API key is required to load these URLs - they are public CDN links suitable for use directly in `<img>` tags or your mobile app.

## Getting the image URL

Every product and variant in the Snappy catalog includes image metadata.

### V3 products

V3 returns images in the `media` array on products and variants. Each entry includes a `src` URL that already points at the image CDN:

```json theme={null}
{
  "id": "655277e68e0719000d6c3fd5",
  "title": "NFL 25-Layer StadiumView Wall Art",
  "media": [
    {
      "type": "image",
      "src": "https://image.snappy.com/o1xc17wfbda6cl91hm0r6"
    }
  ]
}
```

You can use the `src` value from the API as-is, or add query parameters to match the size and format your UI needs.

## URL format

```text theme={null}
https://image.snappy.com/{imageId}?width={px}&height={px}&format={format}&background={color}
```

All query parameters are optional. Omit any parameter you do not need.

**Example - square thumbnail with white padding:**

```text theme={null}
https://image.snappy.com/bnxjv94tmzq1w8eplk73ua?width=400&height=400&format=webp&background=white
```

**Example - scale to a fixed width:**

```text theme={null}
https://image.snappy.com/bnxjv94tmzq1w8eplk73ua?width=600&format=auto
```

***

## Query parameters

| Parameter    | Type    | Allowed values                                                              | Default | Required |
| :----------- | :------ | :-------------------------------------------------------------------------- | :------ | :------- |
| `width`      | integer | Any positive integer (snapped - see below)                                  | -       | No       |
| `height`     | integer | Any positive integer (snapped - see below)                                  | -       | No       |
| `format`     | string  | `jpg`, `png`, `webp`, `auto`                                                | `auto`  | No       |
| `background` | string  | `white`, `black`, `transparent`, or hex as `rgb:rrggbb` (e.g. `rgb:ff0000`) | `white` | No       |

<Note>
  **`background` is only applied when both `width` and `height` are provided.** In all other cases it is ignored.
</Note>

### Allowed sizes (snapping)

You can pass any positive integer for `width` and `height`. The CDN snaps your value to the allowed size before serving the image:

`100`, `200`, `300`, `400`, `500`, `600`, `800`, `1000`

For example, `width=99` is served as `100`, and `width=350` is served as `400`. This keeps cache efficiency high across all integrations using the same CDN.

If no transformation parameters are provided, the original image is returned unchanged.

***

## How transformations work

### Both `width` and `height` provided - pad to fit

When both dimensions are given, the image is **padded** (not cropped, not stretched) to fit the requested box. The original aspect ratio is preserved and empty space is filled with the `background` color.

This is the recommended mode for product cards and grids where the full product must remain visible.

```text theme={null}
width=400&height=400&background=white
```

### Only `width` or `height` provided - scale preserving ratio

When only one dimension is given, the image is scaled proportionally. The other dimension adjusts automatically. No padding, no cropping.

```text theme={null}
width=600
```

```text theme={null}
height=300
```

### Neither provided - format only

When no dimensions are given, only format conversion is applied (if `format` is set).

```text theme={null}
format=jpg
```

***

## Examples

| Use case                                      | URL                                                                                                       |
| :-------------------------------------------- | :-------------------------------------------------------------------------------------------------------- |
| Square card thumbnail (400 px, white padding) | `https://image.snappy.com/bnxjv94tmzq1w8eplk73ua?width=400&height=400&format=webp&background=white`       |
| Square with transparent padding               | `https://image.snappy.com/bnxjv94tmzq1w8eplk73ua?width=400&height=400&background=transparent&format=auto` |
| Fixed width, auto height                      | `https://image.snappy.com/bnxjv94tmzq1w8eplk73ua?width=600&format=auto`                                   |
| Fixed height, auto width                      | `https://image.snappy.com/bnxjv94tmzq1w8eplk73ua?height=300&format=auto`                                  |
| Convert to JPEG, no resize                    | `https://image.snappy.com/bnxjv94tmzq1w8eplk73ua?format=jpg`                                              |

***

## Recommended sizes by use case

| Size (px) | Typical use     |
| :-------- | :-------------- |
| 100       | Micro thumbnail |
| 200       | Small list item |
| 300       | Card            |
| 400       | Medium card     |
| 500       | Large card      |
| 600       | Hero thumbnail  |
| 800       | Grid image      |
| 1000      | Large display   |

Pick the size closest to your layout need - the snapping behavior ensures you land on one of these values automatically.

***

## Best practices

* **Use the first `media` image as the card thumbnail** when rendering product lists.
* **Prefer `format=webp` or `format=auto`** for web UIs to reduce payload size.
* **Use both `width` and `height` with `background`** when you need a consistent square or fixed-aspect container without cropping the product.
* **Reuse the same URL** across your app for the same size - identical URLs are served from CDN cache.