ImageKit let's you manipulate images on-the-fly using URL-based transformations. You can resize, crop, rotate, and apply various other transformations to images using simple URL parameters.
Basic example
Here's the basic structure of a URL-based image transformation:
URL endpoint transformation image path ┌──────────────────────────┐┌────────────┐┌────────────────┐ https://ik.imagekit.io/demo/tr:w-300,h-300/example-asset.jpg
Let's see a basic resizing example. We will add transformation parameter to the below image URL:
https://ik.imagekit.io/ikmedia/docs_images/examples/example_fashion_1.jpg
Image transformation overview
Overview of different image transformations available in ImageKit.
- Basic image resizing and cropping. Learn different crop modes and AI-powered smart cropping to adapt images for different layouts.
- AI-based object-aware and smart cropping to generate images that focus on the main subject.
- Adding text and image overlays. Learn more.
- Image enhancements like sharpening, contrast stretching, gradient, shadow effect, and other common operations. Learn more.
- Convert GIF to videos, SVG rasterization, and other operations on vector formats like PSD, AI, EPS, and PDF files. Learn more.
- Conditional transformations. Learn more.
Limits and supported image formats
Refer to supported image formats for a list of image formats supported by ImageKit.io for transformations. Check out various limits.
Expensive transformation limits
By default, we do not charge for transformations when you use ImageKit.io. However, if an account extensively uses expensive transformations such as AVIF conversion, complex text or image overlays, smart crop, or other AI-related transformations, in that case, our sales team may reach out to explore alternative options. Those options include upgrading to a custom plan that fits the usage pattern, helping you bring down the unique transformation count, or even migrating off our platform if ImageKit is not the right fit for your requirements. Please note that over 99% of the customers do not face these limitations.
Client Hints
Client hints are the hints provided by the client device to the server along with the request itself. These hints allow the server to fulfill a particular request with the most optimal resource.
Client hints provide this information via HTTP request headers. For example,
You can learn more about client hints from the responsive image guide.
Enable client hints before using them
Not every request has these HTTP headers. You will have to explicitly tell the browser to include these client hints using a meta tag:
<meta http-equiv="Accept-CH" content="Sec-CH-DPR, Sec-CH-Width">
ImageKit supports the following standard client hints:
To allow ImageKit to read values from the client hint request headers (DPR and Width), you have to set dpr and width to auto in transformation parameters.
For example, when the browser requests:
GET: https://ik.imagekit.io/your_imagekitid/tr:w-100,dpr-auto/image_name.jpg Sec-CH-DPR: 2
In this case, an extrinsic width of 100 pixels is required. To calculate the extrinsic width of the to-be-delivered image, ImageKit reads the client hint header Sec-CH-DPR value and multiplies it with the specified extrinsic width. Therefore, the final actual width of the delivered image is 200.
100 * 2 = 200 px
If the browser requests:
https://ik.imagekit.io/your_imagekitid/tr:w-auto,dpr-auto/image_name.jpg Sec-CH-DPR: 2 Sec-CH-Width: 600
In this case, an intrinsic size of 600 pixels is required. The browser sends Sec-CH-Width request header and also considers the DPR of the user-device while calculating the value of Sec-CH-Width header. Therefore, ImageKit ignores the Sec-CH-DPR value and delivers an image of width 600. ImageKit will return Content-DPR response header so that browser can scale the image correctly.
The Content-DPR Header
ImageKit rounds the intrinsic size of the image to the next smallest 100. If the Sec-CH-Widthheader indicates a width of 150 px, then ImageKit will deliver an image with a width of 200 px.
Now, if the DPR of the device is 2, then the device will end up rendering an image of width 100 px (200 / 2), which is the incorrect width. The correct intended width to be displayed is 75px (150 / 2). To rectify this miscalculation due to the rounding to the next 100, the Content-DPR header is used.
Content-DPR is a response header and indicates the actual DPR of the response image. It is calculated as follows:
Content-DPR = [Selected Image Size] / (Width / DPR)
Let's learn this with a few examples:
GET: https://ik.imagekit.io/your_imagekitid/tr:w-auto,dpr-auto/image_name.jpg Sec-CH-DPR: 2 Sec-CH-Width: 212
ImageKit rounds off 212 to 300, and an image of width 300 pixels is delivered. Now, the Content-DPR header is calculated as follows:
Content-DPR = 300/ (212 / 2) = 2.83
Hence, ImageKit responds with a 300 pixel wide image and Content-DPR response header with a value 2.83
Content-DPR: 2.83
When the browser receives the image and the header, it scales it down to 300 / 2.83 = 106 px, which is the intended final width of the rendered image. If there were no Content-DPR header received, the browser would scale down the image as 300 / 2 = 150 px, which might break your layout.
WebP conversion using Accept header is enabled by default and part of the automatic image format conversion.
Default image - (di)
When an image that is requested using ImageKit.io does not exist, a 404 error is displayed. In certain scenarios, you would want a default image to be delivered instead of the 404 error message.
ImageKit.io provides an alternative to achieve this without having to make changes at the application level using this parameter. The image specified in this parameter should be accessible using the default endpoint of your ImageKit.io account.
If the default image is nested inside multiple folders, then you need to specify the entire default image path in this parameter. Replace
/with@@in the default image path. For example, if the default image is accessible onhttps://ik.imagekit.io/ikmedia/path/to/image.jpg, then thediparameter should bedi-@@path@@to@@image.jpg.