NAV
cURL NodeJS

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 sources or servers to your ImageKit account or upload new images directly to your ImageKit storage. 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

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

Default Image Storage

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. You can access it by going to the Media Library section of your dashboard. The size of the storage will depend on your pricing plan.

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

You can upload images to this default storage from the Media Library section in the dashboard or using the upload APIs. All the images uploaded to your ImageKit storage 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.

Migration

Apart from the default storage that comes along with your ImageKit account, 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. And because it is virtually impossible to confidently migrate all your existing images from your existing image servers to ImageKit, we have made the migration simpler with our Plug-and-Play techology.

This is the best possbile way of migrating your existing images to ImageKit. With this you can plug all your existing image sources to your ImageKit account and start getting all the benefits of ImageKit on your existing images instantly. No migration needed at all.

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

Image Sources

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

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

  1. AWS S3 Bucket / Folder
  2. A Web server

Once you add a source to your ImageKit account, all images from that image source, 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 sources is very simple and has been explained later in the examples section.

Once an image from one of your added sources 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 source for your ImageKit account and can be used to store and deliver images even if you don’t add any other source of images.

URL Patterns

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

Your ImageKit account comes with a default / 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, also contains / in the URL. The purpose of a pattern is to identify the sources from which the image will be fetched. Any image source that you add to your account, would become accessible using the / URL pattern. You can alter the order of preference in which these image sources 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 sources or multiple URL patterns can be setup, each one for an individual source. In case of multiple sources against a single URL pattern, ImageKit attempts to retrieve the image from each of the sources sequentially. Since the media library is the default source of images for all ImageKit accounts, it is always checked first for any image request.

Adding a Source

Adding an AWS S3 Bucket or Folder as a source

  1. Go to the migration section in your dashboard. Click on the “Add New Source” button.

  2. In the form that opens up, select “Amazon S3” as the type.

  3. In the “Name” field, enter any name for this new source like “MyS3Images”. The source name is just for you to easily identify a source.

  4. Enter your S3 bucket’s name in the “S3 Bucket” field.

  5. 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.

  6. 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 source form.

  7. Click on “Save” and all the images inside your S3 bucket at the specified S3 prefix would become accessible using ImageKit.

  8. 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 http://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 a source

  1. Go to the migration section in your dashboard. Click on the “Add New Source” button.

  2. In the form that opens up, select “Web Folder” as the type.

  3. In the “Name” field, enter any name for this new source like “MyImages”. The source name is just for you to easily identify a source.

  4. Let’s say you currently access your images at http://www.mywebsite.com/images/webserver_image.png. Then in the “Base URL” field you can enter http://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 http://www.mywebsite.com/images will be the base URL and only webserver_image.png would appear in the new URL.

  5. Example - You orignally access your images using http://www.mywebsite.com/images/webserver_image.png. The Base URL is http://www.mywebsite.com/images. Then the new ImageKit URL would be http://ik.imagekit.io/<imagekitId>/webserver_image.png. Whatever appears after “ in the ImageKit URL is added to your base URL for access.

Editing a Source

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

Adding a URL pattern

Any source 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 sources.

  1. Go to the migration section in your dashboard. Click on the “Add New Pattern” button.

  2. In the form that opens up, enter the pattern that you want in the “URL Prefix” field. A pattern name can only consist of alphabets, numbers and hyphen. So “images”, “my-images”, “2007-images” etc are valid pattern names.

  3. In the description field, you can enter any thing that will help you identify the purpose of the URL pattern

  4. The first source is always ImageKit and cannot be changed. You can start selecting your sources starting from the 2nd source preference. The sources are checked for an image in the same preference order that you specify here.

  5. The sources that you have added will appear in a dropdown when you click on any of the preference fields. Ensure that while selcting the sources, you don’t repeat the same source twice in the preference order.

  6. If you don’t want to provide all the preference options, you should leave them blank or “None”.

  7. Example - Let’s say you have 3 image sources - 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 sources 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.

 

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

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

This options specifies the degrees by which the output image has to be rotated.


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

 

Overlays

overlay transformation


    <!-- Image with height 300px overlaid with a logo at the center -->
    http://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: http://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:
http://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.


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.


Image with height 300px overlaid with a logo at the 10px from top and 5px from left edge

 

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-

  1. 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).

  1. 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 storage directly and not on one of your original image sources. 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


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.

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

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:

  1. 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 http://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.

  2. Create a HMAC-SHA1 signature of the above string using your private key as the key.

  3. Get the hex digest of the above signature and attach it to the URL as a query parameter named ik-s.

  4. 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.

  1. 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.

  2. Sort the parameters in the alphabetical order of the keys i.e. apiKey comes before filename which comes before timestamp.

  3. Append the value of each of these parameters with the key using an = sign to get a key-value pair.

  4. Append these key value pairs to each other using & to get a serialized string of the parameters.

  5. 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.

  6. 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" 
     "http://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 storage.

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" 
     "http://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

 

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-

NodeJS

NPM package

Python

Python package

.NET

.NET integration

Client-side jQuery plugin

ImageKit client-side jQuery plugin

Wordpress plugin

See on Wordpress

Shopify Integration

ImageKit.io integration on Shopify

cURL NodeJS