URL-Based Image Transformation Reference

This reference provides URL-based image transformation parameters for images served by the Media API. You can transform images by appending transformation parameters to Wix media URLs, allowing you to resize, crop, and change formats without additional 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"

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"

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"

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
Invalid dimensions	400	{"error": "Invalid dimensions: width and height must be 1-5000"}
Crop out of bounds	400	{"error": "Crop parameters exceed image boundaries"}
Unsupported format	400	{"error": "Unsupported file format: {format}"}
Invalid URL structure	400	{"error": "Invalid media URL format"}