Transform and adapt media assets

ImageKit offers 50+ real-time URL-based transformations, empowering you to adapt your media assets to your needs. These transformations enable you to resize, crop, rotate, and optimize images and videos on the fly. You can even add text and image overlays to create personalized and captivating media experiences.

With ImageKit, engineering teams can modify assets on the fly without generating and storing multiple versions of the same asset. This allows you to avoid the complexity of multiple asynchronous tools and provider-specific processing implementations. ImageKit's developer-friendly, real-time media processing API simplifies your workflow, allowing you to quickly create high-quality, media-rich experiences.

You can apply transformations by adding specific parameters to the asset's URL. When a request is made to the transformed URL, ImageKit processes the request and returns the transformed asset.

Here's the basic structure of a URL-based transformation:

        URL endpoint        transformation    asset path 
┌──────────────────────────┐┌────────────┐┌────────────────┐
https://ik.imagekit.io/demo/tr:w-300,h-300/example-asset.jpg

For example, let's say you have an image asset at the following URL:

https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg

To resize this image to 300x300 pixels, you can append the tr:w-300,h-300 transformation parameter to the asset URL:

                               transformation
                               ┌────────────┐
https://ik.imagekit.io/ikmedia/tr:w-300,h-300/docs_images/examples/example_food_3.jpg

The same transformation can be passed as query parameters as well:

                                                                       transformation
                                                                       ┌────────────┐
https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg?tr=w-300,h-300

Here's how the original and resized images look side by side:

Here is a table of transformations that you can apply to your media assets:

When you apply transformations to your media assets, ImageKit returns 400 Bad Request. This error occurs when the transformation parameters are incorrect, or the transformation is not supported.

To help you troubleshoot and debug transformation errors, ImageKit returns an ik-error header in the response. The ik-error header provides detailed information about the error, including the error code and a description.

The error can be very specific or generic, depending on the issue. Here's an example of an ik-error header with a generic error message:

Here are some limits to keep in mind when using transformations. Most of the limits are adjustable based on your pricing plan. Please contact support if you need to adjust these limits.

ImageKit supports a wide range of image, video, and audio formats in input for transformation and optimization. By default, ImageKit chooses an optimal output format based on input and browser compatibility. However, you can always specify the output format based on your requirements. Here are some of the most common formats:

• Image formats: JPEG, PNG, WebP, AVIF, GIF, animated WebP, and animated PNG are the image formats that ImageKit can accept in the input, transform, optimize, and deliver in the output. SVG input can be rasterized by specifying dimensions or a raster format in the output. HEIC input will always be converted to JPEG, PNG, and WebP output formats.
• Video and audio formats: For input, ImageKit supports MP4, MOV, WebM, MPEG, 3GP, OGG, OGV, and HEVC video formats. The video codec can be H.264, MPEG4, HEVC, AV1, VP8, VP9, and H.263. The audio codec can be AAC, Opus, MP2, and Vorbis. ImageKit will always convert to an MP4 or WebM container with H.264, VP9, or AV1 video codec for output. The audio codec will be AAC or Opus based on compatibility.
• Other file formats: If a format is not supported for transformation and optimization, you can still use ImageKit to deliver the file as it is. This allows you to serve PDF, DOC, JS, JSON, CSS, and even HTML files through ImageKit. By default, all text-based files are compressed and served with GZIP or Brotli compression based on the browser support.

Using chained transformations, you can chain the output of one transformation as the input for the next to create the desired output.

A colon separates each step in the chained transform:, and they are applied in the sequence in which they appear. For example, w-400,h-300:rt-90 first resizes the image to 400x300 pixels and then rotates the image by 90 degrees.

                                  1st → Resize to 400x300                               
                                  ┌─────────┐
https://ik.imagekit.io/ikmedia/tr:w-400,h-300:rt-90/default-image.jpg
                                              └───┘
                                              2nd → Rotate by 90°

Chained transformation is especially useful when creating personalized media experiences using multiple text and image overlays.

For example, an image like this:

Let's understand the chained transformation applied to this image:

1. Resize to 400x400

This is fairly straightforward w-400,h-400

2. Add a 100px padding to the left

100px padding on the left means the resulting image will have a width of 400+100px = 500px. The image should be completely on the right in this image. This is achieved using the pad_resize crop mode (to pad the image in case resize doesn't match the aspect ratio) along with the focus parameter set to the right (to focus the image to the right). We also need to set the background to black (#000000). The transformation thus becomes -

w-500,h-400,cm-pad_resize,fo-right,bg-000000

3. Overlay ImageKit.io's logo

ImageKit's logo is accessible at path logo-white_SJwqB4Nfe.png, and then we can position and resize the overlay using overlay lx, ly, and overlay height transforms, respectively. The transformation thus becomes

l-image,i-docs_images@@examples@@logo-white_SJwqB4Nfe_zsEuI_3S4.png,lx-10,ly-40,h-20,l-end

We combine these three steps into a chain, separating each step by a colon :. The final chained transformation is:

w-400,h-400:w-500,h-400,cm-pad_resize,fo-right,bg-000000:l-image,i-docs_images@@examples@@logo-white_SJwqB4Nfe_zsEuI_3S4.png,lx-10,ly-40,h-20,l-end

Open the final URL

Named transformations within ImageKit.io are aliases or names you can give for a complex URL transformation string. Named transformations make it easy to remember and use complex transformation strings in your code. Overall, it makes your code more readable and clean. Named transformation works across images and videos.

For example, let's say our original URL is
https://ik.imagekit.io/ikmedia/tr:w-300,h-200,bl-10/default-image.jpg

We can replace the transformation string tr:w-300,h-200,bl-10 with an easy-to-remember named transformation blur_thumbnail.

URL with Named Transformation becomes
https://ik.imagekit.io/ikmedia/tr:n-blur_thumbnail/default-image.jpg

You can create and manage named transformations within the ImageKit.io dashboard.

A layer is a special transformation in which you can specify an asset to be used as an overlay, along with its positioning and transformations. It supports nesting, allows you to modify the overlay itself, and expresses its position relative to the parent.

A layer starts with l-<type> and ends with l-end. All the positional and transformation parameters of that layer are between l-<type> and l-end and only apply to that layer and not the parent base asset.

type can be image, video, or text.

For example, in the following URL, we are adding a logo image logo.png on top of a base image, i.e. sample-image.jpg. However, we applied width (w-10) and rotation (rt-90) transformations on this overlay logo image before placing it on the base image. Transformations w-300,h-300 are applied to sample-image.jpg.

Here, the parent base image has one layer inside it. A layer can also nest another layer.

         URL endpoint           Base image                                Layer
┌──────────────────────────┐┌──────────────┐                ┌─────────────────────────────────┐
https://ik.imagekit.io/demo/sample-image.jpg?tr=w-300,h-300,l-image,i-logo.png,w-10,rt-90,l-end
                                                └────┬────┘                    └────┬────┘
                                                     │                              │
                                                     │             These transformations are applied to logo.png
                                                     │
                              These transformations are applied to sample-image.jpg

The input of the layer can be specified using i or ie (base64 encoded) parameter. In case both i and ie are present, i is ignored. The base64 string should be made URL-safe to ensure that all padding characters (=) are included correctly. In Javascript, a function like encodeURIComponent() can be used for this.

The position of the layer can be controlled using the following parameters. The position of the layer is always relative to the immediate parent. For instance, the parent is the base image in the above example, and the logo image is the nested layer.

Note: If one or both of lx and ly parameters are specified along with lfo, then lfo parameter is ignored.

A layer can have nested layers up to 3 levels.

For example, in the below URL, i-inner.png is rendered on the top-left corner of i-outer.png using the lfo-top_left parameter.

                         Parent layer
┌──────────────────────────────────────────────────────────────┐
l-image,i-outer.png,l-image,i-inner.png,lfo-top_left,l-end,l-end
                    └──────────────────┬──────────────────┘
                                       │
                                  Nested layer

Learn more with examples.

• Add image overlay on images and videos.
• Add text overlay on images and videos.
• Add video overlay on videos.
• Add solid color blocks over images and videos.
• Add subtitles on videos.