> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: URL Image Transformation

## Article: Image Transformation

## Article Link: https://dev.wix.com/docs/api-reference/assets/media/media-manager/url-image-transformation.md

## Article Content:

# URL-Based Image Transformation Reference

This reference provides URL-based image transformation parameters for images served by the [Media API](https://dev.wix.com/docs/api-reference/assets/media/media-manager/introduction.md). 
You can transform images by appending transformation parameters to Wix media URLs, allowing you to resize, crop, and change formats without additional processing.

> **Note:** For programmatic image manipulation in JavaScript apps, you can use the [Image-Kit](https://www.npmjs.com/package/@wix/image-kit) package instead of URL transformations. The package provides the same functionality with a JavaScript API and additional features like batch processing.

## Before you begin

It's important to note the following points before starting to code:

- Image transformations only work with Wix-hosted media URLs, `static.wixstatic.com`.
- URL-based transformations only work for public media files. 
- The backend applies transformations and caches them for performance.
- Invalid parameters return HTTP 400 errors with descriptive messages.

## URL transformation methods

You can transform images using 3 methods. Each method serves different use cases depending on your layout requirements.

### When to use each method

| Method | Use case | Behavior |
|--------|----------|----------|
| **Fit** | Preserve entire image in bounds | Scales image to fit dimensions, adds padding if needed |
| **Fill** | Fill container completely | Scales and crops image to fill exact dimensions |
| **Crop** | Extract specific image region | Cuts specified rectangular area from original image |

## Transformation parameters

### Fit transformation

Scales the image to fit in specified dimensions while preserving the original aspect ratio.

**URL format:** `"{{your-URL}}/v1/fit/w_{{width}},h_{{height}}/file.{{fileExtension}}"`

**Parameters:**
- `width`: Target width in pixels, 1-5000.
- `height`: Target height in pixels, 1-5000.
- `fileExtension`: Output format. For example, jpg, png, webp, gif.

**Example:**

`"https://static.wixstatic.com/media/11062b_58a1e9635ec6423f98b2f3407ccea943~mv2.jpeg/v1/fit/w_640,h_640/file.jpg"`

> **Note:** The fit transformation scales the image to the requested dimensions while keeping the original aspect ratio. The resulting image may be smaller than the requested dimensions if the aspect ratios differ. For example, a 1000x500 image requested at 1000x250 returns a 500x250 image. Also, images aren't scaled up beyond their original size, attempts to do so returns the original image.

### Fill transformation

Scales the image to completely fill specified dimensions while preserving the original aspect ratio. When aspect ratios differ, the system crops the image to fit.

**URL format:** `"{{your-URL}}/v1/fill/w_{{width}},h_{{height}}/file.{{fileExtension}}"`

**Parameters:**
- `width`: Target width in pixels, 1-5000.
- `height`: Target height in pixels, 1-5000.
- `fileExtension`: Output format. For example, jpg, png, webp, gif.

**Example:**

`"https://static.wixstatic.com/media/11062b_58a1e9635ec6423f98b2f3407ccea943~mv2.jpeg/v1/fill/w_640,h_640/file.jpg"`

> **Note:** When the target dimensions have a different aspect ratio than the source image, the system crops the image from the center to fill the specified dimensions exactly.

### Crop transformation

Extracts a rectangular region from the original image starting at specified coordinates. The coordinate system uses the top-left corner as origin (0,0), with x increasing rightward and y increasing downward.

**URL format:** `"{{your-URL}}/v1/crop/x_{{xStartingPosition}},y_{{yStartingPosition}},w_{{width}},h_{{height}}/file.{{fileExtension}}"`

**Parameters:**
- `xStartingPosition`: Left edge coordinate in pixels, from 0 to image width.
- `yStartingPosition`: Top edge coordinate in pixels, from 0 to image height.  
- `width`: Target width in pixels, 1-5000.
- `height`: Target height in pixels, 1-5000.
- `fileExtension`: Output format. For example, jpg, png, webp, gif.

**Example:**

`"https://static.wixstatic.com/media/11062b_58a1e9635ec6423f98b2f3407ccea943~mv2.jpeg/v1/crop/x_1000,y_100,w_1500,h_1500/file.webp"`

> **Note:** All coordinate and dimension parameters must be in the image bounds. If any parameter exceeds the original image dimensions, the request returns an HTTP 400 error.

## Supported file formats

| Extension | Format | Use case                                  |
|-----------|--------|-------------------------------------------|
| `jpg`     | JPEG   | Photographs, images with many colors      |
| `png`     | PNG    | Images with transparency, simple graphics |
| `webp`    | WebP   | Modern format with better compression     |
| `gif`     | GIF    | Simple animations, limited color images   |

## Error responses

Invalid transformation requests return HTTP 400 status with error details:

| Error condition                                          | HTTP status | Response                                                                                                                                                                                                                  |
|----------------------------------------------------------|-------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Crop out of bounds (xStartingPosition/yStartingPosition) | 400         | `width/height must be greater than 0`                                                                                                                                                                                     |
| Missing required param                                   | 400         | `missing {paramName}`                                                                                                                                                                                                     |
| Requesting unsupported dimensions                        | 400         | <li>webp - `webp supports up to 16383 pixels on each dimension`</li><br/><li>gif, jpg, png - `output area (total pixels) must not exceed 33177600 ( requested: w:22894,h:10000, frame multiply:1, total: 228940000)`</li> |