Getting started

Integration & migration

Image & video API

DAM user guide

API overview


Video Transformation

Learn how to transform videos using the URL-based transformation parameters.

ImageKit lets you manipulate videos on the fly using URL-based transformations. Using simple URL parameters, you can resize, crop, trim, get thumbnails, create adaptive bitrate streams, and apply various other transformations to videos.

Basic example

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

        URL endpoint        Transformation    Video path                                    

Let's see a basic resizing example. We will add a transformation parameter to the video URL below:

Video transformation overview

Overview of different video transformations available in ImageKit.

Limits and supported video formats

Refer to supported video formats for a list of video formats supported by for transformations. Check out various limits.


Every new video transformation that has never been done before will contribute toward video processing units using the below definition. Subsequent views of the same video transformation only count towards bandwidth.

Video processing units used depend on output video codec, duration, and resolution.

Calculation of units for resolution:

  • 1 second of SD video output = 1 unit
  • 1 second of HD video output = 2 units
  • 1 second of 4K video output = 4 units
  • 1 second of 8K video output = 8 units
  • 1 second of 16K video output = 16 units

Calculation of units for video codec:

  • 1 second of video output in H.264 codec = 1 unit
  • 1 second of video output in VP9 codec = 1 unit
  • 1 second of video output in AV1 codec = 10 units

VPU (Video Processing Unit) usage = Duration (in seconds) × Resolution (in units) × Video Codec (in units)

Special operations:

  • Audio extraction - Using vc-none transformation results in audio output. This operation is equal to processing the input video in SD output resolution for the duration of the output audio.
  • Adaptive bitrate streaming - This operation is equal to processing a 30 seconds SD resolution video. In addition, all generated representations are charged based on requested resolutions.
  • Get thumbnail - This operation is equal to processing a 30-second SD resolution video.

We define resolutions in terms of total pixel count as the following.

SDLess than 921,600 total pixels, i.e., less than 1280 × 720.
HDGreater than or equal to 1280 × 720 but less than 3840 × 2160.
4KGreater than or equal to 3840 × 2160 but less than 7680 × 4320.
8KGreater than or equal to 7680 × 4320 but less than 15360 × 8640.
16KGreater than or equal to 15360 × 8640.

First-time request and cache

When you issue a request to transform a video, ImageKit looks for the transformed video in its cache. If the transformed video is not found in the cache, ImageKit will accept and start processing the requests. However, on the first request and subsequent requests, while the video is being processed, ImageKit can do either of the following things:

  • Return a 302 status code with a Location header pointing to the original video URL. This ensures that the user gets the video even if the transformation is not ready. If you use the URL in a video tag, the browser will automatically follow the redirect and play the video.
  • Waits for the transformation to complete and then serves the transformed video.

You can control the waiting behavior from the dashboard settings. However, the maximum wait time is 15 seconds, after which ImageKit will redirect to the original video URL.


Here are a few recommendations you should follow while using video API in a live environment.

Eagerly generate transformation

Whether a video is optimized or transformed, a new video(s) is generated and saved internally by ImageKit. Depending on the video duration, output format, and transformation parameters, this process could take a few seconds. Therefore, you should eagerly generate the transformation before using the video URL in a live environment to ensure it works as expected. It guarantees that all necessary transformations are prepared and ready to be served. This avoids unnecessary data transfer costs on your origin. You can listen to video webhook events to get updates on asset transformations.

If you upload video files to ImageKit using the upload API, you can use the transformation parameter to eagerly generate the transformation. This parameter accepts a comma-separated list of transformations that you want to apply to the video post-upload. Learn more.

Check assets in Chrome and Safari

ImageKit prepares a webm and mp4 variant of the video to serve optimized video to your users. In a few cases, for specific input videos, the encoding could permanently fail for one or both formats. In this case, you will always get 302 instead of 200. Using such a URL in a live environment would result in repeated transformation attempts. This will unnecessarily increase origin data transfer at your end. To ensure that the video is ready in both formats, always fetch the same URL in both Chrome and Safari.