Transform image

The Image Transformation API allows you to apply various real-time transformations to your uploaded images. Below are the supported parameters, their usage, and examples.

Parameters

1. region

Description: Crops a specific region from the image.
Type: { left: number, top: number, width: number, height: number }
Example: /image.jpg?region=10,10,100,100
Example Image: → region (region=50,50,300,300)

2. resize

Description: Resizes the image to the specified dimensions.
Type: { width?: number, height?: number, fit?: "cover" | "contain" | "fill" | "inside" | "outside", resize?: "pct", background?: [number, number, number, number] }
Example: /image.jpg?w=200&h=100
Example Image: → width only (w=200) → width and height (w=200&h=100) → width and height with fit (w=200&h=100&fit=contain) → width and pct (resize=pct&w=50, 50% of original width) → width, height, fit, background (w=200&h=100&fit=contain&background=255,255,255,0)

3. rotation

Description: Rotates the image by the given degrees.
Type: number (degrees, e.g., 90, 180)
Example: /image.jpg?rotation=90
Example Image: →

4. color

Description: Adjusts image color properties such as brightness, contrast, and saturation.
Type: { color?: number, negate?: boolean, normalize?: boolean }
Example: /image.jpg?color=100,128,200&negate=true&normalize=true
Example Image: → color (color=100,128,200) → negate (negate=true) → normalize (normalize=true)

5. blur

Description: Applies a blur effect to the image.
Type: { blur?: number, sharpen?: number }
Example: /image.jpg?blur=5&sharpen=10
Example Image: → blur (blur=5) → sharpen (sharpen=10)

6. threshold

Description: Applies a threshold effect, converting the image to high-contrast black and white.
Type: number (threshold value)
Example: /image.jpg?threshold=128
Example Image: → threshold (threshold=128)

7. grayscale

Description: Converts the image to grayscale.
Type: boolean
Example: /image.jpg?grayscale=true
Example Image: → grayscale (grayscale=true)

Notes

If a parameter is omitted, the original image is used for that property.
Some combinations may not be supported for all image formats.
The order of transformations is: region → resize → rotation → color → blur → threshold → grayscale.

Error Handling

If an invalid parameter is provided, the original image is returned.
For large images or complex transformations, processing time may increase.

Limitation

Vector images(ex. .svg) are not supported. (Bitmaps are only supported.)
The maximum transformation image size is 1MB for Free Plan. (original image will be returned)
The maximum transformation time is 30 seconds for Free Plan. (original image will be returned)