Getting Started

Images make up a critical part of all websites and mobile applications these days. They are the center pieces of a great product and user experience. Managing your images and delivering the perfect image, tailored and optimised for your user’s device, is therefore more critical than it has ever been. However this takes up a lot of development and maintenance time that could have otherwise been used in building your core product. This is where ImageKit can excel.

ImageKit is a ready to use cloud-based CDN, image server, manipulation engine and storage for website and mobile app developers. You can get started with ImageKit in a few minutes and get up to 50% improvement in image load time as soon as you switch to ImageKit.

ImageKit helps deliver highly optimised images on your websites and mobile apps without worrying about setting up or maintaining your own image delivery and transformation infrastructure. You can plug your existing image storages or servers to your ImageKit account or upload new images directly to your ImageKit Media Library. All images, original or transformed, new or old, are delivered from our high-performance servers and distributed using a global CDN network.

Imagekit ID

Use of ImageKit ID to access images:

    <!-- if the ImageKit ID is demo -->

    <!-- 'demo' appears in the path in path-based URLs -->
    https://ik.imagekit.io/demo/path/to/your/image.jpg 

    <!-- 'demo' appears in the subdomain in subdomain-based URLs -->
    https://demo.imagekit.io/path/to/your/image.jpg

To start using ImageKit, you would first need to create an account with ImageKit. During registration, you would be asked to choose your ImageKit ID. Consider this like a username that is unique across all ImageKit accounts. This ImageKit ID acts as a unique identifier in the URLs that will be used to access your images.

After you login, your ImageKit Id is displayed with the logged-in user’s name on your dashboard (top-right corner).

Let’s say your ImageKit ID is mycompany. This ImageKit ID can be used in two ways to access your images

Path-based URLs (accessible on free and paid pricing plans)
Subdomain-based URLs (accessible only on paid pricing plans)

ImageKit Media Library

Accessing the default image:


    <!-- Replace 'demo' with your ImageKit ID -->
    https://ik.imagekit.io/demo/default-image.jpg

As soon as you sign up with ImageKit, you get access to an image storage or Media Library. You can access it by going to the Media Library section of your dashboard. The size of the storage may vary on your pricing plan.

To get you started, a default image, default-image.jpg, is added to your ImageKit Media Library which can be accessed using the URL given in the code sample.

You can upload images to this storage from the Media Library section in the dashboard or using the upload APIs. All the images uploaded to your ImageKit Media Library are immediately accessible using your ImageKit ID in the URL.

CDN

All your images are delivered using a global CDN network, coupled with our powerful image servers. To ensure that you get the best possible quality optimizations and caching performance as soon as you switch to ImageKit, the CDN is preconfigured with certain default settings.

For paid plan users, it is advisable to always use subdomain-based URLs versus path-based URLs to access images (as specified here). The subdomain-based URLs give you access to a private CDN distribution whereas path-based URLs use a shared CDN distribution.

Existing Image Migration

Apart from your the ImageKit Media Library, you might have images that are currently being used on your website or mobile app. To use all the features of ImageKit on all your images, including the existing ones, the images must be accessed using ImageKit.

Your images may be spread across multiple image origins - servers or storages. And because it is virtually impossible to confidently migrate all your existing images from your existing image servers or storage to ImageKit, we have made the migration simpler with our Plug-and-Play techology.

This is the best possbile way of integrating ImageKit with your existing image origins. With this you can plug all your existing image origins to your ImageKit account and start getting all the benefits of ImageKit on your existing images instantly. No additional migration effort at all.

Migration and integration related options are available under the Integration section in your dashboard. First the general concept of origins and patterns, the two key components of Plug-and-Play technology, has been explained, followed by the actual steps of integration.

Image Origins

An origin is basically any storage or web server which you might be using for images on your website or app.

Currently, the following image origins can be added to your ImageKit account

AWS S3 Bucket / Folder
A Web server
Cloudinary Backup Bucket (Contact ImageKit team for this)

Once you add an origin to your ImageKit account, all images from that image origin, regardless of date of creation or size, would automatically be accessible using ImageKit URLs. All transformations and optimizations would work on all these images like they do for every other image. URL creation for images from these origins is very simple and has been explained later in the examples section.

Once an image from one of your added origins is accessed using an ImageKit URL, the image (and its transform, if any) is automatically moved to your media library. You would then be able to view this image in the Media Library section of your dashboard. This not only allows on-the-fly migration of images, you can always be sure that you would never miss out on any image during migration. Also, since transforming and optimizing an image is a costly operation, saving an image to your media library is always done for performance considerations.

The media library is the default origin for your ImageKit account and can be used to store and deliver images even if you don’t add any other origin of images.

URL Patterns

A URL pattern is any unique, customisable identifier that will appear in your image URL to identify the origins from which the image has to be fetched.

Your ImageKit account comes with a default / or empty URL pattern. In case you missed it earlier, the URL of the default image that is added to your media library, https://ik.imagekit.io/demo/default-image.jpg, contains / after the ImageKit ID in the URL. That is the default URL Pattern.

The purpose of a pattern is to identify the origins from which the image will be fetched. Any image origin that you add to your account, would become accessible using the / URL pattern. You can alter the order of preference in which these image origins will be hit by / or any other URL pattern that you create. / URL pattern cannot be deleted.

A single URL pattern can be configured to fetch an image from multiple image origins or multiple URL patterns can be setup, each one for an individual origin. In case of multiple origins against a single URL pattern, ImageKit attempts to retrieve the image from each of the origins sequentially. Since the media library is the default origin of images for all ImageKit accounts, it is always checked first for any image request.

Adding an image origin

Adding an AWS S3 Bucket or Folder as an origin

Go to the “Integration” section in your dashboard. Click on the “Add Origin” button.
In the form that opens up, select “Amazon S3 Bucket” as the origin type.
In the “Origin Name” field, enter any name for this new origin like “MyS3Images”. The origin name is just for you to easily identify an origin.
Enter your S3 bucket’s name in the “S3 Bucket Name” field.
Inside your S3 Bucket, let’s say all the images are in the /media/images path. So instead of repeating /media/images in every image URL, you can mention this in the “S3 Bucket Prefix” field. This way, not only does the URL become shorter, you also restrict the folders in your bucket that can be accessed via ImageKit. If you want your entire bucket to be accessible, enter “/” as the bucket prefix.
ImageKit needs to be given access to read images from your bucket. To do this, you must create a new AWS user for ImageKit and provide only read-only to the S3 bucket you want to add. Generate the access and secret keys for this user in AWS and enter those generated keys in the respective fields in the add origin form.
Click on “Save” and all the images inside your S3 bucket at the specified S3 prefix would become accessible using ImageKit.
Example - Your bucket name is ‘myimages’ and an image inside that bucket is available at /media/images/small/aws_image.jpg path. You can enter /media/images as the bucket prefix. Then your image will be accessible at https://ik.imagekit.io/<imagekitId>/small/aws_image.jpg. Whatever appears after / in the ImageKit URL is added to your bucket prefix for access.

Adding a web server as an origin

Go to the migration section in your dashboard. Click on the “Add Origin” button.
In the form that opens up, select “Web Server” as the type.
In the “Origin Name” field, enter any name for this new origin like “MyImages”. The origin name is just for you to easily identify an origin.
Let’s say you currently access your images at https://www.mywebsite.com/images/webserver_image.png. Then in the “Base URL” field you can enter https://www.mywebsite.com. The remainder of the path i.e. /images/webserver_image.png would appear in the new ImageKit URL. If you want to restrict ImageKit’s access to only the /images path on your server, then https://www.mywebsite.com/images will be the base URL and only webserver_image.png would appear in the new URL.
Example - You orignally access your images using https://www.mywebsite.com/images/webserver_image.png. The Base URL is https://www.mywebsite.com/images. Then the new ImageKit URL would be https://ik.imagekit.io/<imagekitId>/webserver_image.png. Whatever appears after “ in the ImageKit URL is added to your base URL for access.

Editing an Origin

An "Edit” link appears when you hover on the origin in the origin list. Clicking on that link will open up a form with values corresponding to that origin. After editing the values, click on “Save” to save those changes. Changes to your origin will reflect immediately for fresh images.

Adding a URL pattern

Any origin that you add will be accessible using the / URL pattern by default. However you can create a new URL pattern as well that is bound to one or few specific image origins.

Go to the Integration section in your dashboard. Click on the “Add Pattern” button.
In the form that opens up, enter the pattern that you want in the “URL Pattern Prefix” field. A pattern name can only consist of alphabets, numbers and hyphen. So “images”, “my-images”, “2007-images” etc are valid pattern names.
In the description field, you can enter any thing that will help you identify the purpose of the URL pattern
The first origin is always ImageKit Media Library and cannot be changed. You can start selecting your origins starting from the 2nd origin preference. The origins are checked for an image in the same preference order that you specify here.
The origins that you have added will appear in a dropdown when you click on any of the preference fields. Ensure that while selcting the origins, you don’t repeat the same origin twice in the preference order.
If you don’t want to provide all the preference options, you should leave them blank or “None”.
Example - Let’s say you have 3 image origins - s3-images-1, s3-images-2 and web-images-1 - and want to create a new URL pattern just for your S3 Images. Then in the add pattern form, you can use the pattern name as s3-images and add s3-images-1 in the second preference field and s3-images-2 in the third preference field. Leave the other preference options blank or “None”. The new pattern would then look for images in ImageKit media library, s3-images-1 and s3-images-2 in this preference order.

Editing a URL pattern

An “Edit” link appears when you hover on the pattern in the pattern list. Clicking on that link will open up a form with values and current preference of origins corresponding to that pattern. After editing the values and preference order, click on “Save” to save those changes. Changes to your pattern will reflect immediately for fresh images.

Transformations

Adding transformation to your image URL

    <!-- if the ImageKit ID is demo -->

    <!-- transformation appears after / URL pattern -->
    https://ik.imagekit.io/demo/tr:<transformations>/path/to/your/image.jpg 

    <!-- transformation appears as a query parameter 'tr'-->
    https://ik.imagekit.io/demo/path/to/your/image.jpg?tr=<transformations>

There are several image transformations available in ImageKit and new ones are being added regularly. All transformations can be applied by changing the image URL. These URL based transformations give you the flexibility of getting the exact image instantly for different devices and as per your design requirements.

Transformation Examples

    <!-- if the ImageKit ID is demo -->

    <!-- transformation of height 100px -->
    https://ik.imagekit.io/demo/tr:h-100/default-image.jpg 

    <!-- transformation of height 100px, width 200px and quality 80 -->
    https://ik.imagekit.io/demo/tr:h-100,w-200,q-80/default-image.jpg

    <!-- same transformation as query parameter -->
    https://ik.imagekit.io/demo/default-image.jpg?tr=h-100,w-200,q-80

There are two ways of adding a transformation. In the first way, the transformations are added immediately after the URL pattern appears in the URL and before the rest of the image path. As can be seen from the examples, each transformation string has to begin with tr: and appears after the / URL pattern. This holds true for even the custom URL patterns that you create.

In the second way, the transformations are added as a query parameter tr in the URL. As it can be seen from the example, the transformation string remains the same in both the cases. Just that, instead of using tr: in the URL, we use tr= as a query parameter. This makes it even easier to apply transformations to your existing image URLs.

Each individual transformation like height, width, quality etc. has a transformation code. For example, the transformation code for height is h and that for width is w. Each individual transformation has to specified in the format <transformationCode>-<transformationValue>. So if you want to specify the value of height as 100px, the transformation would be h-100. If you want to specify the width as 200px, then the transformation would be w-200.

After tr:, you can mention as many transformations as you want, each separated by a “,” (comma). For example, to specify the height of an image as 100px, the width as 200px, and the image quality as 80. the transformation string would look like tr:h-100,w-200,q-80. Note that there are no spaces in the final transformation string.

Following is a list of available transformations, followed by examples of how the transformations can be used and combined with other transformations to get an appropriate image. For all examples, we will be using the following image which is 600x600 pixels.

Resizing

These options are used to change the dimensions of the input image.

height transformation

    <!-- if the ImageKit ID is demo -->

    <!-- transformation of height 100px -->
    https://ik.imagekit.io/demo/tr:h-100/medium_cafe_B1iTdD0C.jpg

Height
Transformation Code: h

Used to specify the height of the output image. If height is used without specifying the width, then the aspect ratio is preserved in the final output image. Only integer values can be specified for height. Values should be greater than 0.

For example, if the input image has width = 600px and height = 600px, and h-100 transformation is used to get an image with 100px height, then the resulting image has width = 100px and height = 100px. The aspect ratio is preserved by adjusting the width.

Image with height = 100px with tr:h-100 transformation.

width transformation

    <!-- if the ImageKit ID is demo -->

    <!-- transformation of width 200px -->
    https://ik.imagekit.io/demo/tr:w-200/medium_cafe_B1iTdD0C.jpg

Width
Transformation Code: w

Used to specify the width of the output image. If width is used without specifying the height, then the aspect ratio is preserved in the final output image. Only integer values can be specified for width. Values should be greater than 0.

For example, if the input image has width = 600px and height = 600px, and w-200 transformation is used to get an image with 200px width, then the resulting image has width = 200px and height = 200px. The aspect ratio is preserved by adjusting the height.

Image with width = 200px with tr:w-200 transformation.

aspect ratio transformation

    <!-- transformation of width 400px and 4:3 aspect ratio -->
    https://ik.imagekit.io/demo/tr:ar-4-3,w-400/medium_cafe_B1iTdD0C.jpg

Aspect Ratio
Transformation Code: ar

Used to specify the aspect ratio of the output image or the ratio of width to height of the output image. This transform must be used along with either the height or the width transform. The format of specifying this transformation is ar-<width>-<height>. So, for a aspect ratio of 4:3, the transformation would be ar-4-3. The maximum allowed aspect ratios are 10:1 and 1:10.

For example, if the input image has width = 600px and height = 600px, and w-200,ar-4-3 transformation is used to get an image with 200px width, then the resulting image has width = 200px and height = 150px. The aspect ratio 4:3 (200px:150px) and width 200px is preserved by adjusting the height.

This feature is particularly useful if you know the image container ratio and are using Client Hints to vary the width of the image automatically based on the user’s device. See how to use aspect ratio for client hints here.

Image with width = 200px and aspect ratio 4:3

Cropping

When height and width both are specified together, then there are different possible scenarios to get the final image. The final image could be forced to fit the specified dimensions. Or we could be more lenient on one of the dimensions to maintain the aspect ratio. Or we could extract the specified area from the larger original image without actually resizing the image. To control these scenarios, there are 3 different cropping options.

Crop
Transformation Code: c
Valid Values: maintain_ratio, force, at_least, at_max
Default Value: maintain_ratio

This option decides the final value of height and width of the output image based on the aspect ratio of the input image and the requested transform.

The input image is 600px by 600px. And we use the transformation string tr:h-300,w-400 to get an output image of width 400px and height 300px. Note that in such a case, the aspect ratio of the input image is 1:1 whereas the requested output aspect ratio is 4:3.

maintain_ratio (default) cropping

    <!-- transformation of height 300px, width 400px -->

    <!-- default crop of maintain_ratio -->
    https://ik.imagekit.io/demo/tr:h-300,w-400/medium_cafe_B1iTdD0C.jpg

maintain_ratio will maintain the aspect ratio of the original image. But at the same time will give you the exact dimensions in the output image. In the above example, the 600x600 image is first brought down to 400x400. This satisfies width = 400px. Now to satisfy height = 300px, the height has to be reduced. Instead of distorting the aspect ratio, some portion of the image is shaved off from the edges. The resulting image is 400x300 with 50px shaved off from each side.

Image with width = 400px, height = 300px and default cropping.

forced cropping

    <!-- transformation of height 300px, width 400px, forced crop -->

    <!-- forced crop-->
    https://ik.imagekit.io/demo/tr:h-300,w-400,c-force/medium_cafe_B1iTdD0C.jpg

force is the opposite of maintain_ratio. It will give you the exact dimensions but disturb aspect ratio of the original image to preserve the entire image content. In the above example, the 600x600 image is first brought down to 400x400. This satisfies width = 400px. Now to satisfy height = 300px, the height has to be reduced. To do this, the image is vertically compressed, distorting it’s aspect ratio.

Image with width = 400px, height = 300px and forced cropping.

at_least and at_max try to combine the best of maintain_ratio and force. Like maintain_ratio, both these crops don’t change the aspect ratio. And like force, they try to preserve the entire content of the image which is not done in maintain_ratio. To achieve this, the resulting image may or may not have the exact same dimension as requested in the transformation. Only one of the dimensions would match the requested transformation.

at_least cropping

    <!-- transformation of height 300px, width 400px, at_least crop -->

    <!-- at_least crop -->
    https://ik.imagekit.io/demo/tr:h-300,w-400,c-at_least/medium_cafe_B1iTdD0C.jpg

at_least will give you an image that is at least as big as what you request or can be bigger than what you request. In the above example, the 600x600 image is first brought down to 400x400. This satisfies width = 400px. Also, at this stage, the entire image is preserved and is larger than what is requested. So the output image will have dimensions 400x400. Note only the requested width matches the final output.

Image with width = 400px, height = 300px and at_least cropping.

at_max cropping

    <!-- transformation of height 300px, width 400px, at_max crop -->

    <!-- at_max crop -->
    https://ik.imagekit.io/demo/tr:h-300,w-400,c-at_max/medium_cafe_B1iTdD0C.jpg

at_max will give you an image that is at max as big as what you request or can be smaller than what you request. In the above example, the 600x600 image is first brought down to 400x400. This satisfies width = 400px. But to preserve the entire content, the output will be 400x400 which is larger than what was requested. So the resulting image is brought down 300x300. This is smaller than what was requested and the requested height matches the final output image.

Image with width = 400px, height = 300px and at_max cropping.

Side by side placement of all croppings at height = 100px, width = 150px. Default, Forced, At Least and At Max

Crop Mode
Transformation Code: cm
Valid Values: resize, extract, pad_extract, pad_resize
Default Value: resize

The crop mode option is used to specify the strategy of how the input image is used for cropping to get the output image.

The input image is 600px by 600px. And we use the transformation string tr:h-300,w-400 to get an output image of width 400px and height 300px.

different crop modes

    <!-- transformation of height 300px, width 400px, default crop mode -->

    <!-- default crop mode -->
    https://ik.imagekit.io/demo/tr:h-300,w-400/medium_cafe_B1iTdD0C.jpg

    <!-- extract crop mode -->
    https://ik.imagekit.io/demo/tr:h-300,w-400,cm-extract/medium_cafe_B1iTdD0C.jpg

    <!-- pad_extract crop mode -->
    https://ik.imagekit.io/demo/tr:h-700,w-700,cm-pad_extract/medium_cafe_B1iTdD0C.jpg

    <!-- pad_resize crop mode -->
    https://ik.imagekit.io/demo/tr:h-300,w-400,cm-pad_resize,bg-DEDEDE/medium_cafe_B1iTdD0C.jpg

One option is to resize the image down to a smaller size. The content of the image starts appearing smaller in the new resized version. This is achieved by setting crop mode to resize. This is also the default option.

Image with width = 400px, height = 300px and default crop mode.

The other option is that the image content remains of the same size. But you extract out or crop out a region of that image that matches the required dimension. This is achieved by setting crop mode to extract. In this case, not all the original image’s content appears in the final output because only a small region of the image is being considered for the output. The region which is extracted can be controlled using the “focus” parameter, explained in the next section.

Image with width = 400px, height = 300px and extract crop mode.

The extract method works when you have to extract out a smaller region from a larger image. It won’t work if you request for a larger image from a smaller original one. In this case, to match the required output dimensions, the extracted image is padded. This can be achieved by setting crop mode to pad_extract. For example, if your have a 400x300 image and request to extract a 500x500 image using the pad_extract option, the output image requested is larger than the input image. pad_extract would try to extract the maximum possible area it can from the original image. In this case it is of the size of the original input image. It then centrally places this extracted image on a 500x500 canvas. The background color of the canvas defaults to black (#000000) but can be controlled using the background color parameter (explained later).

Image with width = 700px, height = 700px and pad_extract crop mode. The original image is smaller than the requested output at 700x700 px.

The pad resize is required when you want to resize image to a smaller dimension, want the aspect ratio maintained and do not want cropping on your image. In this case, if you want the final image to be of a specific height and width, then the image needs to be appropriately padded on the edges. pad_resize does that intelligently.

Image with width = 400px, height = 300px and pad_resize crop mode. The original image is 600x600 and resized image is 400x300 with padding of color #DEDEDE.

By default, if you do not specify the background color and the image does not contain any transparency, pad_resize crop mode uses solid white (#FFFFFF) as the background. However, in case the image does have a transparent background, pad_resize automatically uses a transparent padding for the image.

focus transformation

    <!-- transformation of height 300px, width 400px -->

    <!-- extract crop mode, default center focus -->
    https://ik.imagekit.io/demo/tr:h-300,w-400,cm-extract/medium_cafe_B1iTdD0C.jpg

    <!-- extract crop mode, focus top-left -->
    https://ik.imagekit.io/demo/tr:h-300,w-400,cm-extract,fo-top_left/medium_cafe_B1iTdD0C.jpg

    <!-- extract crop mode, focus bottom-right -->
    https://ik.imagekit.io/demo/tr:h-300,w-400,cm-extract,fo-bottom_right/medium_cafe_B1iTdD0C.jpg

    <!-- extract crop mode, smart crop (focus auto) -->
    https://ik.imagekit.io/demo/tr:h-100,w-300,fo-auto/blue_sea_BJ8kcp2A__1_.jpg

Focus
Transformation Code: fo
Valid Values: center, centre, top, left, bottom, right, top_left, top_right, bottom_left, bottom_right, auto (beta)
Default Value: center

This option is coupled with the extract type of crop mode (crop mode is not needed if you are using auto focus, read below) to get the area of the input image that should be focussed on to get the output image.

Let’s say the input image is 600px by 600px. And we use the transformation string tr:h-300,w-400 to get an output image of width 400px and height 300px. With the extract option as crop mode, a 400x300 region has to be extracted out from the image. By default, the value of focus is center, because of which the 400x300 region is extracted from the center of the image.

Similarly, if the value of focus is top_left, then the 400x300 region is extracted out from the top-left corner of the input image i.e. both left and top edges of the input and output image align with each other. If the value is top, then the 400x300 region is extracted from the top-center position of the input image i.e. only the top edge of the input and output image align with each other.

Smart crop is a new focus mode, currently in beta. It can be enabled by setting the value of focus to auto. This works by intelligently identifying the most important part of an image and keeping it in focus while creating the thumbnail. To get smart crop to work, you need to specify both height and width required in the output image.

Side by side placement of differently focussed extractions at height = 200px, width = 200px. Default (Center), top_left and bottom_right

Quality

quality transformation


    <!-- quality of 75 with resizing -->
    https://ik.imagekit.io/demo/tr:h-300,w-400,q-75/medium_cafe_B1iTdD0C.jpg

    <!-- quality of 60 without resizing -->
    https://ik.imagekit.io/demo/tr:q-40/medium_cafe_B1iTdD0C.jpg

Transformation Code: q
Valid Values: integers from 0-100
Default Value: 80 (see optimisation section)

This option specifies the output quality of the lossy formats like JPG and WebP. A higher quality number means a larger size of the output image with high quality. A smaller number means low quality image at a smaller size. Setting the quality to 80 reduces the original image size significantly without any perceivable difference in the image quality.

If no quality value is specified and the “Automatic image quality control” options is selected in your dashboard settings, then the default quality value of 80 is used for all images. If automatic image quality control is switched off then the no quality optimisation is done.

Side by side placement of images with different quality at height = 200px, width = 200px in JPG format. Default Q=80 (12.2KB), Q=100 (39.7KB) and Q=40 (6.6KB)

Format

format transformation


    <!-- WebP Format (automatic) -->
    https://ik.imagekit.io/demo/tr:h-300,w-400/medium_cafe_B1iTdD0C.jpg

    <!-- JPG format -->
    https://ik.imagekit.io/demo/tr:h-300,w-400,f-jpg/medium_cafe_B1iTdD0C.jpg

    <!-- PNG format -->
    https://ik.imagekit.io/demo/tr:h-300,w-400,f-png/medium_cafe_B1iTdD0C.jpg

Transformation Code: f
Valid Values: auto, webp, jpg, jpeg, png
Default Value: auto (see optimisation section)

This options specifies the format of the output image. If no output format is specified and the “Dynamic image format selection” option is selected in your dashboard settings, then the output format is decided on the basis of the user’s device capabilities and input image format. If dynamic image format selction is switched off, then the format of the output image is same as that of the input image.

Side by side placement of images with different formats at height = 200px, width = 200px. Default WebP (10.5KB if supported by browser else JPG), JPG (12.2KB) and PNG (79.9KB)

Progressive JPEG

progressive JPEG options


    <!-- Progressive JPG -->
    https://ik.imagekit.io/demo/tr:h-300,w-400,f-jpg,pr-true/medium_cafe_B1iTdD0C.jpg

    <!-- Normal JPG -->
    https://ik.imagekit.io/demo/tr:h-300,w-400,f-jpg/medium_cafe_B1iTdD0C.jpg

Transformation Code: pr
Valid Values: true, false
Default Value: false

This options specifies if the output JPEG image should be rendered progressively. In progressive rendering, the client instead of downloading the image row-wise (baseline loading), renders a low-quality pixelated full image and then gradually keeps on adding more pixels and information to the image. This gives faster perceived load times.

Progressive JPEGs can also be smaller than a baseline JPEG, especially for larger images high-resolution images.

Image Metadata

metadata options


    <!-- With all image metadata -->
    https://ik.imagekit.io/demo/tr:h-300,w-400,f-jpg,md-true/medium_cafe_B1iTdD0C.jpg

    <!-- All metadata stripped -->
    https://ik.imagekit.io/demo/tr:h-300,w-400,f-jpg/medium_cafe_B1iTdD0C.jpg

Transformation Code: md
Valid Values: true, false
Default Value: false

This options specifies if the output image should contain all the metadata that is initially available from the original image. Enabling this is not recommended because this metadata is not relevant for rendering on web and mobile apps. The only reason where you should enable the metadata option is when you have knowingly want the additional data like camera information, lens information and other image profiles attached to your image.

This option can also be controlled from your dashboard using the “Image Metadata” setting. If the “Image Metadata” setting is set to “Preserve complete metadata”, then the metadata is preserved in all output images that use ImageKit.

Color Profile

color profile options


    <!-- With image color profile excluding rest of the metadata -->
    https://ik.imagekit.io/demo/tr:h-300,w-400,f-jpg,cp-true/medium_cafe_B1iTdD0C.jpg

    <!-- All metadata including color profile stripped -->
    https://ik.imagekit.io/demo/tr:h-300,w-400,f-jpg/medium_cafe_B1iTdD0C.jpg

Transformation Code: cp
Valid Values: true, false
Default Value: false

This options specifies if the output image should contain the color profile that is initially available from the original image. It is recommended to remove the color profile before serving the image on web and apps. However, in cases where you feel that the image looks faded or washed-out after using ImageKit and want to preserve the colors in your image, then you should set this option to true.

This option can also be controlled from your dashboard using the “Image Metadata” setting. If the setting is set to “Only color profile”, then the color profile is preserved in all output images that use ImageKit. Apart from the color profile, the other metadata is removed.

Rotate

rotate transformation


    <!-- 90 degree rotation -->
    https://ik.imagekit.io/demo/tr:rt-90/medium_cafe_B1iTdD0C.jpg

    <!-- automatic rotation based on EXIF Orientation tag -->
    https://ik.imagekit.io/demo/tr:rt-auto/medium_cafe_B1iTdD0C.jpg

Transformation Code: rt
Valid Values: 0, 90, 180, 270, 360, auto

This options specifies the degrees by which the output image has to be rotated or specifies the use of EXIF Orientation tag for the rotation of the image using the keyword auto.

Image with width = 200px, height = 200px and rotated by 90 degrees.

Radius

radius transformation


    <!-- 20px radius -->
    https://ik.imagekit.io/demo/tr:r-20/medium_cafe_B1iTdD0C.jpg

Transformation Code: r
Valid Values: any positive integer or “max”

This options specifies the radius to be used to get a rounded corner image. If you want a perfectly rounded image, set the value as “max”. This option is applied after resizing of the image, if any. Since rounding the image from the corners requires introduction of a transparent layer, the default output format is WebP (wherever supported) or PNG. PNG images are significantly larger than the corresponding JPG image in most cases. If you do not need a transparent background and are fine with a fixed solid color background, then after this transformation, chain a background bg and format jpeg. You can read about chaining transformations here.

Image with width = 200px, height = 200px and radius 50px. Output has transparent background.

Background

background transformation


    <!-- dark blue background -->
    https://ik.imagekit.io/demo/tr:h-700,w-700,cm-pad_extract,bg-272B38/medium_cafe_B1iTdD0C.jpg

Transformation Code: bg
Valid Values: a valid RGB hex code Default: Black (000000)

This option specifies the background color as RGB hex code (eg FF0000) or a RGBA code (eg FFAABB50) to be used for the image. If you specify a 8-character background the last two characters should be numbers from 00 to 99 which indicate the opacity level of the background. 00 corresponds to opacity of 0.00, 01 corresponds to an opacity of 0.01 and so on.

If you want a completely transparent background use 00 in the last two digits of the background. If you use a 6-character background value, then a fully opaque background (i.e. opacity 1) is used for the operation.

This option is useful when you use pad_extract crop mode (where the resulting image is larger than the original image) or when you use the radius option and want a non-transparent background or in the pad_resize crop mode for padding the resized image. When using this with the radius option, then the background transformation should be applied in the next step of the transformation chain along with the format jpeg transformation. You can read about chaining transformations here.

Image with width = 700px, height = 700px and pad_extract crop mode and background #272B38 (dark blue).

Image with width = 700px, height = 700px and pad_extract crop mode and background #00000000 (transparent).

Blur

blur transformation


    <!-- blurred image -->
    https://ik.imagekit.io/demo/tr:bl-20/medium_cafe_B1iTdD0C.jpg

Transformation Code: bl
Valid Values: Integers from 1 to 100

This options specifies the Gaussian blur that has to be applied to the image. The value of blur decides the radius of the Gaussian blur that is applied. Higher the value, higher is the radius of Gaussian blur.

Blurred image

Border

border transformation


    <!-- image with red border 2px wide -->
    https://ik.imagekit.io/demo/tr:b-2_FF0000/medium_cafe_B1iTdD0C.jpg

Transformation Code: b
Valid Values: -

This options specifies the width and color of the border that is added around the image. The width is a positive integer that specifies the border width in pixels. The border color is specified as a standard RGB hex code. Width and color are separated by an underscore “_”.

A valid value would look like b-10_FF0000. This would add a constant border of 10px with color code #FF0000 around the image. If the original image dimension is 200x200, then after applying the border, the dimensions would be 220x220.

Bordered image

DPR

DPR transformation


    <!-- DPR 2.5, results in a 250px height image -->
    https://ik.imagekit.io/demo/tr:h-100,dpr-2.5/medium_cafe_B1iTdD0C.jpg

Transformation Code: dpr
Valid Values: 0.1 to 5.0

This options specifies the device pixel ratio to be used to calculate the dimension of the output image. It is useful when creating image transformations for devices with high density screens (DPR greater than 1) like the iPhone.

The DPR option works only when either the height or the width or both are specified for resizing the image. The value of DPR can be a floating point number between 0.1 and 5.0. The floating point DPR value is then multiplied with the specified height and width to create and deliver the image.

If the resulting height or width after considering the specified DPR value is less than 1px or more than 5000px then the value of DPR is not considered and the normal height or width specified in the transformation string is used.

Image with width = 100px, height = 100px for a screen with DPR 2, results in a 200x200 image

Trim Edges

Trim Edges transformation


    <!-- Original Image -->
    https://ik.imagekit.io/demo/img/trim_test_1_SykZcHjhz.jpg

    <!-- White background trimmed from the edges -->
    https://ik.imagekit.io/demo/img/tr:t-true/trim_test_1_SykZcHjhz.jpg

Transformation Code: t
Valid Values: true or an integer from 1 to 99

This transformation is useful for images that have a solid / nearly-solid background and the object in the center. This transformation will trim the background from the edges, leaving only the central object in the picture.

This transformation compares the background pixels against the pixel in the top-left corner of the image and decides whether it should be considered for trimming or not. The comparison is made using a threshold difference. If the difference between the pixels falls within the threshold limits, then it would be considered for trimming.

If you use t-true as the transformation, then it uses a default threshold value for trimming. Otherwise, you can specify an integral value to vary the threshold from 1 to 99.

Original Image

Image with width = 100px with the background trimmed

Overlays

Overlay Transformation


    <!-- Image with height 300px overlaid with a logo at the center -->
    https://ik.imagekit.io/demo/tr:h-300,oi-logo-white_SJwqB4Nfe.png/medium_cafe_B1iTdD0C.jpg

These set of options are used to overlay one image over another image. This will help you generate watermarked images if needed.

Overlay Image
Transformation Code: oi

You will have to upload the overlay Image in ImageKit dashboard and overlay image has to be a PNG image.

For example: If you upload one logo image and one input image

Input image: https://ik.imagekit.io/demo/medium_cafe_B1iTdD0C.jpg
Logo image: https://ik.imagekit.io/demo/logo-white_SJwqB4Nfe.png

The overlay image path i.e logo-white_SJwqB4Nfe.png cannot contain slashes (“/”).

URL to overlay logo image on input image:
https://ik.imagekit.io/demo/tr:h-300,oi-logo-white_SJwqB4Nfe.png/medium_cafe_B1iTdD0C.jpg

Image with height 300px overlaid with a logo at the center

Overlay Focus
Transformation Code: ofo
Valid Values: center, centre, top, left, bottom, right, top_left, top_right, bottom_left, bottom_right
Default Value: center

Specifies the positon of the overlaid image relative to the input image. For example, if the value of overlay focus is top_left, then the overlay image is placed in the top left corner of the input image. If the value of overlay focus is bottom, then the overlay image is placed at the bottom center of the input image. By default, the overlay image is placed at the center of the input image.

Overlay Transformation - Focus


    <!-- Image with height 300px overlaid with a logo at the top-right corner -->
    https://ik.imagekit.io/demo/tr:h-300,oi-logo-white_SJwqB4Nfe.png,ofo-top_right/medium_cafe_B1iTdD0C.jpg

Image with height 300px overlaid with a logo at the top-right corner

Overlay X and Y positions
Transformation Code: ox and oy respectively
Valid Values: Positive Integer value

This option provides more granular control over the positioning of the overlay image on the input image. The top left corner of the input image is considered as (0,0) and the bottom right corner is considered as (w, h) where w is the width and h is the height of the input image. If ox is 100 then the overlay image is placed 100px from the left edge of the input image. If oy is 150 then the overlay image is placed 150px from the top edge of the input image.

If either of ox or oy value exceeds the width or height of the input image, then the values are adjusted and made equal to the corresponding dimension of the input image.

We also have support for negative values as well. Negative values are supported with a leading capital N in front of the value provided. The value provided is subtracted from the original dimension of the image & positioned accordingly.

Overlay Transformation - X & Y


    <!-- Image with height 300px overlaid with a logo at the 30px from top and 35px from left edge -->
    https://ik.imagekit.io/demo/tr:h-300,oi-logo-white_SJwqB4Nfe.png,ox-35,oy-30/medium_cafe_B1iTdD0C.jpg

Image with height 300px overlaid with a logo at the 30px from top and 35px from left edge

Overlay Transformation - Negative X & Y


    <!-- Image with height 300px overlaid with a logo using the 40px from bottom & 120px from right -->
    https://ik.imagekit.io/demo/tr:h-300:oi-logo-white_SJwqB4Nfe.png,oh-20,ox-N120,oy-N40/medium_cafe_B1iTdD0C.jpg

Image with height 300px overlaid with a logo using the 40px from bottom & 120px from right

Overlay Height and Width
Transformation Code: oh and ow respectively
Valid Values: Positive Integer value

Specifies the height & width of the overlaid image. For example, if you need to resize the overlaid image with dimensions 900 X 600 to 300 X 200, you can use oh-200 / ow-300 as they help to maintain aspect ratio of image while resizing.

Overlay Transformation - Overlay Height & Width


    <!-- Image with height 300px overlaid with resized image -->
    https://ik.imagekit.io/demo/tr:oi-logo-white_SJwqB4Nfe.png,oh-20/medium_cafe_B1iTdD0C.jpg

Image with height 300px overlaid with resized image

Overlay Text
Transformation Code: ot

Input image: https://ik.imagekit.io/demo/medium_cafe_B1iTdD0C.jpg
Input Text: overlay made easy

The text is overlaid at the center of the image by default. Our current support is limited to alphanumberic system & special characters _ & - only.

For overlay text, we have support for features such as text’s color, font, typography & size.

Overlay Transformation - Text


    <!-- Image with height 300px overlaid with text -->
    https://ik.imagekit.io/demo/tr:ot-overlay%20made%20easy,ots-45/medium_cafe_B1iTdD0C.jpg

Image with height 300px overlaid with text

Overlay Text Color
Transformation Code: otc
Valid Values: a valid RGB Hex Code
Default Value: 000000 (Black)

Species the color of the overlaid text on the image.

Overlay Transformation - Text Color


    <!-- Image with height 300px overlaid with aqua text color -->
    https://ik.imagekit.io/demo/tr:ot-overlay%20made%20easy,ots-45,otc-00FFFF/medium_cafe_B1iTdD0C.jpg

br/> Image with height 300px overlaid with aqua text color

Overlay Text Font
Transformation Code: otf
Valid Values: Positive integer values
Default Value: Sans Serif

Specifies the font family for the overlaid text.

Overlay Transformation - Text Font


    <!-- Image with height 300px overlaid with ubuntu text font -->
    https://ik.imagekit.io/demo/tr:ot-overlays%20made%20easy,ots-45,otc-00FFFF,otf-ubuntu/medium_cafe_B1iTdD0C.jpg

Image with height 300px overlaid with ubuntu text font

We currently support a limited number of font families

Font Family	Support for Bold	Support for Italics
AbrilFatFace	No	No
Amarnath	Yes	Yes
Arvo	Yes	Yes
Audiowide	No	No
Chivo	Yes	Yes
CrimsonText	Yes	Yes
exo	Yes	Yes
FredokaOne	No	No
GravitasOne	No	No
Kanit	Yes	Yes
Lato	Yes	Yes
Lobster	No	No
Lora	Yes	Yes
Monoton	No	No
Montserrat	Yes	Yes
PT Mono	No	No
PT_Serif	Yes	Yes
OpenSans	Yes	Yes
Roboto	Yes	Yes
stagOldStandard	Yes	Yes
Ubuntu	Yes	Yes
Vollkorn	Yes	Yes

Overlay Text Size
Transformation Code: ots
Valid Values: Positive integer values
Default Value: 10px

Specifies the size of the overlaid text.

Overlay Transformation - Text Size


    <!-- Image with height 300px overlaid with text size of 45px -->
    https://ik.imagekit.io/demo/tr:ot-overlays%20made%20easy,ots-45,otc-00FFFF/medium_cafe_B1iTdD0C.jpg

Image with height 300px overlaid with text size of 45px

Overlay Text Typography
Transformation Code: ott
Valid Values: b ( bold ) & i ( italics )

Specifies the typography of the font family used for the overlaid text.

Overlay Transformation - Text Typography


    <!-- Image with height 300px overlaid with text typography -->
    https://ik.imagekit.io/demo/tr:ot-overlays%20made%20easy,ott-bi,ots-45,otc-00FFFF/medium_cafe_B1iTdD0C.jpg

Image with height 300px overlaid with text typography

NOTE : Bold & Italics are not supported for all provided fonts, kindly refer to font chart

Overlay Transparency
Transformation Code: oa
Valid Values: 1 to 9

Specifies the transperancy level for the overlaid image.

Overlay Transformation - Transparency


    <!-- Image with height 300px overlaid with image having 50% transperancy level -->
    https://ik.imagekit.io/demo/tr:ot-overlays%20made%20easy,oa-5,ots-45/medium_cafe_B1iTdD0C.jpg

Image with height 300px overlaid with image having 50% transperancy level

NOTE : overlay transparency is currently supported for overlay texts & backgrounds only

Overlay Background
Transformation Code: obg
Valid Values: a valid RGB Hex code Default Value: 100px for both height & width

Specifies the colour of background canvas to be overlaid.

Overlay Transformation - Background


    <!-- Image with height 300px overlaid with background canvas -->
    https://ik.imagekit.io/demo/tr:obg-00FFFF,oh-50,ow-600,ofo-bottom/medium_cafe_B1iTdD0C.jpg

Image with height 300px overlaid with background canvas

NOTE : Default values for overlay height & width are 100px for overlay background

We recommend using named transformations for overlay transformations.

Named Transformations

Transformation Code: n

Let’s say you have to crop a 200px by 200px region from the top left corner of the input image and give it a 3px black border. The transformation string for this would look like tr:h-200,w-200,cm-extract,fo-top_left,b-3_000000.

Transformations strings of this kind can be difficult to remember for a developer. Repeating these transformation strings across your code base could make it difficult to maintain and change.

To avoid this, you can give a name to this transformation like bordered-thumbnail and use this name as an alias for the entire transformation string. Your new transform string would look like tr:n-bordered_thumbnail which is definitely more expressive and easier to remember than the original transformation string above.

Using named transforms is highly recommended. Not only does this improve your code quality and maintainability, it also improves caching performance of the CDN.

Content on a CDN is cached on the basis of the resource URL. So for a CDN tr:h-200,w-200,cm-extract,fo-top_left,b-3_000000 is different from tr:w-200,h-200,cm-extract,fo-top_left,b-3_000000 which is different from tr:h-200,w-200,fo-top_left,b-3_000000,cm-extract. Thus for all the three transformation strings, the same image is cached on the CDN which is inefficient. Internally all these transformations result in the same image. By using a named transformation instead of this transformation string, you would reduce the chances for a developer to make different transformation strings to achieve the same result thereby increasing CDN caching performance.

Chained Transformations

Some transforms are dependent on the sequence in which they are carried out. For example, if we have a transformation that requires the input image to be resized from 800x600 to 400x300 and rotated by 90 degrees. The transformation string for this will be tr:w-400,h-300,rt-90

Here are two possible scenarios for this-

Rotation takes place before resize

The 800x600 image is rotated by 90 degrees to get 600x800 image. Then a 400x300 image is obtained from it. The resulting image would be a 400x300 image with some portion of the original image missing (if aspect ratio of the 600x800 image is to be maintained).

Resize takes place before rotation

The 800x600 image is first resized to 400x300 (half it’s size) and then rotated by 90 degrees. The resulting image would be a 300x400 image with all the contents of the original image still present (though rotated by 90 degrees). This is also the default behavior of ImageKit.

Since it is easy to confuse the two cases while implementation and there can be more confusing cases when it comes to the sequence of application of transforms, ImageKit provides an easy way to get the exact image predictably with chained transformations. In chained transformations, you can specify the exact sequence in which the transformations are to be applied. Each step of the transformation chain is separated from the other by “:”.

In the above example, rotate and resize can be considered as two steps of the transformation chain.

Resize step: w-400,h-300
Rotate step: rt-90

These two can be combined in a transformation chain to get a predictable image as per the requirement.

Rotate before resize: tr:rt-90:w-400,h-300
Resize before rotate: tr:w-400,h-300:rt-90

As it can be seen from the chained transformation strings above, the transformation steps are separated by a “:”. Also the transformation string is now more expressive about the transform that will be actually carried out. Like this, you can add other sequence dependent steps in a transform chain to obtain predictable results.

Default Image

Transformation Code: di

If the image that is requested using ImageKit does not exist, then a 404 error is shown. However, there might be a need where instead of giving a broken image to the user, you want a default image to be delivered. ImageKit provides a way to do this without having to handle this at application level.

This option di specifies the path of the image that will be delivered if the original image is not available. The default image should be available in the ImageKit Media Library directly and not on one of your image origins. The default image path cannot contain slashes (“/”). All the transformations that are applied to the original image in the URL will be applied on the default image as well before delivering it.

For example: If this is your default image

Default Image: https://ik.imagekit.io/demo/medium_cafe_B1iTdD0C.jpg

Then use the following URL to get the default image in case an error occurs while fetching the original image.
https://ik.imagekit.io/demo/tr:di-medium_cafe_B1iTdD0C.jpg/non_existent_image.jpg

Effects

auto contrast stretching


    <!-- Image with height 300px, with automatic contrast enhancement -->
    https://ik.imagekit.io/demo/tr:h-300,e-contrast/sample_image.jpg

    <!-- Image with height 300px, with automatic sharpening -->
    https://ik.imagekit.io/demo/tr:h-300,e-sharpen/sample_image.jpg

    <!-- Image with height 300px, with unsharp mask -->
    https://ik.imagekit.io/demo/tr:h-300,e-usm-2-2-0.8-0.024/sample_image.jpg

These set of options that can be used to add some effect to the image by altering its contrast, sharpness, colors etc..

Contrast Stretch
Transformation Code: e-contrast

This option will automatically enhance the contrast of the image by using the full range of intensity values that a particular image format allows. This basically means that the lighter portions of the image would become even lighter and the darker portions of the image would become even brighter, thereby enhancing the contrast.

Original Image with height 300px

Image after contrast enhancement

Sharpen
Transformation Code: e-sharpen(-number)
Valid Values: any integer value can be used in place of number or it can be ommitted (i.e. use just e-sharpen)

Sharpens the input image. It is useful to highlight the edges and finer details in the image. If just e-sharpen is used, then a default sharpening is performed on the image. This behavior can be controlled by specifying a number that controls the extent of sharpening performed - higher the number, more the sharpening.

Original Image with height 300px

Image with default sharpening

Image with numeric sharpening

Unsharp Mask
Transformation Code: e-usm-<radius>-<sigma>-<amount>-<threshold>
Valid Values: radius, sigma, amount and threshold have to be positive floating point values

Unsharp masking (USM) is an image sharpening technique. This transform allows you to apply and control unsharp mask on your images. The amount of sharpening can be controlled by varying the 4 parameters - radius, sigma, amount and threshold. This results in perceptually better images compared to just e-sharpen.

You can read more about the unsharp masking technique on Wikipedia and Cambridge Colour apart from other resources on the internet. While most resources talk only about radius, amount and threshold parameters, the sigma parameter is the standard deviation, used as an input to the unsharp masking process.

Original Image with height 300px

Image with unsharp masking

Optimisations

ImageKit offers some optimisations out of the box. The optimisations are done to reduce the size of the final output image. This greatly improves the loading performance of your images while preserving an acceptable image quality.

Removing Metadata

Images carry a lot of additional textual information with them like camera model, ISO, aperture, shutter speed etc. Removing these information while delivering the image can save a lot of KBs. By default, ImageKit delivers an optimised version of the original image that does not contain any metadata. The original copy of the image however would still contain all the metadata if needed.

If you want the image metadata in your output image, you can use the md option in your URL or set the “Image Metadata” to “Preserve complete metadata” in the “Settings” section of your dashboard. This has been explained here.

Since most of the metadata except for the color profile isn’t of much use while delivering the image, you selectively choose to just preserve the color profile in the output image and remove the rest of the metadata.This can be done by using the cp option in your URL or set the “Image Metadata” to “Preserve only color profile” in the “Settings” section of your dashboard. This has been explained here.

Quality Optimisation

Image size can be significantly reduced by delivering an image at a slightly lower quality. Human eye often cannot perceive pixel level changes to an image. This can be used to our advantage as in almost all cases, an image with quality 80 won’t “look” much different from an image at quality 100. However an image at quality 80 can be delivered in half the size when compared to the original image. ImageKit uses a default quality of 80 for all the images.

This can be turned off by unchecking “Automatic image quality control” option in the Settings section of your dashboard. You can also change the default quality from 80 to any other value of your choice for different formats in the “Image quality” section of your dashboard settings. For e-commerce companies with a lot of product images, a quality setting of 90 on WebP and JPEG images would work perfectly.

Format Optimisation

WebP is a relatively new image format currently developed by Google that has a far superior lossless and lossy compression ratio as compared to other image formats. This means an image in WebP format would be 30-40% smaller than the exact same JPEG image. However, WebP support is still at about 60% of all popular devices. ImageKit automatically delivers a WebP image wherever possible to reduce the size of the image delivered. The output image looks absolutely identical to the original one.

SVG files, especially those generated from various design editors, contain a lot of redundant and unnecessary information. These can include editor metadata, hidden elements, default or non-optimal values, comments and other stuff that can be safely removed or converted without affecting the SVG rendering result. Once the extraneous code is removed, the file size decreases by a significant amount, which in turn speeds up website load time. This feature is enabled by default to ensure your website loads as quickly as possible.

This can be turned off by unchecking “Dynamic image format selection” in the Settings section of your dashboard.

PNG Image Optimisation

The size of PNG images can be reduced significantly by using either lossy or lossless compression methods.

The lossy compression methods reduce the size by a significant margin but may also reduce the image quality significantly in some cases. The lossless compression methods achieve a small reduction in image size but the image quality is more or less the same as the original image.

By default, ImageKit chooses lossy compression method on images to achieve maximum size reduction. This is denoted by “Maximum” in the setting “PNG Image Compression Mode” under the “Advanced” tab in Image Settings. You can also switch to lossless compression mode by selecting “Minimum” in this setting. If you do not want any optimization on your PNG image, you can also turn it off completely.

Do note that if you change this setting, the images already cached on the CDN will not reflect this change till the cache expires.

Chroma Subsampling

Chroma Subsampling is an optimisation technique that is used for encoding of JPEG images. This technique takes advantage of the lower sensitivity of human visual system towards color (chroma) than towards brightness (luma). It is generally recommended to use 4:2:0 chroma subsampling on all images. But in certain cases, especially the ones with a very bright object in the foreground over a completely white background, it introduces unwanted image artefacts.

Because quality of the image is our utmost priority, the setting “Use chroma subsampling 4:2:0” is kept “off” by default. This means that we do not use chroma subsampling on the image by default. However, if your images look fine with this setting turned “on”, then you can use it on all your images without worrying and enjoy even better compression ratios on your images.

Security and Restrictions

Certain options are provided in your ImageKit account to secure your images and restrict the transformations that can be done on them. Implementing these securities and restrictions would not only help prevent unauthorised use of your image URLs by random third-parties but would also make your code look cleaner.

Signed URLs

When generating image URLs from your server, you can use your Private Key (available in the Settings section of your dashboard) to sign the image URL. Signing basically adds additional query parameters to your image which ensure that the URL and the image transformation cannot be altered from the URL. The signature can even be used to set a predefined expiry time of the URL.

Since your private key is only known to you and image signatures are one-way hashes, it is not possible for a third-party to be able to generate the exact same signature for a request even if they get access to one of your URLs. If the third party tries to modify the image transformation or the image URL or use it beyond its intended expiry time, the request would return a 401 Unauthorised status code because of a signature mismatch.

By default, this setting, “Only allow signed URLs”, is kept turned off in the settings dashboard as this requires you to implement the signing logic on your servers. If this setting is enabled, then no image without a valid signature attached to it as a query parameter, would be accessible. If this setting is kept off, then all image URLs would be accessible no matter when or how they were generated. If you are using unsigned images now, and want to move to a completely secure signed image request system, then you would need to migrate the existing image URLs as well to start using a signature.

Your private key is used for creating signatures. It is important that signature generation logic is kept on your servers and your private key is not disclosed to anyone.

Generating signed URLs

You can use one of our SDKs to generate a signed image URL. The process of generating a signed URL using the SDK is available in the respective SDK’s documentations.

If you want to implement the signature and URL generation logic on your own, then follow these steps:

Append the following in a string
a. ImageKit ID
b. The complete transformation string without the tr: in the beginning.
If you use tr:h-100,w-100:rt-90 in the URL, then to calculate the signature use h-100,w-100:rt-90.
c. The UTC timestamp in seconds for the expiry time of the URL (if you do not want to expire the URL, set this to 9999999999)
d. Image Key which is the image URL without the URL pattern and transformation string. It should include all query paramaters as well except for the signature related query params i.e. ik-s and ik-t (covered in the next point)
If your URL is https://ik.imagekit.io/demo/tr:h-100,w-100:rt-90/files/image.jpg?version=1 then the image key is files/image.jpg?version=1.
Create a HMAC-SHA1 signature of the above string using your private key as the key.
Get the hex digest of the above signature and attach it to the URL as a query parameter named ik-s.
If you used a timestamp (other than the default 9999999999) to set the expiry time while calculating the hash, attach it to the URL as a query parameter named ik-t.

If the signature is incorrect and the setting “Only allow signed URLs” is checked in your dashboard, then you will get 401 Unauthorised error in the response. Only when the signature is correct, and the URL has not expired (if you set an expiry time in the hash), will the image will be delivered.

If the setting “Only allow signed URLs” is unchecked in your dashboard, then it doesn’t matter whether the URL is signed or not. If the image exists, it will be delivered.

Restricting Unnamed Transformations

Named transformations and there utility has been explained in the Named Transformations section above.

There is a setting “Only allow named transformations” in the settings section of your dashboard. If this setting is enabled, then using unnamed transformations like height, width etc. won’t work in any combination. If the setting is enabled and any of the requested transformations is unnamed, then the URL would return 400 Bad Request response. All the transformations, even in chained transformations, must be named.

Restricting the use of transformations not only makes it easier for the developers to remember the transformations that can be used, it also prevents any unauthorised third-party from applying random transformations on your images.

Uploads

At this stage, only JPG, PNG, WebP and GIF images can be uploaded to ImageKit.

Uploading from dashboard

In the media library section of your dashboard, click on the Upload Images button. You can either choose files using the normal file select dialog box or drag and drop images anywhere on the dashboard to initiate an upload. Once the upload completes, you can copy the image URL to access the image.

Server-side image upload

ImageKit has developed several SDKs to ease the upload integrations. You can check the available SDKs here. If you do not want to use an SDK or could not find a relevant SDK, then you can integrate the upload API directly in your application.

Generating signature for the upload

Each upload request must be signed before uploading. The signature is a mandatory parameter in the upload request. To calculate the signature.

The parameters filename, timestamp and apiKey (your public key) that have to be sent in the image upload request have to be included in the signature.
Sort the parameters in the alphabetical order of the keys i.e. apiKey comes before filename which comes before timestamp.
Append the value of each of these parameters with the key using an = sign to get a key-value pair.
Append these key value pairs to each other using & to get a serialized string of the parameters.
Example - If the filename is my-image.jpg, timestamp is 123456789 and apiKey is myapikey, then the string to be used for signature will be apiKey=myapikey&filename=my-image.jpg&timestamp=123456789.
Using your private key as the key, calculate a hexadecimal HMAC-SHA1 digest of this serialized string.

Never expose your private key on the client-side. All signature generation should take place on the server.

Server-side image upload, using public key:

curl -X POST
     -F "filename=my_image"
     -F "useUniqueFilename=true"
     -F "file=@/path/to/image.jpg"
     -F "folder=/files/"
     -F "signature=generatedsignaturefromyourcode"
     -F "apiKey=mypublickey"
     -F "timestamp=1475592319" 
     "https://upload.imagekit.io/rest/api/image/v2/myimagekitid"

Fill in with actual imagekitId, file and timestamp.

Output for successful upload:

{
  "imagePath": "images/my_image_BJyuWdf0.jpg",
  "size": 51198,
  "height": 300,
  "width": 444
}

HTTP Request

POST https://upload.imagekit.io/rest/api/image/v2/<imagekitId>
Content-Type : multipart/form-data

The API endpoint /rest/api/image/ used the parameter 'image’ for the input file. Given the introduction of non-image file uploads, this old API endpoint will be deprecated in favor of the new /rest/api/image/v2/ endpoint that uses 'file’ parameter for the input file

Path Parameters

Parameter	Required	Description
imagekitId	Yes	The ImageKit Id associated with your account

Form Parameters

Parameter	Required	Description
file	Yes	The base64 encoded image that has to be uploaded
filename	Yes	The name with which the file has to be uploaded
apiKey	Yes	Your public API key
signature	Yes	HMAC-SHA1 signature generated for the file upload
timestamp	Yes	UTC timestamp in seconds. The request will be valid for 30 minutes from this timestamp.
useUniqueFilename	No	“true” or “false”. If set to true, ImageKit will add a unique code to the filename parameter to get a unique filename. If false, the image is uploaded with the filename parameter as name. If an image exists with the same name, this new image will override it. Default is “true”
folder	No	The folder path (eg- `/images/folder/`) in which the image has to be uploaded. Default is “/”

Response Codes

HTTP Status	Status Number (Status Code)	Description
400	1400 (BAD_REQUEST)	Invalid or missing form parameters in the request or file too large
403	1403 (ACCESS_FORBIDDEN)	Invalid signature or expired request
404	1404 (UNMAPPED_REQUEST)	Invalid ImageKit Id
500	1500 (SERVER_ERROR)	Internal server error while uploading the file

Server-side file upload

Since it is not an ideal scneario to manage multiple CDN partners for different set of resources on a single app, ImageKit now allows PDF, JS, CSS and TXT file upload to it’s media library.

Generating signature for the upload

The process of generating a signature for a file upload remains the same as that explained for image upload in the section above. Use the file’s name instead of the PDF name

Never expose your private key on the client-side. All signature generation should take place on the server.

Server-side file upload, using public key:

curl -X POST
     -F "filename=my_file"
     -F "useUniqueFilename=true"
     -F "file=@/path/to/file.pdf;type=application/pdf"
     -F "folder=/files/"
     -F "signature=generatedsignaturefromyourcode"
     -F "apiKey=mypublickey"
     -F "timestamp=1475592319" 
     "https://upload.imagekit.io/rest/api/static/v2/myimagekitid"

Fill in with actual imagekitId, file and timestamp.

Output for successful upload:

{
  "imagePath": "files/my_file_BJyuWdf0.jpg",
  "size": 51198
}

HTTP Request

POST https://upload.imagekit.io/rest/api/static/v2/<imagekitId>
Content-Type : multipart/form-data

Path Parameters

Parameter	Required	Description
imagekitId	Yes	The ImageKit Id associated with your account

Form Parameters

Parameter	Required	Description
file	Yes	The base64 encoded file that has to be uploaded
filename	Yes	The name with which the file has to be uploaded
apiKey	Yes	Your public API key
signature	Yes	HMAC-SHA1 signature generated for the file upload
timestamp	Yes	UTC timestamp in seconds. The request will be valid for 30 minutes from this timestamp.
useUniqueFilename	No	“true” or “false”. If set to true, ImageKit will add a unique code to the filename parameter to get a unique filename. If false, the file is uploaded with the filename parameter as name. If a file exists with the same name, this new file will override it. Default is “true”
folder	No	The folder path (eg- `/files/folder/`) in which the file has to be uploaded. Default is “/”

Response Codes

HTTP Status	Status Number (Status Code)	Description
400	1400 (BAD_REQUEST)	Invalid or missing form parameters in the request or file too large
403	1403 (ACCESS_FORBIDDEN)	Invalid signature or expired request
404	1404 (UNMAPPED_REQUEST)	Invalid ImageKit Id
500	1500 (SERVER_ERROR)	Internal server error while uploading the file

Server-side Upload via URL (Beta)

As a method of convenience, ImageKit allows you to upload images and PDF, JS, CSS and TXT files to the ImageKit Media Library from a remote HTTP(S) accessible URL. The image or the file is downloaded from the URL provided and uploaded to the Media Library.

Generating signature for the upload

The process of generating a signature for a file upload via URL remains the same as that explained for image upload in the section above. Use the API Key, Filename and Timestamp to generate the signature using your secret key.

Never expose your private key on the client-side. All signature generation should take place on the server.

Server-side upload via URL with public key

    curl -X POST 
         -H "Content-Type: application/x-www-form-urlencoded" 
         -d 'url=https://example.com/path/to/my/image.jpg&filename=abc.pdf&useUniqueFilename=true&folder=/images/&apiKey=myapikey&signature=mysignature&timestamp=1510829509'
    "https://upload.imagekit.io/rest/api/url/v2/myimagekitid"

Fill in with actual imagekitId, url, filename and timestamp.

Output for successful upload:

{
  "imagePath": "files/my_file_BJyuWdf0.jpg",
  "size": 51198
}

HTTP Request

POST https://upload.imagekit.io/rest/api/url/v2/<imagekitId>
Content-Type : application/x-www-form-urlencoded

Path Parameters

Parameter	Required	Description
imagekitId	Yes	The ImageKit Id associated with your account

Form Parameters

Parameter	Required	Description
url	Yes	The HTTP(S) accessible URL for the file that has to be uploaded. The protocol http:// or https:// also needs to be included.
filename	Yes	The name with which the file has to be uploaded
apiKey	Yes	Your public API key
signature	Yes	HMAC-SHA1 signature generated for the file upload
timestamp	Yes	UTC timestamp in seconds. The request will be valid for 30 minutes from this timestamp.
useUniqueFilename	No	“true” or “false”. If set to true, ImageKit will add a unique code to the filename parameter to get a unique filename. If false, the file is uploaded with the filename parameter as name. If a file exists with the same name, this new file will override it. Default is “true”
folder	No	The folder path (eg- `/files/folder/`) in which the file has to be uploaded. Default is “/”

Response Codes

HTTP Status	Status Number (Status Code)	Description
400	1400 (BAD_REQUEST)	Invalid or missing form parameters in the request or file not downloadable
403	1403 (ACCESS_FORBIDDEN)	Invalid signature or expired request
404	1404 (UNMAPPED_REQUEST)	Invalid ImageKit Id
500	1500 (SERVER_ERROR)	Internal server error while uploading the file

Admin API

Purging

You can purge single image URL using this API endpoint.

Generating signature for the purge request

Each purge request must be signed. The signature is a mandatory parameter in the request. To calculate the signature.

The parameters url, imagekitId that have to be sent in the image purge request have to be included in the signature.
Sort the parameters in the alphabetical order of the keys i.e. imagekitId comes before url.
Append the value of each of these parameters with the key using an = sign to get a key-value pair.
Append these key value pairs to each other using & to get a serialized string of the parameters.
Example - If the url is https://ik.imagekit.io/yourimagekitID/example-image.jpeg, imagekitId is yourimagekitID, then the string to be used for signature will be imagekitId=yourimagekitID&url=https://ik.imagekit.io/yourimagekitID/example-image.jpeg.
Using your private key as the key, calculate a hexadecimal HMAC-SHA1 digest of this serialized string.

Never expose your private key on the client-side. All signature generation should take place on the server.

Purge API example:

curl -X POST
     -F "url=https://ik.imagekit.io/yourimagekitID/example-image.jpeg"
     -F "imagekitId=yourimagekitID"
     -F "signature=generatedsignaturefromyourcode"
     "https://imagekit.io/api/admin/purge"

Fill in with actual imagekitId, url.

Output for successful purge request:

{
  "requestId": "RequestID which you can use to get status of purge request"
}

HTTP Request

POST https://imagekit.io/api/admin/purge
Content-Type : multipart/form-data

Form Parameters

Parameter	Required	Description
url	Yes	The URL which needs to be purged from ImageKit and CDN
imagekitId	Yes	ImageKit ID associated with your account
signature	Yes	HMAC-SHA1 signature generated for the this request

Response Codes

HTTP Status	Status Number (Status Code)	Description
400	1400 (BAD_REQUEST)	Invalid or missing form parameters in the request
403	1403 (ACCESS_FORBIDDEN)	Invalid signature
404	1404 (UNMAPPED_REQUEST)	Invalid ImageKit Id
500	1500 (SERVER_ERROR)	Internal server error while purging the file

Purge status

To get the status of purge request, use the requestId returned in the response of purge API:

GET https://imagekit.io/api/admin/purge/status/<requestID>

Get media library file

You can get the list of files uploaded in media library using this admin API.

Generating signature for the list uploaded files request

Each request must be signed. The signature is a mandatory parameter in the request. To calculate the signature.

The parameters skip, limit, imagekitId that have to be sent in the request have to be included in the signature. Maximum value of limit can be 1000.
Sort the parameters in the alphabetical order of the keys i.e. imagekitId comes before limit.
Append the value of each of these parameters with the key using an = sign to get a key-value pair.
Append these key value pairs to each other using & to get a serialized string of the parameters.
Example - If the skip is 0, limit is 1000, then the string to be used for signature will be imagekitId=yourimagekitID&limit=1000&skip=0.
Using your private key as the key, calculate a hexadecimal HMAC-SHA1 digest of this serialized string.

Never expose your private key on the client-side. All signature generation should take place on the server.

List files API example:

curl 'https://imagekit.io/api/admin/media/listFiles?skip=0&limit=1000&imagekitId=yourimagekitID&signature=generatedsignaturefromyourcode'

Fill in with actual imagekitId, skip, and limit.

Output for successful list files request:

[  
   {  
      "name":"test.jpg",
      "url":"https://ik.imagekit.io/test.jpg"
   },
   {  
      "name":"gate.jpg",
      "url":"https://ik.imagekit.io/new-uploaded-files/gate.jpg"
   }
]

HTTP Request

GET https://imagekit.io/api/admin/media/listFiles

Form Parameters

Parameter	Required	Description
skip	Yes	The number of files you want to skip from the response
limit	Yes	The maximum number of URLs you want in response. The maximum allowed value is 1000.
imagekitId	Yes	ImageKit ID associated with your account
signature	Yes	HMAC-SHA1 signature generated for the this request

Response Codes

HTTP Status	Status Number (Status Code)	Description
400	1400 (BAD_REQUEST)	Invalid or missing form parameters in the request
400	1401 (BAD_REQUEST)	Limit parameter value is more than 1000
403	1403 (ACCESS_FORBIDDEN)	Invalid signature
404	1404 (UNMAPPED_REQUEST)	Invalid ImageKit Id
500	1500 (SERVER_ERROR)	Internal server error while deleting the file

Delete media library file

You can delete the files uploaded in media library from the dashboard or using this admin API.

Generating signature for the delete request

Each delete request must be signed. The signature is a mandatory parameter in the request. To calculate the signature.

The parameters path, imagekitId that have to be sent in the file delete request have to be included in the signature.
Sort the parameters in the alphabetical order of the keys i.e. imagekitId comes before path.
Append the value of each of these parameters with the key using an = sign to get a key-value pair.
Append these key value pairs to each other using & to get a serialized string of the parameters.
Example - If the path is example-image.jpeg, imagekitId is yourimagekitID, then the string to be used for signature will be imagekitId=yourimagekitID&path=example-image.jpeg.
Using your private key as the key, calculate a hexadecimal HMAC-SHA1 digest of this serialized string.

Never expose your private key on the client-side. All signature generation should take place on the server.

Delete API example:

curl -X POST
     -F "path=example-image.jpeg"
     -F "imagekitId=yourimagekitID"
     -F "signature=generatedsignaturefromyourcode"
     "https://imagekit.io/api/admin/media/deleteFile"

Fill in with actual imagekitId, path.

Output for successful delete request:

{
  "success": true
}

HTTP Request

POST https://imagekit.io/api/admin/media/deleteFile
Content-Type : multipart/form-data

Form Parameters

Parameter	Required	Description
path	Yes	The imagePath that you get when uploading image. It excludes any URL-pattern and hostname.
imagekitId	Yes	ImageKit ID associated with your account
signature	Yes	HMAC-SHA1 signature generated for the this request

Response Codes

HTTP Status	Status Number (Status Code)	Description
400	1400 (BAD_REQUEST)	Invalid or missing form parameters in the request
403	1403 (ACCESS_FORBIDDEN)	Invalid signature
404	1404 (UNMAPPED_REQUEST)	Invalid ImageKit Id
500	1500 (SERVER_ERROR)	Internal server error while deleting the file

SDKs and Plugins

ImageKit provides SDKs and plugins that make it easy to integrate image uploads and image get requests in your application. The documentation of how to use a particular SDK or plugin in your application is provided below-