# ImageKit Documentation (full)



---

# Source: /overview

---
title: Get started
description: Create an account and use ImageKit to deliver and manage perfect media experiences.
---

{% callout style="info" %}
If you are using ImageKit for Digital Asset Management, follow the steps from our [DAM Guide](./dam/overview#points-to-consider-before-using-the-dam) after creating the account.
{% /callout %}

## Step 1: Create an ImageKit account

If you still need to create an account, [sign up for free](https://imagekit.io/registration). The free plan offers generous limits and is well-suited for small-scale projects.

Once you've verified your email and logged in, you will be prompted to enter a few details about yourself and your use-cases around ImageKit.

![Step 1: Quick details](https://ik.imagekit.io/ikmedia/docs_images/getting-started/quickstart-guides/onboarding-step-1.png?tr=w-1600)

In the next step, you will be prompted to select an ImageKit ID and a processing region during the account setup process.

![Step 2: Selecting ImageKit ID and processing region](https://ik.imagekit.io/ikmedia/docs_images/getting-started/quickstart-guides/onboarding-step-2.png?tr=w-1600)

* The **ImageKit ID** serves as a unique identifier for your account and will appear in the URLs of your images & videos, for example, `https://ik.imagekit.io/your_imagekit_id/image.jpg`. Feel free to choose any unique identifier that suits your brand.
* The **processing region** is crucial as it determines where your media files are stored and processed. Choose your processing region based on your [integration strategy](#step-2:-plan-your-integration) with ImageKit, compliance needs, and your audience's geographical location. ImageKit has seven processing regions: North California (United States), North Virginia (United States), Frankfurt (Europe), Mumbai (India), Singapore (Singapore), Sydney (Australia), and Montreal (Canada).

{% callout style="info" %}
On the enterprise plan, ImageKit lets you create [sub-accounts](/sub-accounts) to manage different environments like staging, production, etc. Each sub-account has its own API key, Media Library, and settings. This setup is also helpful for agencies managing multiple clients.
{% /callout %}

## Step 2: Plan your integration

Regardless of how you currently store and serve your media assets, integrating ImageKit is straightforward. The platform offers two primary integration methods, each tailored to fit your specific requirements:

* **Connect existing storage** - Quickly attach your Amazon S3, Google Cloud Storage, Cloudinary backup bucket, or any web server with ImageKit. This method allows you to transform, optimize, and deliver existing media files through ImageKit without extensive migration. The setup takes a few minutes, and you can begin using ImageKit immediately with minimal or no changes to existing URLs. Learn more about [connecting existing storage](/integration/connect-external-storage).

* **Upload media to ImageKit storage** - For those preferring to centralize their media uploads, management, sharing, and collaboration, ImageKit provides a full-fledged Digital Asset Management platform. You can upload files directly through the dashboard, utilize the ImageKit API for bulk uploads and management, or use Rclone to synchronize files from any 70 cloud storage, including Google Drive, Dropbox, OneDrive, etc. Learn more about [uploading media to ImageKit](/dam/upload-assets).

{% callout style="info" title="Tips" %}
1. Both methods offer equal performance, transformation & optimization capabilities. The best approach for you will depend on your existing infrastructure and specific needs.
2. If you integrate existing storage with ImageKit, select a processing region nearest your storage to optimize performance. If you migrate your media to ImageKit storage, choose a region closest to your audience to expedite content delivery.
3. Most customers start by connecting their existing storage to ImageKit. Gradually, different teams within the organization start using ImageKit DAM for new uploads and managing marketing assets.
4. If you are migrating from Cloudinary, Imgix, or another service, read our [migration guide](/migration/overview).
{% /callout %}

## Step 3: Integrate into your application

Start using ImageKit.io URLs in your application to deliver perfect images and videos.

* To integrate ImageKit into your application, follow one of our platform-specific quick-start guides for developers. The guide covers common use cases, such as rendering images and videos, uploading media, and applying transformations. Checkout [quick start guides](/quick-start-guides).
* Learn different [transformations](/transformations) to deliver the perfect visual experience.
* Learn how to [optimize images & videos](/optimize-image-and-video-for-web-delivery) for web delivery.
* Refer to [production checklist](/production-checklist) before going live.


---

# Source: /quick-start-guides

---
title: Quick start guides
description: Integrate ImageKit into your application with quick start guides for different programming languages, frameworks, and CMS.
---

We maintain SDKs for various front-end, back-end, and mobile platforms and have listed plugins in marketplaces like WordPress, Magento, etc. The following quick start guides will help you integrate ImageKit using SDKs.

## Front-end

Front-end guides cover the following media use cases:

* Loading optimized images & videos.
* Basic resizing & cropping of images & videos.
* Adding text & image overlays.
* Using chained transformations to apply multiple transformations in a single request.
* Lazy loading images.
* Low-quality image placeholders.
* File upload, tagging, and metadata operations.

Choose your technology to get started with ImageKit:

{% quickstartLinksGrid %}

{% griditem %}
{% linkButton href="/integration/angular"  text="Angular" /%}
{% /griditem %}

{% griditem %}
{% linkButton href="/integration/javascript"  text="JavaScript" /%}
{% /griditem %}

{% griditem %}
{% linkButton href="/integration/nextjs"  text="Next.js" /%}
{% /griditem %}

{% griditem %}
{% linkButton href="/integration/astro"  text="Astro" /%}
{% /griditem %}

{% griditem %}
{% linkButton href="/integration/react"  text="React" /%}
{% /griditem %}

{% griditem %}
{% linkButton href="/integration/react-native"  text="React Native" /%}
{% /griditem %}

{% griditem %}
{% linkButton href="/integration/vuejs"  text="Vue.js" /%}
{% /griditem %}

{% /quickstartLinksGrid %}

{%callout type="info" %}
All front-end SDKs use the [ImageKit Javascript](https://github.com/imagekit-developer/imagekit-javascript) SDK. For more control and customization, use the JS SDK directly in your application.
{%/callout%}

## Mobile platforms

We have native SDKs for iOS and Android. These SDKs cover the following media use cases:

* Constructing URLs for optimized images & videos, including adaptive bitrate streaming for videos.
* Loading optimized images & videos. Android SDK integrates with popular image-loading libraries like Glide, Picasso, Coil, and Fresco.
* Responsive image loading.
* File upload and upload policy to control network type, retry policy, and more.
* Preprocessing images & videos before upload to control file size, dimensions, etc.

{% quickstartLinksGrid %}

{% griditem %}
{% linkButton href="https://github.com/imagekit-developer/imagekit-android" newtab=true  text="Android" /%}
{% /griditem %}

{% griditem %}
{% linkButton href="https://github.com/imagekit-developer/imagekit-ios"  newtab=true text="iOS" /%}
{% /griditem %}

{% /quickstartLinksGrid %}

{%callout type="info" %}
iOS SDK needs to catch up with Android SDK regarding features and updates. We are working on bringing the iOS SDK at par with the Android SDK.
{%/callout%}

## Back-end

Back-end guides cover the following media use cases:

* URL construction for optimized images & videos, including applying transformations.
* Generating signed URLs for secure delivery of media.
* Generating authentication parameters to facilitate secure upload from the client side.
* File upload, tagging, and metadata operations.
* Developer-friendly wrapper functions for media management APIs.

{% quickstartLinksGrid %}

{% griditem %}
{% linkButton href="https://github.com/imagekit-developer/imagekit-nodejs" newtab=true text="Node.js" /%}
{% /griditem %}

{% griditem %}
{% linkButton href="/integration/java"  text="Java" /%}
{% /griditem %}

{% griditem %}
{% linkButton href="/integration/php"  text="PHP" /%}
{% /griditem %}

{% griditem %}
{% linkButton href="/integration/python"  text="Python" /%}
{% /griditem %}

{% griditem %}
{% linkButton href="/integration/ruby" text="Ruby" /%}
{% /griditem %}

{% griditem %}
{% linkButton href="https://github.com/imagekit-developer/imagekit-dotnet/" newtab=true text=".NET" /%}
{% /griditem %}

{% griditem %}
{% linkButton href="https://github.com/imagekit-developer/imagekit-go" newtab=true text="Go" /%}
{% /griditem %}

{% /quickstartLinksGrid %}

## CMS & E-commerce platforms

{% quickstartLinksGrid %}

{% griditem %}
{% linkButton href="/integration/shopify"  text="Shopify" /%}
{% /griditem %}

{% griditem %}
{% linkButton href="/integration/wordpress"  text="WordPress" /%}
{% /griditem %}

{% griditem %}
{% linkButton href="/integration/magento"  text="Magento" /%}
{% /griditem %}

{% griditem %}
{% linkButton href="/integration/netlify"  text="Netlify" /%}
{% /griditem %}

{% griditem %}
{% linkButton href="/integration/strapi"  text="Strapi" /%}
{% /griditem %}

{% griditem %}
{% linkButton href="/integration/contentful"  text="Contentful" /%}
{% /griditem %}

{% griditem %}
{% linkButton href="/integration/sanity"  text="Sanity" /%}
{% /griditem %}

{% /quickstartLinksGrid %}

## AI & Developer Tools

Integrate ImageKit with AI assistants and coding agents for intelligent media management:

{% quickstartLinksGrid %}

{% griditem %}
{% linkButton href="/build-with-ai"  text="Build with AI" /%}
{% /griditem %}

{% /quickstartLinksGrid %}

{%callout style="info" %}
Install the ImageKit skills and MCP servers to let AI tools like Claude, Cursor, Windsurf, and VS Code Copilot manage media, write integration code, and build transformations using natural language. See [Build with AI](/build-with-ai).
{%/callout%}

## Upload Widget


ImageKit also provides a way to upload files using [Uppy](https://uppy.io/) and its [XHR Upload plugin](https://uppy.io/docs/xhr-upload/). You can find more about this in our sample application [here](https://github.com/imagekit-samples/uppy-uploader). Using Uppy, users can select files from sources such as the local file system, URLs, Dropbox, Google Drive, Instagram, and more, and upload them directly to your ImageKit Media Library.

## Sample applications & tutorials

We publish tutorials on blogs providing step-by-step instructions along with full code snippets. Here are a few tutorials that you might find interesting:

* Adding video player and implementing adaptive bitrate streaming - [React](https://imagekit.io/blog/react-video-player/) and [Next.js](https://imagekit.io/blog/nextjs-video-player/).
* File upload in [Angular](https://imagekit.io/blog/angular-image-video-upload/) and [PHP](https://imagekit.io/blog/php-image-and-video-upload).
* Check out [all our blogs](https://imagekit.io/blog).


---

# Source: /integration/javascript

---
title: JavaScript ImageKit SDK
description: Learn how to use the ImageKit JavaScript SDK for URL generation, responsive images and file uploads.
---

The ImageKit JavaScript SDK provides easy-to-use utility functions for generating optimized image and video URLs, applying a wide range of transformations (resize, crop, overlays, effects, and even AI-powered enhancements), generating responsive images `srcset`, and uploading files. It is designed specifically for browser-based environments. If you are looking to use ImageKit on Node.js, please refer to the [ImageKit Node.js SDK](https://github.com/imagekit-developer/imagekit-nodejs).

The SDK is lightweight, does not require any dependencies, and has first-class TypeScript support. You can view the [source code](https://github.com/imagekit-developer/imagekit-javascript) on GitHub.

## Installation and Setup

Install the SDK via npm or yarn:

```bash
npm install @imagekit/javascript
# or
yarn add @imagekit/javascript
```

You can also include the SDK directly in your HTML using a script tag. It is recommended to load a specific version to avoid unexpected breaking changes:

```html
<script src="https://unpkg.com/@imagekit/javascript@5.0.0/dist/imagekit.min.js"></script>
```

For environments with module bundlers (e.g., webpack, Rollup) or ES modules, simply import the functions:

```js
import { buildSrc, buildTransformationString, upload, getResponsiveImageAttributes } from '@imagekit/javascript';
```

The JavaScript SDK exports the following:

#### Utility functions
  - `buildSrc` - To generate complete URLs for images and videos with transformations.
  - `buildTransformationString` - To generate transformation strings so that you can use them in your own URL generation logic.
  - `upload` - To upload files to ImageKit.
  - `getResponsiveImageAttributes` - To generate responsive image attributes for `<img>` tags.

#### Error classes for upload error handling
  - `ImageKitInvalidRequestError` - For invalid requests.
  - `ImageKitAbortError` - For aborted uploads.
  - `ImageKitUploadNetworkError` - For network errors during upload.
  - `ImageKitServerError` - For server-side errors.

#### Type definitions
The SDK provides TypeScript type definitions for all the parameters and options used in the SDK. This includes types for `SrcOptions`, `UploadOptions`, `UploadResponse`, `Transformation`, `GetImageAttributesOptions`, and `ResponsiveImageAttributes`.

## URL Generation

The SDK provides two helper functions:
- `buildSrc` - To generate complete URLs for images and videos with transformations.
- `buildTransformationString` - To generate transformation strings so that you can use them in your own URL generation logic.

### buildSrc Parameters

The `buildSrc` function accepts an options object with the following parameters:

{% table %}

- Parameter {% width="30%" %}
- Description and Example {% width="70%" %}

---

- **urlEndpoint**  
  (Required)  
- The base URL endpoint from your [ImageKit dashboard](https://imagekit.io/dashboard/url-endpoints).  
  
  Example: `https://ik.imagekit.io/your_imagekit_id`

---

- **src**  
  (Required)  
- A relative or absolute path to the image or video.

  - If a **relative path** is provided, it is appended to the `urlEndpoint`.
  - If an **absolute path** is provided, it is used as-is and the `urlEndpoint` is ignored.
  - **Do not include query parameters** directly in the `src`. Use the `queryParameters` prop instead.
  - **When using a web proxy**, you can pass the full URL and prepend it with a `/`. For example - `/https://example.com/image.jpg`.

  **Examples:**  
  Relative - `/default-image.jpg`  
  Absolute - `https://example.com/image.jpg`  
  Web Proxy - `/https://example.com/image.jpg`

---

- **transformation**
- An array of transformation objects. Each object can include properties like `width`, `height`, `rotation`, overlays, and advanced effects.  
  
  Example: `[ { width: 300, height: 300 } ]`  
  
  See all [supported transformation](#supported-transformations) options and how to [handle unsupported transformations](#handling-unsupported-transformations).

---

- **queryParameters**
- An object with additional query parameters to append to the URL.  
  Example: `{ v: 2 }`

---

- **transformationPosition**
- Specifies whether the transformation string is included in the URL path or as a query parameter. Defaults to `"query"`.  
  Example: `"query"` or `"path"`

{% /table %}

### buildTransformationString Parameters

The `buildTransformationString` accepts an array of transformation objects and returns the transformation string.

```js
import { buildTransformationString } from '@imagekit/javascript';
const transformationString = buildTransformationString([
  { width: 300, height: 300 },
  { overlay: { type: "text", text: "Hello World" } }
]);
console.log(transformationString);
// Expected output: "w-300,h-300:l-text,i-Hello%20World,l-end"
```

## Height and Width Transformations

ImageKit allows you to resize images and videos on-the-fly using the `width` and `height` parameters.

```js
buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/photo.jpg",
  transformation: [{ width: 300, height: 300 }]
});
```

## Chained Transformations

You can chain multiple transformations together by passing an array of transformation objects. Each object can specify different properties, such as width, height, cropping, overlays, and effects. See [chained transformations](/transformations#chained-transformations) for more details.

```js
buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/photo.jpg",
  transformation: [
    { width: 400, height: 300 },
    { rotation: 90 }
  ]
});
```

## Responsive Images

The `getResponsiveImageAttributes()` utility function generates optimized values for `src`, `srcSet`, and optionally `sizes` to be used in `<img>` tags. It adheres to responsive image best practices and employs breakpoint logic similar to Next.js, ensuring that each device downloads the lightest image that still appears sharp.

### getResponsiveImageAttributes Parameters

The `getResponsiveImageAttributes` function accepts all parameters that `buildSrc` accepts, along with the following additional parameters:

{% table %}

- Parameter {% width="30%" %}
- Description and Example {% width="70%" %}

---

- **width**  
  (number)
- The intended display width of the image in pixels. This is used to calculate the `srcSet` attribute and is only utilized when `sizes` is not provided.
  
  Example: `100`.

---

- **sizes**  
  (string)
- The value for the HTML `sizes` attribute.
  - If it includes one or more vw units, breakpoints smaller than the corresponding percentage of the smallest device width are excluded.
  - If it contains no vw units, the full breakpoint list is used.

  Example: `"100vw"` or `"(min-width:768px) 50vw, 100vw"`

---

- **deviceBreakpoints**  
  (number[])
- It allows you to specify a list of device width breakpoints.

  Defaults to `[640, 750, 828, 1080, 1200, 1920, 2048, 3840]`.

---

- **imageBreakpoints**  
  (number[])
- It allows you to specify a list of image width breakpoints. It is concatenated with `deviceBreakpoints` before calculating `srcSet`. 
  
  Defaults to `[16, 32, 48, 64, 96, 128, 256, 384]`.

{% /table %}

### Responsive Image Logic

The logic for generating responsive images is as follows:

* If only `width` is provided, the function uses a DPR (Device Pixel Ratio)-based strategy. It rounds the specified width up to the nearest available breakpoint and generates two image candidates—one for `1×` and one for `2×` pixel densities. The resulting `srcSet` uses x-descriptors, and the `width` value is included in the returned object.
* If `sizes` is provided, the function follows a width-based strategy. It parses the smallest `%vw` value from the sizes string to determine the minimum required image width. Breakpoints smaller than this calculated value are excluded from the `srcSet`. The output uses a w-descriptor, and any value passed in the `width` parameter is ignored. Remember that `imageBreakpoints` is concatenated with `deviceBreakpoints` before calculating the `srcSet`.
* If neither `sizes` nor `width` is provided, the function defaults to using the full list of device breakpoints. In this case, the sizes attribute is set to `100vw` automatically, and a w-descriptor `srcSet` is generated using all available breakpoints.

### Recommended Responsive Image Usage

Specify `width` in pixels and `sizes` in `vw` units. This is the recommended way to use responsive images.

```js
const out = getResponsiveImageAttributes({
  src: 'sample.jpg',
  urlEndpoint: 'https://ik.imagekit.io/demo',
  width: 400,
  sizes: '(min-width:800px) 33vw, 100vw',
});
```

The output will look like this:

```bash
{
  src: "https://ik.imagekit.io/demo/sample.jpg?tr=w-3840,c-at_max",
  srcSet: "https://ik.imagekit.io/demo/sample.jpg?tr=w-256,c-at_max 256w, 
           https://ik.imagekit.io/demo/sample.jpg?tr=w-384,c-at_max 384w, 
           https://ik.imagekit.io/demo/sample.jpg?tr=w-640,c-at_max 640w, 
           https://ik.imagekit.io/demo/sample.jpg?tr=w-750,c-at_max 750w, 
           https://ik.imagekit.io/demo/sample.jpg?tr=w-828,c-at_max 828w, 
           https://ik.imagekit.io/demo/sample.jpg?tr=w-1080,c-at_max 1080w, 
           https://ik.imagekit.io/demo/sample.jpg?tr=w-1200,c-at_max 1200w, 
           https://ik.imagekit.io/demo/sample.jpg?tr=w-1920,c-at_max 1920w, 
           https://ik.imagekit.io/demo/sample.jpg?tr=w-2048,c-at_max 2048w, 
           https://ik.imagekit.io/demo/sample.jpg?tr=w-3840,c-at_max 3840w",
  sizes: "(min-width: 800px) 33vw, 100vw"
}
```

If neither `width` nor `sizes` is specified, the SDK will generate a `srcSet` using all available device breakpoints. The `sizes` attribute will default to `100vw`, assuming the image should span the full viewport width.

```js
const out = getResponsiveImageAttributes({
  src: 'sample.jpg',
  urlEndpoint: 'https://ik.imagekit.io/demo',
});
```

Expected output:

```bash
{
  src: "https://ik.imagekit.io/demo/sample.jpg?tr=w-3840,c-at_max",
  srcSet: "https://ik.imagekit.io/demo/sample.jpg?tr=w-640,c-at_max 640w, 
           https://ik.imagekit.io/demo/sample.jpg?tr=w-750,c-at_max 750w, 
           https://ik.imagekit.io/demo/sample.jpg?tr=w-828,c-at_max 828w, 
           https://ik.imagekit.io/demo/sample.jpg?tr=w-1080,c-at_max 1080w, 
           https://ik.imagekit.io/demo/sample.jpg?tr=w-1200,c-at_max 1200w, 
           https://ik.imagekit.io/demo/sample.jpg?tr=w-1920,c-at_max 1920w, 
           https://ik.imagekit.io/demo/sample.jpg?tr=w-2048,c-at_max 2048w, 
           https://ik.imagekit.io/demo/sample.jpg?tr=w-3840,c-at_max 3840w",
  sizes: "100vw"
}
```

If you specify a `width` but omit `sizes`, the SDK will generate a `srcSet` using `1x` and `2x` descriptors based on the nearest matching breakpoints.

```js
const out = getResponsiveImageAttributes({
  src: 'sample.jpg',
  urlEndpoint: 'https://ik.imagekit.io/demo',
  width: 400,
});
```

The output will look like this:

```bash
{
  src: "https://ik.imagekit.io/demo/sample.jpg?tr=w-828,c-at_max",
  srcSet: "https://ik.imagekit.io/demo/sample.jpg?tr=w-640,c-at_max 1x, 
           https://ik.imagekit.io/demo/sample.jpg?tr=w-828,c-at_max 2x",
  width: 400
}
```

## Adding Overlays
You can add overlays to images and videos. The overlay can be a text, image, video, or subtitle.

Besides the overlay type, you can also specify the position, size, and other properties of the overlay. Check the [overlay options](#overlay-reference) for more details.

### Image Overlay

```js
// Image overlay example:
buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/background.jpg",
  transformation: [
    { 
      overlay: { 
        type: "image", 
        input: "logo.png"
      } 
    }
  ]
});
```

You can further transform the overlay image independently of the base image by adding additional transformation parameters. For example, to resize the overlay image:

```js
buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/background.jpg",
  transformation: [
    { 
      overlay: { 
        type: "image", 
        input: "logo.png", 
        transformation: [
          { width: 100, height: 100 }
        ]
      } 
    }
  ]
});
```

Image overlays support a wide range of transformations. Check [reference](/add-overlays-on-images#list-of-supported-image-transformations-in-image-layers) for a complete list of transformations supported on image overlays.

### Solid Color Overlay

You can add a solid color overlay to images and videos.

```js
buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/background.jpg",
  transformation: [
    { 
      overlay: { 
        type: "solidColor", 
        color: "FF0000" // Required
      } 
    }
  ]
});
```

You can also specify the width, height, and other properties of the solid color overlay. For example:

```js
buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/background.jpg",
  transformation: [
    { 
      overlay: { 
        type: "solidColor", 
        color: "FF0000", // Required
        transformation: [
          { width: 100, height: 100 }
        ]
      } 
    }
  ]
});
```

For more options related to styling the solid color overlay, check the [solid color overlay transformations](#solid-color-overlay-transformations) section.

### Text Overlay

You can add text overlays to images and videos.

```js
buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/background.jpg",
  transformation: [
    { 
      overlay: { type: "text", text: "Hello, ImageKit!" } 
    }
  ]
});
```

You can also specify the font size, color, and other properties of the text overlay. For example:

```js
buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/background.jpg",
  transformation: [
    { 
      overlay: { 
        type: "text", 
        text: "Hello, ImageKit!", 
        transformation: [
          { fontSize: 20, fontColor: "FF0000" }
        ]
      } 
    }
  ]
});
```

Check the [text overlay transformations](#text-overlay-transformations) section for more options related to styling the text.

### Video Overlay

You can add video overlays on videos only.

```js
buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/background.mp4",
  transformation: [
    { 
      overlay: { 
        type: "video", 
        input: "video.mp4"
      } 
    }
  ]
});
```

Additionally, you can specify the start and end time for the overlay video. For example:

```js
buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/background.mp4",
  transformation: [
    { 
      overlay: { 
        type: "video", 
        input: "video.mp4", 
        timing: { start: 5, duration: 10 } // Overlay appears at 5 seconds and lasts for 10 seconds
      } 
    }
  ]
});
```

You can also independently transform the overlay video. For example, to resize the overlay video:

```js
buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/background.mp4",
  transformation: [
    { 
      overlay: { 
        type: "video", 
        input: "video.mp4", 
        transformation: [
          { width: 100, height: 100 } // Resize overlay video independently
        ] 
      } 
    }
  ]
});
```

All supported [video transformations](/video-transformation) can also be applied to overlay videos.

If you're overlaying an image on a base video, refer to [this list](/add-overlays-on-videos#list-of-transformations-supported-on-image-overlay) for all the transformations supported on image overlays.

### Subtitle Overlay

You can add subtitle overlays on videos.

```js
buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/background.mp4",
  transformation: [
    { 
      overlay: { type: "subtitle", input: "subtitle.srt" } 
    }
  ]
});
```

The subtitle overlay can be styled with various properties such as font size, color, and outline. See the [Subtitle Overlay Transformations](#subtitle-overlay-transformations) section for all styling options.

## Background Removal Using AI

You can use the `aiRemoveBackground` transformation to remove the background from images. This is particularly useful for e-commerce applications.

```js
buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/photo.jpg",
  transformation: [{ aiRemoveBackground: true }]
});
```

ImageKit supports multiple AI-powered transformations, like upscaling, generative fill, and more. You can use these transformations to enhance your images without needing to manually edit them. Check the [AI Transformations](/ai-transformations) section for more details.

More examples:

```js
// Drop shadow using AI
buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/photo.jpg",
  transformation: [{ aiDropShadow: true }]
});

// Upscale a small image using AI
buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/photo.jpg",
  transformation: [{ aiUpscale: true }]
});
```

## Arithmetic Expressions

You can use arithmetic expressions to dynamically compute transformation values. For example, to set the width to half of the original image width:

```js
buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/photo.jpg",
  transformation: [{ width: "iw_div_2" }]
});
```

Check out the [Arithmetic Expressions](/arithmetic-expressions-in-transformations) reference for more examples and details.


## Uploading Files

The `upload()` function enables you to upload files to ImageKit using [upload V1 API](/api-reference/upload-file/upload-file). It accepts an options object and returns a promise that resolves with an upload response. The SDK JSON stringifies certain parameters before sending them to the server as expected by the API. If the SDK does not support a parameter, it is added as-is in the request. Check the API documentation for more details.

### upload() Parameters

The `upload()` function accepts a JSON object with the following parameters:

{% table %}

- Option {% width="30%" %}
- Description and Example {% width="70%" %}

---

- **file**  
  (Required)  
- The file content to be uploaded. Accepts binary data, a base64-encoded string, or a URL. Typically used with a File or Blob in the browser. Example: `file: fileInput.files[0]`

---

- **fileName**  
  (Required)  
- The name to assign to the uploaded file. Supports alphanumeric characters, dot, underscore, and dash. Any other character is replaced with `_`. Example: `fileName: "myImage.jpg"`

---

- **signature**  
  (Required)  
- The HMAC-SHA1 digest of the concatenation of "token + expire". The signing key is your ImageKit private API key. Must be computed on the server side. Example: `signature: "generated_signature"`

---

- **token**  
  (Required)  
- A unique value to identify and prevent replays. Typically a UUID (e.g., version 4). Example: `token: "unique_upload_token"`
  
  Check the [signature generation](#generating-authentication-parameters) section for more details on how to generate this value.

---

- **expire**  
  (Required)  
- A Unix timestamp in seconds, less than 1 hour in the future. Example: `expire: 1616161616`
  
  Check the [signature generation](#generating-authentication-parameters) section for more details on how to generate this value.

---

- **publicKey**  
  (Required)
- The public API key for your ImageKit account. This is used to identify the account making the upload request. Example: `publicKey: "your_public_api_key"`
  
  Check the [signature generation](#generating-authentication-parameters) section for more details on how to generate this value.

---

- **onProgress**
- A callback function to track the upload progress. It receives an event object with `loaded` and `total` properties. Example: `onProgress: (event) => console.log(event.loaded, event.total)`
  This is useful for showing upload progress to the user.

---
- **abortSignal**
- An optional `AbortSignal` object to abort the upload request. If the signal is already aborted, the upload will fail immediately.
  You can create an `AbortController` instance and pass its signal to the `upload()` function.

---

- **useUniqueFileName**
- Boolean flag to automatically generate a unique filename if set to true. Defaults to true. If false, the image is uploaded with the provided filename, replacing any existing file with the same name. Example: `useUniqueFileName: true`

---

- **folder**
- The folder path where the file will be stored, e.g., "/images/folder/". If the path doesn't exist, it is created on-the-fly. Example: `folder: "/images/uploads"`

---

- **isPrivateFile**
- Boolean to mark the file as private, restricting access to the original file URL. A private file requires signed URLs or named transformations for access. Defaults to false. Example: `isPrivateFile: false`

---

- **tags**
- Optionally set tags on the uploaded file. Can be a comma-separated string or an array of tags. Example: `tags: "summer,holiday"` or `tags: ["summer","holiday"]`

---

- **customCoordinates**
- A string in "x,y,width,height" format that defines the region of interest in an image (top-left coords and area size). Example: `customCoordinates: "10,10,100,100"`

---

- **responseFields**
- A comma-separated or array-based set of fields to return in the upload response. Example: `responseFields: "tags,customCoordinates"`

---

- **extensions**
- An array of extension objects to apply to the image, e.g., background removal, auto-tagging, etc. Example: `extensions: [{ name: "auto-tagging" }]`

---

- **webhookUrl**
- A webhook URL to receive the final status of any pending extensions once they've completed processing. Example: `webhookUrl: "https://example.com/webhook"`

---

- **overwriteFile**
- Defaults to true. If false, and "useUniqueFileName" is also false, the API immediately fails if a file with the same name/folder already exists. Example: `overwriteFile: true`

---

- **overwriteAITags**
- Defaults to true. If true, and an existing file is found at the same location, its AITags are removed. Set to false to keep existing AITags. Example: `overwriteAITags: true`

---

- **overwriteTags**
- Defaults to true. If no tags are specified in the request, existing tags are removed from overwritten files. Setting to false has no effect if the request includes tags. Example: `overwriteTags: true`

---

- **overwriteCustomMetadata**
- Defaults to true. If no customMetadata is specified in the request, existing customMetadata is removed from overwritten files. Setting to false has no effect if the request specifies customMetadata. Example: `overwriteCustomMetadata: true`

---

- **customMetadata**
- A stringified JSON or an object containing custom metadata fields to store with the file. Custom metadata fields must be pre-defined in your ImageKit configuration. Example: `customMetadata: {author: "John Doe"}`

---

- **transformation**
- Defines pre and post transformations to be applied to the file during upload. The SDK enforces certain validation rules for pre/post transformations. Example: `transformation: { pre: "w-200,h-200", post: [...] }`

---

- **xhr**
- An optional XMLHttpRequest instance for the upload. The SDK merges it with its own logic to handle progress events, etc. Example: `xhr: new XMLHttpRequest()`

---

- **checks**
- A string specifying the checks to be performed server-side before uploading to the media library, e.g., size or mime type checks. Example: `checks: "file.size' < '1MB'"`

{% /table %}


## Upload Example and Error Handling

The `.upload` function requires you to send `token`, `signature`, `expire` and `publicKey` parameters. Check the [generating authentication parameters](#generating-authentication-parameters) section for more details on how to generate these values.

```js
import { upload, ImageKitInvalidRequestError, ImageKitAbortError, ImageKitUploadNetworkError, ImageKitServerError } from '@imagekit/javascript';

const fileInput = document.getElementById('fileInput');
const abortController = new AbortController(); // You can abort the upload using abortController.abort();

// Get required token, signature, and expire values from your server. Check the signature generation below for more details.

fileInput.addEventListener('change', async (e) => {
  const file = e.target.files[0];
  const uploadOptions = {
    file,
    fileName: file.name,
    token: "your_upload_token", // Check signature generation section for more details
    signature: "your_generated_signature",
    expire: Math.floor(Date.now() / 1000) + 3600,
    publicKey: "your_public_key",
    onProgress: (event) => {
      console.log(`Progress: ${event.loaded}/${event.total}`);
    },
    abortSignal: abortController.signal
  };
  
  try {
    const response = await upload(uploadOptions);
    console.log("Upload successful:", response);
  } catch (error) {
    if (error instanceof ImageKitAbortError) {
      // You aborted the upload
      console.error("Upload aborted:", error.reason);
    } else if (error instanceof ImageKitInvalidRequestError) {
      // You made an invalid request
      console.error("Invalid request:", error.message);
    } else if(error instanceof ImageKitUploadNetworkError) {
      // Random network error on client side
      console.error("Network error:", error.message);
    } else if (error instanceof ImageKitServerError) {
      // Error on ImageKit server side (5xx). Usually rare and temporary.
      console.error("Server error:", error.message);
    } else {
      // Any other error. You love JavaScript, right?
      console.error("Upload error:", error);
    }
  }
});
```

## Generating Authentication Parameters

The `.upload` function requires you to send `token`, `signature`, and `expire` parameters. These are used to authenticate the upload request. These values should be generated in your secure backend server and passed to the client. The SDK does not generate these values for you. However, all ImageKit SDKs (Java, PHP, Node.js, Python, Ruby, etc.) provide methods to generate these values. You can use any of these SDKs to generate the signature and token.

Check the [upload API documentation](/api-reference/upload-file/upload-file#how-to-implement-client-side-file-upload) for more details on how to generate the signature and token.

{% callout style="alert" %}
Never expose your private API key in the client-side code. Always generate the `token`, `signature`, and `expire` values on your server and pass them to the client securely.
{% /callout %}

Sample code to generate the signature and token:

{% tabs %}
{% tab title="Node.js" %}
```js
import ImageKit from '@imagekit/nodejs';

const client = new ImageKit({
    privateKey: "your_private_api_key"
});

const { token, expire, signature } = client.helper.getAuthenticationParameters();
console.log({token, expire, signature});
```
{% /tab %}

{% tab title="Go" %}
```go
import (
	"fmt"

	"github.com/imagekit-developer/imagekit-go/v2"
	"github.com/imagekit-developer/imagekit-go/v2/option"
)

client := imagekit.NewClient(
	option.WithPrivateKey("your_private_api_key"),
)

// Generate authentication parameters for client-side uploads
authParams, err := client.Helper.GetAuthenticationParameters("", 0)
if err != nil {
	fmt.Printf("Error: %v\n", err)
	return
}

fmt.Printf("Token: %v\n", authParams["token"])
fmt.Printf("Expire: %v\n", authParams["expire"])
fmt.Printf("Signature: %v\n", authParams["signature"])
```
{% /tab %}

{% tab title="Python" %}
```python
import os
from imagekitio import ImageKit

imagekit = ImageKit(
    private_key=os.environ.get("IMAGEKIT_PRIVATE_KEY")
)

auth_params = imagekit.helper.get_authentication_parameters()
print(auth_params)
# Output: {'token': 'unique_token', 'expire': <timestamp>, 'signature': 'generated_signature'}
```
{% /tab %}

{% tab title="Ruby" %}
```ruby
require 'imagekitio'

client = Imagekitio::Client.new(private_key: "your_private_api_key")

auth_params = client.helper.get_authentication_parameters
puts auth_params
# Output: {token: "unique_token", expire: <timestamp>, signature: "generated_signature"}
```
{% /tab %}

{% tab title="Java" %}
```java
import io.imagekit.client.ImageKitClient;
import io.imagekit.client.okhttp.ImageKitOkHttpClient;
import java.util.Map;

ImageKitClient client = ImageKitOkHttpClient.builder()
    .privateKey("your_private_key")
    .build();

Map<String, Object> authParams = client.helper().getAuthenticationParameters(null, null);
System.out.println(authParams);
// Output: {token=unique_token, expire=<timestamp>, signature=generated_signature}
```
{% /tab %}

{% tab title=".Net" %}
```csharp
using Imagekit;

ImageKitClient client = new() { PrivateKey = "your_private_key" };

var authParams = client.Helper.GetAuthenticationParameters();
Console.WriteLine(authParams);
```
{% /tab %}
{% /tabs %}

## Video Player SDK

Looking to embed videos with advanced playback features? The **ImageKit Video Player SDK** is a powerful video player built on Video.js with enhanced capabilities like **AI-generated subtitles and chapters**, shoppable videos, playlists, and more.

### Quick Example

Install the Video Player SDK:

```bash
npm install @imagekit/video-player
```

Create a fully-featured video player with just a few lines:

```html
<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://unpkg.com/@imagekit/video-player@latest/dist/styles.css" />
  <script src="https://unpkg.com/@imagekit/video-player@latest/dist/index.js"></script>
</head>
<body>
  <video id="my-player" class="video-js" controls></video>

  <script>
    const player = ImageKitVideoPlayer.videoPlayer('my-player', {
      imagekitId: 'YOUR_IMAGEKIT_ID',
      seekThumbnails: true, // Show previews on hover
      floatingWhenNotVisible: 'right' // Sticky player on scroll
    });

    player.src({
      src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
      
      // AI-powered features - no manual work required!
      chapters: true, // Auto-generate chapters from video content
      textTracks: [{
        autoGenerate: true, // AI speech-to-text transcription
        default: true,
        maxChars: 60,
        highlightWords: true, // Karaoke-like word highlighting
        translations: [
          { langCode: 'es', label: 'Spanish' },
          { langCode: 'fr', label: 'French' },
          { langCode: 'de', label: 'German' }
        ]
      }],
      
      transformation: [
        { width: 800, height: 600 },
        { quality: 80 }
      ]
    });
  </script>
</body>
</html>
```

{% callout style="info" %}
**AI-Powered Features:** The example above uses ImageKit's AI to automatically generate accurate subtitles in 50+ languages, create intelligent chapters, and enable word-level highlighting—all without manual transcription work.
{% /callout %}

[**Explore Video Player SDK →**](/video-player/overview)

## Supported Transformations

The SDK gives a name to each transformation parameter (e.g. `height` maps to `h`, `width` maps to `w`). If the property does not match any of the following supported options, it is added as is in the URL.

If you want to generate transformations without any modifications, use the `raw` parameter. For example, the SDK doesn't provide a nice way to write [conditional transformations](/conditional-transformations), so you can use the `raw` parameter to add them as is.

Check [transformation documentation](/transformations) for a complete reference on all transformations supported by ImageKit.

| Transformation Name        | URL Parameter                                                                                  |
| -------------------------- | ---------------------------------------------------------------------------------------------- |
| width                      | w                                                                                              |
| height                     | h                                                                                              |
| aspectRatio                | ar                                                                                             |
| quality                    | q                                                                                              |
| aiRemoveBackground         | e-bgremove (ImageKit powered)                                                                  |
| aiRemoveBackgroundExternal | e-removedotbg (Using third party)                                                              |
| aiEdit                     | e-edit                                                                                         |
| aiUpscale                  | e-upscale                                                                                      |
| aiRetouch                  | e-retouch                                                                                      |
| aiVariation                | e-genvar                                                                                       |
| aiDropShadow               | e-dropshadow                                                                                   |
| aiChangeBackground         | e-changebg                                                                                     |
| colorize                   | e-colorize                                                                                     |
| gradient                   | e-gradient                                                                                     |
| distort                    | e-distort                                                                                      |
| crop                       | c                                                                                              |
| cropMode                   | cm                                                                                             |
| x                          | x                                                                                              |
| y                          | y                                                                                              |
| xCenter                    | xc                                                                                             |
| yCenter                    | yc                                                                                             |
| focus                      | fo                                                                                             |
| format                     | f                                                                                              |
| radius                     | r                                                                                              |
| background                 | bg                                                                                             |
| border                     | b                                                                                              |
| rotation                   | rt                                                                                             |
| blur                       | bl                                                                                             |
| named                      | n                                                                                              |
| dpr                        | dpr                                                                                            |
| progressive                | pr                                                                                             |
| lossless                   | lo                                                                                             |
| trim                       | t                                                                                              |
| metadata                   | md                                                                                             |
| colorProfile               | cp                                                                                             |
| defaultImage               | di                                                                                             |
| original                   | orig                                                                                           |
| videoCodec                 | vc                                                                                             |
| audioCodec                 | ac                                                                                             |
| grayscale                  | e-grayscale                                                                                    |
| contrastStretch            | e-contrast                                                                                     |
| shadow                     | e-shadow                                                                                       |
| sharpen                    | e-sharpen                                                                                      |
| unsharpMask                | e-usm                                                                                          |
| gradient                   | e-gradient                                                                                     |
| flip                       | fl                                                                                             |
| opacity                    | o                                                                                              |
| zoom                       | z                                                                                              |
| page                       | pg                                                                                             |
| startOffset                | so                                                                                             |
| endOffset                  | eo                                                                                             |
| duration                   | du                                                                                             |
| streamingResolutions       | sr                                                                                             |
| colorReplace               | cr                                                                                             |
| overlay                    | Generates the correct layer syntax for image, video, text, subtitle, and solid color overlays. |
| raw                        | The string provided in raw will be added in the URL as is.                                     |


## Handling Unsupported Transformations

If you specify a transformation parameter that is not explicitly supported by the SDK, it is added “as-is” in the generated URL. This provides flexibility for using new or custom transformations without waiting for an SDK update.

For example:

```js
buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/photo.jpg",
  transformation: [
    { unsupportedTransformation: "value" }
  ]
});
// Output: https://ik.imagekit.io/your_imagekit_id/photo.jpg?tr=unsupportedTransformation-value
```

## Overlay Reference

This SDK provides `overlay` as a transformation parameter. The overlay can be a text, image, video, subtitle, or solid color.

Overlays in ImageKit are applied using layers, allowing you to stack multiple overlays on top of each other. Each overlay can be styled and positioned independently. For more details, refer to the [layer documentation](/transformations#overlay-using-layers).

The SDK automatically generates the correct layer syntax for image, video, text, subtitle, and solid color overlays. You can also specify the overlay position, size, and other properties.

The table below outlines the available overlay configuration options:

{% table %}

- Option {% width="30%" %}
- Description and Example {% width="70%" %}

---

- **type**  
  (Required)
- Specifies the type of overlay. Supported values: `text`, `image`, `video`, `subtitle`, `solidColor`. Example: `type: "text"`

---

- **text**  
  (Required for text overlays)
- The text content to display. Example: `text: "ImageKit"`

---

- **input**  
  (Required for image, video, or subtitle overlays)
- Relative path to the overlay asset. Example: `input: "logo.png"` or `input: "overlay-video.mp4"`

---

- **color**  
  (Required for solidColor overlays)
- RGB/RGBA hex code or color name for the overlay color. Example: `color: "FF0000"`

---

- **encoding**
- Accepted values: `auto`, `plain`, `base64`. [Check this](#encoding-options) for more details. Example: `encoding: "auto"`

---

- **transformation**
- An array of transformation objects to style the overlay independently of the base asset. Each overlay type has its own set of supported transformations.
  - For example, for text overlays, you can specify `fontSize`, `fontColor`, `background`, etc. Example: `transformation: [{ fontSize: 20, fontColor: "FF0000" }]`. Check out the [text overlay transformations](#text-overlay-transformations) section for more options.
  - For image overlays, you can specify `width`, `height`, `radius`, etc. Example: `transformation: [{ width: 100, height: 100 }]`. Check [reference](/add-overlays-on-images#list-of-supported-image-transformations-in-image-layers) for complete list of transformations supported on image overlays.
  - For video overlays, you can specify `width`, `height`, `rotation`, etc. Example: `transformation: [{ width: 100, height: 100 }]`. Check [reference](/add-overlays-on-videos#list-of-transformations-supported-on-image-overlay) for complete list of transformations supported on video overlays.
  - For subtitle overlays, you can specify `fontSize`, `fontColor`, `background`, etc. Example: `transformation: [{ fontSize: 20, fontColor: "FF0000" }]`. Check out the [subtitle overlay transformations](#subtitle-overlay-transformations) section for more options.
  - For solid color overlays, you can specify `width`, `height`, `radius`, etc. Example: `transformation: [{ width: 100, height: 100 }]`. Check out the [solid color overlay transformations](#solid-color-overlay-transformations) section for more options.


---

- **layerMode**
- Controls how the layer blends with the base image or underlying content. 
  - By default, layers completely cover the base image beneath them. Layer modes change this behavior. 
  - Supported values: `multiply`, `displace`, `cutout`, `cutter`, Check [reference](/add-overlays-on-images#layer-modes)

---

- **position**
- Sets the overlay’s position relative to the base asset. Accepts an object with `x`, `y`, or `focus`. Example: `position: { x: 10, y: 20 }` or `position: { focus: "center" }`

---

- **timing**
- (For video base) Specifies when the overlay appears using `start`, `duration`, and `end` (in seconds); if both `duration` and `end` are set, `duration` is ignored. Example: `timing: { start: 5, duration: 10 }`

{% /table %}

### Encoding Options

Overlay encoding options define how the overlay input is converted for URL construction. When set to `auto`, the SDK automatically determines whether to use plain text or Base64 encoding based on the input content.

For text overlays:
- If `auto` is used, the SDK checks the text overlay input: if it is URL-safe, it uses the format `i-{input}` (plain text); otherwise, it applies Base64 encoding with the format `ie-{base64_encoded_input}`.
- You can force a specific method by setting encoding to `plain` (always use `i-{input}`) or `base64` (always use `ie-{base64}`).
- Note: In all cases, the text is percent-encoded to ensure URL safety.

For image, video, and subtitle overlays:
- The input path is processed by removing any leading/trailing slashes and replacing inner slashes with `@@` when `plain` is used.
- Similarly, if `auto` is used, the SDK determines whether to apply plain text or Base64 encoding based on the characters present.
- For explicit behavior, use `plain` or `base64` to enforce the desired encoding.

Use `auto` for most cases to let the SDK optimize encoding, and use `plain` or `base64` when a specific encoding method is required.

### Solid Color Overlay Transformations

| Option     | Description                                                                                                                                                                                                                   | Example             |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| width      | Specifies the width of the solid color overlay block (in pixels or as an arithmetic expression).                                                                                                                              | `width: 100`        |
| height     | Specifies the height of the solid color overlay block (in pixels or as an arithmetic expression).                                                                                                                             | `height: 50`        |
| radius     | Specifies the corner radius of the solid color overlay block or shape. Can be a number or `"max"` for circular/oval shapes.                                                                                                   | `radius: "max"`     |
| alpha      | Specifies the transparency level of the solid color overlay. Supports integers from 1 (most transparent) to 9 (least transparent).                                                                                            | `alpha: 5`          |
| background | Specifies the background color of the solid color overlay. Accepts an RGB hex code, an RGBA code, or a standard color name.                                                                                                   | `background: "red"` |
| gradient   | Only works if base asset is an image. Creates a linear gradient with two colors. Pass `true` for a default gradient, or provide a string for a custom gradient. [Learn more](/effects-and-enhancements#gradient---e-gradient) | `gradient: true`    |

### Text Overlay Transformations

| Option         | Description                                                                                                                                                              | Example                    |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- |
| width          | Specifies the maximum width (in pixels) of the overlaid text. The text wraps automatically, and arithmetic expressions are supported (e.g., `bw_mul_0.2` or `bh_div_2`). | `width: 400`               |
| fontSize       | Specifies the font size of the overlaid text. Accepts a numeric value or an arithmetic expression.                                                                       | `fontSize: 50`             |
| fontFamily     | Specifies the font family of the overlaid text. Choose from the supported fonts or provide a custom font.                                                                | `fontFamily: "Arial"`      |
| fontColor      | Specifies the font color of the overlaid text. Accepts an RGB hex code, an RGBA code, or a standard color name.                                                          | `fontColor: "FF0000"`      |
| innerAlignment | Specifies the inner alignment of the text when it doesn’t occupy the full width. Supported values: `left`, `right`, `center`.                                            | `innerAlignment: "center"` |
| padding        | Specifies the padding around the text overlay. Can be a single integer or multiple values separated by underscores; arithmetic expressions are accepted.                 | `padding: 10`              |
| alpha          | Specifies the transparency level of the text overlay. Accepts an integer between `1` and `9`.                                                                            | `alpha: 5`                 |
| typography     | Specifies the typography style of the text. Supported values: `b` for bold, `i` for italics, and `b_i` for bold with italics.                                            | `typography: "b"`          |
| background     | Specifies the background color of the text overlay. Accepts an RGB hex code, an RGBA code, or a color name.                                                              | `background: "red"`        |
| radius         | Specifies the corner radius of the text overlay. Accepts a numeric value or `max` for circular/oval shape.                                                               | `radius: "max"`            |
| rotation       | Specifies the rotation angle of the text overlay. Accepts a numeric value for clockwise rotation or a string prefixed with `N` for counterclockwise rotation.            | `rotation: 90`             |
| flip           | Specifies the flip option for the text overlay. Supported values: `h`, `v`, `h_v`, `v_h`.                                                                                | `flip: "h"`                |
| lineHeight     | Specifies the line height for multi-line text. Accepts a numeric value or an arithmetic expression.                                                                      | `lineHeight: 20`           |

### Subtitle Overlay Transformations

| Option      | Description                                                                                               | Example                 |
| ----------- | --------------------------------------------------------------------------------------------------------- | ----------------------- |
| background  | Specifies the subtitle background color using a standard color name, RGB color code, or RGBA color code.  | `background: "blue"`    |
| fontSize    | Sets the font size of subtitle text.                                                                      | `fontSize: 16`          |
| fontFamily  | Sets the font family of subtitle text.                                                                    | `fontFamily: "Arial"`   |
| color       | Specifies the font color of subtitle text using standard color name, RGB, or RGBA color code.             | `color: "FF0000"`       |
| typography  | Sets the typography style of subtitle text. Supported values: `b`, `i`, `b_i`.                            | `typography: "b"`       |
| fontOutline | Specifies the font outline for subtitles. Requires an outline width and color separated by an underscore. | `fontOutline: "2_blue"` |
| fontShadow  | Specifies the font shadow for subtitles. Requires shadow color and indent separated by an underscore.     | `fontShadow: "blue_2"`  |


---

# Source: /integration/react

---
title: React ImageKit SDK
description: Real-time image & video resizing, automatic optimization, responsive images, and file uploading in React using ImageKit.io.
---

The React ImageKit SDK is a React-specific wrapper built on top of the ImageKit JavaScript SDK. It seamlessly integrates ImageKit’s URL generation, image and video optimization, responsive image handling, and file upload capabilities into React applications.

The SDK is lightweight and has first-class TypeScript support. You can view the [source code](https://github.com/imagekit-developer/imagekit-react) on Github.

## Installation and Setup

Install the React SDK via npm or yarn:

```bash
npm install @imagekit/react
# or
yarn add @imagekit/react
```

The SDK supports both server-side rendering (SSR) and client-side rendering (CSR), so it can be added to any React project—Create React App, Next.js, or any other framework. However, if you are building Next.js app, use our [Next.js SDK](/integration/nextjs).

This React SDK exports `Image` and `Video` components. These components automatically handle the URL generation logic for images and videos, respectively. They also support lazy loading, responsive images, and transformations.

```jsx
import { Image } from '@imagekit/react';

export default function Page() {
  return (
    <Image
      urlEndpoint="https://ik.imagekit.io/your_imagekit_id"
      src="/profile.png"
      width={500}
      height={500}
      alt="Picture of the author"
    />
  )
}
```

You can wrap `Image` and `Video` components inside the `ImageKitProvider` to set default values for `urlEndpoint` and `transformationPosition`. This allows you to avoid repeating these values in every component, making your code cleaner and more maintainable.

```jsx
import { Image, ImageKitProvider } from '@imagekit/react';

export default function Page() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Image
        src="/profile.png"
        width={500}
        height={500}
        alt="Picture of the author"
      />
    </ImageKitProvider>
  )
}
```

Besides `Image` and `Video`, the SDK also provides utility functions and error classes that can be used independently of the components.

#### Utility functions
- [`buildSrc`](/integration/javascript#buildsrc-parameters) – Generates URLs for images and videos based on your URL endpoint and transformation parameters.
- [`buildTransformationString`](/integration/javascript#buildtransformationstring-parameters) – Converts array of transformation objects into a URL query string.
- [`upload`](/integration/javascript#upload-parameters) – Facilitates file uploads to ImageKit with built-in support for common error handling, progress tracking, and abort functionality.
- [`getResponsiveImageAttributes`](/integration/javascript#getresponsiveimageattributes-parameters) – Generates responsive image attributes that can be used on raw HTML image elements. This SDK however handles this automatically for you when using the `Image` component.

Refer to linked documentation for detailed usage of these utility functions.

#### Error classes for upload error handling
- `ImageKitInvalidRequestError` - For invalid requests.
- `ImageKitAbortError` - For aborted uploads.
- `ImageKitUploadNetworkError` - For network errors during upload.
- `ImageKitServerError` - For server-side errors.

#### React Specific Components
- [`Image`](#image-component) – It is a wrapper around the HTML `img` tag, extending its functionality to support ImageKit-specific features.
- [`Video`](#video-component) – A lightweight wrapper for the HTML video element that automatically generates URLs for video assets with ImageKit transformations.
- `ImageKitProvider` & `ImageKitContext` – Components that let you configure default settings (such as `urlEndpoint` and `transformationPosition`) for all nested Image and Video components.

#### Type definitions
The SDK provides TypeScript definitions for all components and utility functions, ensuring type safety and autocompletion in your IDE. Exported types include `ImageKitProviderProps`, `IKImageProps`, `IKVideoProps`, `SrcOptions`, `UploadOptions`, `UploadResponse`, `Transformation`, `GetImageAttributesOptions`, and `ResponsiveImageAttributes`.

## Image Component

The `Image` component is a wrapper around the HTML `img` element. It allows you to use ImageKit’s URL generation and transformation, lazy-loading, responsive images etc.
 
It supports all [HTML img attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/img#attributes) and additionally accepts the following ImageKit-specific props:

{% table %}

- Parameter {% width="30%" %}
- Description and Example {% width="70%" %}

---

- **urlEndpoint**  
- The base URL endpoint from your [ImageKit dashboard](https://imagekit.io/dashboard/url-endpoints).
  To avoid passing this prop in every component, you can wrap your components in an `ImageKitProvider` and set the `urlEndpoint` there. In case you pass it in the component, it will override the value set in the provider.
  
  Example: `https://ik.imagekit.io/your_imagekit_id`.

---

- **src**  
  (Required)  
- A relative or absolute path to the image.

  - If a **relative path** is provided, it is appended to the `urlEndpoint`.
  - If an **absolute path** is provided, it is used as-is and the `urlEndpoint` is ignored.
  - **Do not include query parameters** directly in the `src`. Use the `queryParameters` prop instead.
  - **When using a web proxy**, you can pass the full image URL and prepend it with a `/`. For example - `/https://example.com/image.jpg`.

  **Examples:**  
  Relative - `/default-image.jpg`  
  Absolute - `https://example.com/image.jpg`  
  Web Proxy - `/https://example.com/image.jpg`

---

- **width**
- The width of the image in pixels (in numbers). This is used to calculate the srcSet attribute and is only utilized when sizes is not provided. The prop is set on the `<img>` element as it is. If provided value is not a number, then `srcset` is generated using the full list of device breakpoints
  
  Example: `width="300"`

---

- **transformation**
- An array of transformation objects. Each object can include properties like `width`, `height`, `rotation`, overlays, and advanced effects.  
  
  Example: `[ { width: 300, height: 300 } ]`  
  
  See all [supported transformation](#supported-transformations) options and how to [handle unsupported transformations](#handling-unsupported-transformations).

---

- **queryParameters**
- An object with additional query parameters to append to the URL.  
  Example: `{ v: 2 }`

---

- **responsive**
- A boolean that determines if responsive image functionality is enabled. By default, this is `true`, meaning that a `srcset` attribute is automatically generated for responsive images. Set it to `false` to disable this behavior and only apply explicitly defined transformations.

---

- **deviceBreakpoints**  
  (number[])
- It allows you to specify a list of device width breakpoints.

  Defaults to `[640, 750, 828, 1080, 1200, 1920, 2048, 3840]`.

---

- **imageBreakpoints**  
  (number[])
- It allows you to specify a list of image width breakpoints. It is concatenated with `deviceBreakpoints` before calculating `srcSet`. 
  
  Defaults to `[16, 32, 48, 64, 96, 128, 256, 384]`.

---

- **transformationPosition**
- Specifies whether the transformation string is included in the URL path or as a query parameter. Defaults to `"query"`.  
  Example: `"query"` or `"path"`

{% /table %}

## Video Component

The `Video` component is a lightweight wrapper around the HTML `video` element. It allows you to use ImageKit’s URL generation and transformation capabilities. It supports all [HTML video attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video#attributes) and additionally accepts the following ImageKit-specific props - `urlEndpoint`, `transformation`, `transformationPosition`, and `queryParameters`. For the definition of these props, refer to the [Image component](#image-component) section.

```js
import { Video } from '@imagekit/react';
export default function Page() {
  return (
    <Video
      urlEndpoint="https://ik.imagekit.io/your_imagekit_id"
      src="/video.mp4"
      controls
      width={500}
      height={500}
    />
  )
}
```

## Height and Width Transformations

With ImageKit, you can resize images on the fly using the `width` and `height` properties. The SDK automatically generates the appropriate URL with the specified dimensions.

```jsx
import { Image } from '@imagekit/react';

export default function Page() {
  return (
    <Image
      urlEndpoint="https://ik.imagekit.io/your_imagekit_id"
      src="/profile.png"
      width={500}
      height={500}
      alt="Picture of the author"
      transformation={[{ width: 500, height: 500 }]}
    />
  )
}
```

## Responsive Images

The `Image` component includes built-in support for **responsive images**, enabled by default. It automatically generates appropriate `srcSet` attributes based on device and image breakpoints, ensuring optimal image delivery across screen sizes.

Under the hood, it leverages the [`getResponsiveImageAttributes`](/integration/javascript#getresponsiveimageattributes-parameters) utility from the core JavaScript SDK to generate these attributes.

If you want to turn off responsive images, you can set `responsive` to `false`. This will disable the automatic generation of `srcset` attributes.

{% callout style="info" %}
**Note:** If you have enabled the "Restrict unnamed transformations" setting (see [Basic Security](/media-delivery-basic-security#restrict-unnamed-transformations)), hardcoded width/crop transformations may be added by default causing request failures. Setting `responsive` to `false` prevents these additional transformations from being applied.
{% /callout %}

## Lazy Loading Images

The `Image` component supports lazy loading by default. You can control this behavior using the [`loading`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/img#loading) prop.

By default, `loading` is set to `lazy`, which defers loading the image until it is near the viewport.

If set to `eager`, the image loads immediately.

```jsx
import { Image } from '@imagekit/react';
export default function Page() {
  return (
    <Image
      urlEndpoint="https://ik.imagekit.io/your_imagekit_id"
      src="/profile.png"
      width={500}
      height={500}
      alt="Picture of the author"
      loading="lazy" // Use "eager" to load immediately. `lazy` is the default value
    />
  )
}
```

## Lazy Loading with Placeholder

To display a placeholder while an image is loading, you can generate a placeholder image URL using ImageKit’s [`buildSrc`](/integration/javascript#buildsrc-parameters) utility function and apply it as a background image using the `style` prop. Once the actual image is mounted, you can hide the placeholder by checking the [`complete`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/complete) property of the image element.

{% callout style="info" %}
**Good to know**  
We avoid using the `onLoad` event to hide the placeholder because it may not always fire or attach reliably. For instance, if the image is cached or loads before the JavaScript bundle is fully loaded and executed, the `onLoad` event might be skipped entirely.
{% /callout %}

```jsx
import { Image, buildSrc } from "@imagekit/react";
import { useState, useRef, useCallback } from "react";
export default function Page() {
  const [showPlaceholder, setShowPlaceholder] = useState(true);

  const hidePlaceholder = () => setShowPlaceholder(false);

  const imgRef = useCallback((img) => {
    if (!img) return; // unmount

    if (img.complete) {
      hidePlaceholder();
      return;
    }
  }, []);

  return (
    <Image
      src="/default-image.jpg"
      alt="React logo"
      width={400}
      height={400}
      loading="eager" // To ensure the image starts loading immediately
      ref={imgRef}
      style={showPlaceholder ? {
        backgroundImage: `url(${buildSrc({
          urlEndpoint: "https://ik.imagekit.io/ikmedia",
          src: "/default-image.jpg",
          transformation: [
            // {}, // Any other transformation you want to apply to the placeholder image
            {
              quality: 10,
              blur: 90,
            }
          ]
        })})`,
        backgroundSize: "cover",
        backgroundRepeat: "no-repeat",
      } : {}}
    />
  )
}
```

## Lazy Loading Videos
To lazy load a video using `Video` component, you can set the `preload` attribute to `none` and specify a `poster` image by extracting a thumbnail from the video.

The [`buildSrc`](/integration/javascript#buildsrc-parameters) utility function is used to generate the thumbnail URL. It accepts the same parameters as the `Video`/`Image` component and returns a URL with the specified transformations.

Refer to the [create thumbnail](/create-video-thumbnails) documentation for detailed instructions on generating a thumbnail from a video using ImageKit.

```jsx
import { Video, buildSrc } from '@imagekit/react';
export default function Page() {
  return (
    <Video
      urlEndpoint="https://ik.imagekit.io/your_imagekit_id"
      src="/video.mp4"
      controls
      preload="none"
      poster={buildSrc({
        urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
        src: `/video.mp4/ik-thumbnail.jpg`, // Append ik-thumbnail.jpg after the video URL
      })}
    />
  )
}
```

## Chained Transformations

You can chain multiple transformations together by passing an array of transformation objects. Each object can specify different properties, such as width, height, cropping, overlays, and effects. See [chained transformations](/transformations#chained-transformations) for more details.

```jsx
import { Image } from '@imagekit/react';
export default function Page() {
  return (
    <Image
      urlEndpoint="https://ik.imagekit.io/your_imagekit_id"
      src="/profile.png"
      width={500}
      height={500}
      alt="Picture of the author"
      transformation={[
        { width: 400, height: 300 },
        { rotation: 90 }
      ]}
    />
  )
}
```

## Adding Overlays

You can add overlays to images and videos. The overlay can be a text, image, video, or subtitle.

Besides the overlay type, you can also specify the position, size, and other properties of the overlay. Check the [overlay options](#overlay-reference) for more details.

### Image Overlay

```jsx
import { Image, ImageKitProvider } from '@imagekit/react';

export default function ImageOverlayExample() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Image
        src="/background.jpg"
        alt="Background with image overlay"
        width={600}
        height={400}
        transformation={[
          { overlay: { type: "image", input: "logo.png" } }
        ]}
      />
    </ImageKitProvider>
  );
}
```

You can independently transform the overlay image by passing a transformation array inside the `overlay` object. The transformation will be applied to the overlay image only.

```jsx
import { Image, ImageKitProvider } from '@imagekit/react';

export default function ImageOverlayExample() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Image
        src="/background.jpg"
        alt="Background with image overlay"
        width={600}
        height={400}
        transformation={[
          { 
            overlay: { 
              type: "image",
              input: "logo.png",
              transformation: [{ width: 100, height: 100 }] // Transformations for the overlay image and not the background image
            } 
          }
        ]}
      />
    </ImageKitProvider>
  );
}
```

Image overlays support a wide range of transformations. Check [reference](/add-overlays-on-images#list-of-supported-image-transformations-in-image-layers) for the complete list of transformations supported on image overlays.

### Solid Color Overlay

You can add a solid color overlay to images and videos.

```jsx
import { Image, ImageKitProvider } from '@imagekit/react';

export default function ColorOverlayExample() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Image
        src="/background.jpg"
        alt="Background with solid color overlay"
        width={600}
        height={400}
        transformation={[
          { 
            overlay: { 
              type: "solidColor",
              color: "FF0000" 
            } 
          }
        ]}
      />
    </ImageKitProvider>
  );
}
```

You can also specify the width, height, and other properties of the solid color overlay. For example:

```jsx
import { Image, ImageKitProvider } from '@imagekit/react';
export default function ColorOverlayExample() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Image
        src="/background.jpg"
        alt="Background with 100x100 solid color overlay"
        width={600}
        height={400}
        transformation={[
          { 
            overlay: { 
              type: "solidColor",
              color: "FF0000",
              transformation: [
                { width: 100, height: 100 }
              ]
            } 
          }
        ]}
      />
    </ImageKitProvider>
  );
}
```

For more options related to styling the solid color overlay, check the [solid color overlay transformations](#solid-color-overlay-transformations) section.

### Text Overlay

You can add text overlays to images and videos.

```jsx
import { Image, ImageKitProvider } from '@imagekit/react';
export default function TextOverlayExample() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Image
        src="/background.jpg"
        alt="Background with text overlay"
        width={600}
        height={400}
        transformation={[
          { 
            overlay: { 
              type: "text", 
              text: "Hello, ImageKit!" 
            } 
          }
        ]}
      />
    </ImageKitProvider>
  );
}
```

You can also specify the font size, color, and other properties of the text overlay. For example:

```jsx
import { Image, ImageKitProvider } from '@imagekit/react';

export default function TextOverlayExample() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Image
        src="/background.jpg"
        alt="Background with text overlay"
        width={600}
        height={400}
        transformation={[
          { 
            overlay: { 
              type: "text", 
              text: "Hello, ImageKit!", 
              transformation: [
                { fontSize: 20, fontColor: "FF0000" } // Specify font size and color of the text
              ] 
            } 
          }
        ]}
      />
    </ImageKitProvider>
  );
}
```

Check the [text overlay transformations](#text-overlay-transformations) section for more options related to styling the text.

### Video Overlay

You can add video overlays on videos only.

```jsx
import { Video, ImageKitProvider } from '@imagekit/react';

export default function VideoOverlayExample() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Video
        src="/background.mp4"
        controls
        transformation={[
          { 
            overlay: { 
              type: "video", 
              input: "overlay.mp4" 
            } 
          }
        ]}
      />
    </ImageKitProvider>
  );
}
```

Additionally, you can specify the start and duration for the overlay video. For example:

```jsx
import { Video, ImageKitProvider } from '@imagekit/react';
export default function VideoOverlayExample() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Video
        src="/background.mp4"
        controls
        transformation={[
          { 
            overlay: { 
              type: "video", 
              input: "overlay.mp4",
              timing: { start: 5, duration: 10 } // Overlay appears at 5 seconds and lasts for 10 seconds
            } 
          }
        ]}
      />
    </ImageKitProvider>
  );
}
```

You can also independently transform the overlay video. For example, to resize the overlay video:

```jsx
import { Video, ImageKitProvider } from '@imagekit/react';
export default function VideoOverlayExample() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Video
        src="/background.mp4"
        controls
        transformation={[
          { 
            overlay: { 
              type: "video", 
              input: "overlay.mp4",
              transformation: [
                { width: 100, height: 100 } // Transformations for the overlay video and not the background video
              ] 
            } 
          }
        ]}
      />
    </ImageKitProvider>
  );
}
```

All supported [video transformations](/video-transformation) can also be applied to overlay videos.

If you're overlaying an image on a base video, refer to [this list](/add-overlays-on-videos#list-of-transformations-supported-on-image-overlay) for all the transformations supported on image overlays.

### Subtitle Overlay

You can add subtitle overlays on videos.

```jsx
import { Video, ImageKitProvider } from '@imagekit/react';

export default function SubtitleOverlayExample() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Video
        src="/background.mp4"
        controls
        transformation={[
          { 
            overlay: { 
              type: "subtitle", 
              input: "subtitle.srt" 
            } 
          }
        ]}
      />
    </ImageKitProvider>
  );
}
```

The subtitle overlay can be styled with various properties such as font size, color, and outline. See the [Subtitle Overlay Transformations](#subtitle-overlay-transformations) section for all styling options.

## Background Removal Using AI

```jsx
import { Image, ImageKitProvider } from '@imagekit/react';

export default function BackgroundRemovalExample() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Image
        src="/photo.jpg"
        alt="Photo with background removal"
        width={500}
        height={500}
        transformation={[
          { aiRemoveBackground: true }
        ]}
      />
    </ImageKitProvider>
  );
}
```

ImageKit supports multiple AI-powered transformations, like upscaling, generative fill, and more. More examples:

```jsx
import { Image, ImageKitProvider } from '@imagekit/react';
export default function AIDropShadow() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Image
        src="/photo.jpg"
        alt="Photo with AI drop shadow"
        width={500}
        height={500}
        transformation={[
          { aiDropShadow: true }
        ]}
      />
    </ImageKitProvider>
  );
}
```

Upscaling example:

```jsx
import { Image, ImageKitProvider } from '@imagekit/react';
export default function AIUpscaleExample() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Image
        src="/photo.jpg"
        alt="Photo with AI upscaling"
        width={500}
        height={500}
        transformation={[
          { aiUpscale: true }
        ]}
      />
    </ImageKitProvider>
  );
}
```

## Arithmetic Expressions

You can use arithmetic expressions to dynamically compute transformation values. For example, to set the width to half of the original image width:

```jsx
import { Image, ImageKitProvider } from '@imagekit/react';

export default function ArithmeticExample() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Image
        src="/photo.jpg"
        alt="Photo with arithmetic width"
        width={300}
        height={200}
        transformation={[
          { width: "iw_div_2" }
        ]}
      />
    </ImageKitProvider>
  );
}
```

Check out the [Arithmetic Expressions](/arithmetic-expressions-in-transformations) reference for more examples and details.

## Uploading Files

The React SDK exports a utility function, `.upload`, which enables you to upload files to ImageKit. This `upload()` function leverages the [Upload V1 API](/api-reference/upload-file/upload-file), accepting an options object and returning a promise that resolves with the upload response.

The SDK automatically converts certain parameters into JSON strings, as required by the API. If a parameter is not explicitly supported by the SDK, it is included in the request as-is. For a complete list of parameters and expected formats, refer to the API documentation.

### upload() Parameters

The `upload()` function accepts a JSON object with the following parameters:

{% table %}

- Option {% width="30%" %}
- Description and Example {% width="70%" %}

---

- **file**  
  (Required)  
- The file content to be uploaded. Accepts binary data, a base64-encoded string, or a URL. Typically used with a File or Blob in the browser. Example: `file: fileInput.files[0]`

---

- **fileName**  
  (Required)  
- The name to assign to the uploaded file. Supports alphanumeric characters, dot, underscore, and dash. Any other character is replaced with `_`. Example: `fileName: "myImage.jpg"`

---

- **signature**  
  (Required)  
- The HMAC-SHA1 digest of the concatenation of "token + expire". The signing key is your ImageKit private API key. Must be computed on the server side. Example: `signature: "generated_signature"`

---

- **token**  
  (Required)  
- A unique value to identify and prevent replays. Typically a UUID (e.g., version 4). Example: `token: "unique_upload_token"`
  
  Check the [signature generation](#generating-authentication-parameters) section for more details on how to generate this value.

---

- **expire**  
  (Required)  
- A Unix timestamp in seconds, less than 1 hour in the future. Example: `expire: 1616161616`
  
  Check the [signature generation](#generating-authentication-parameters) section for more details on how to generate this value.

---

- **publicKey**  
  (Required)
- The public API key for your ImageKit account. This is used to identify the account making the upload request. Example: `publicKey: "your_public_api_key"`
  
  Check the [signature generation](#generating-authentication-parameters) section for more details on how to generate this value.

---

- **onProgress**
- A callback function to track the upload progress. It receives an event object with `loaded` and `total` properties. Example: `onProgress: (event) => console.log(event.loaded, event.total)`
  This is useful for showing upload progress to the user.

---
- **abortSignal**
- An optional `AbortSignal` object to abort the upload request. If the signal is already aborted, the upload will fail immediately.
  You can create an `AbortController` instance and pass its signal to the `upload()` function.

---

- **useUniqueFileName**
- Boolean flag to automatically generate a unique filename if set to true. Defaults to true. If false, the image is uploaded with the provided filename, replacing any existing file with the same name. Example: `useUniqueFileName: true`

---

- **folder**
- The folder path where the file will be stored, e.g., "/images/folder/". If the path doesn't exist, it is created on-the-fly. Example: `folder: "/images/uploads"`

---

- **isPrivateFile**
- Boolean to mark the file as private, restricting access to the original file URL. A private file requires signed URLs or named transformations for access. Defaults to false. Example: `isPrivateFile: false`

---

- **tags**
- Optionally set tags on the uploaded file. Can be a comma-separated string or an array of tags. Example: `tags: "summer,holiday"` or `tags: ["summer","holiday"]`

---

- **customCoordinates**
- A string in "x,y,width,height" format that defines the region of interest in an image (top-left coords and area size). Example: `customCoordinates: "10,10,100,100"`

---

- **responseFields**
- A comma-separated or array-based set of fields to return in the upload response. Example: `responseFields: "tags,customCoordinates"`

---

- **extensions**
- An array of extension objects to apply to the image, e.g., background removal, auto-tagging, etc. Example: `extensions: [{ name: "auto-tagging" }]`

---

- **webhookUrl**
- A webhook URL to receive the final status of any pending extensions once they've completed processing. Example: `webhookUrl: "https://example.com/webhook"`

---

- **overwriteFile**
- Defaults to true. If false, and "useUniqueFileName" is also false, the API immediately fails if a file with the same name/folder already exists. Example: `overwriteFile: true`

---

- **overwriteAITags**
- Defaults to true. If true, and an existing file is found at the same location, its AITags are removed. Set to false to keep existing AITags. Example: `overwriteAITags: true`

---

- **overwriteTags**
- Defaults to true. If no tags are specified in the request, existing tags are removed from overwritten files. Setting to false has no effect if the request includes tags. Example: `overwriteTags: true`

---

- **overwriteCustomMetadata**
- Defaults to true. If no customMetadata is specified in the request, existing customMetadata is removed from overwritten files. Setting to false has no effect if the request specifies customMetadata. Example: `overwriteCustomMetadata: true`

---

- **customMetadata**
- A stringified JSON or an object containing custom metadata fields to store with the file. Custom metadata fields must be pre-defined in your ImageKit configuration. Example: `customMetadata: {author: "John Doe"}`

---

- **transformation**
- Defines pre and post transformations to be applied to the file during upload. The SDK enforces certain validation rules for pre/post transformations. Example: `transformation: { pre: "w-200,h-200", post: [...] }`

---

- **xhr**
- An optional XMLHttpRequest instance for the upload. The SDK merges it with its own logic to handle progress events, etc. Example: `xhr: new XMLHttpRequest()`

---

- **checks**
- A string specifying the checks to be performed server-side before uploading to the media library, e.g., size or mime type checks. Example: `checks: "file.size' < '1MB'"`

{% /table %}


## Upload Example and Error Handling

The `.upload` function expects the following mandatory parameters:

- **`file` and `fileName`** – The file to be uploaded and the name you want to assign to it. The `file` value can be a `File` object, a base64-encoded string, or a URL.
- **Authentication parameters** – `token`, `signature`, `expire`, and `publicKey`.

Authentication is essential for secure file uploads from the browser. You should **never expose your private API key** in client-side code. Instead, generate these one-time authentication parameters on the **server side** and pass them to the client.

To simplify the process, all of our [backend SDKs](/quick-start-guides#back-end) include utility functions for generating authentication parameters.

### Upload Flow Overview

Here’s how the upload process using the SDK works:

1. **Client Request for Auth Parameters**  
   The client component calls an API route to fetch the authentication parameters.  
   You can implement your own application logic within this route to authenticate the user.  
   After that, use one of our backend SDKs to generate the required auth parameters and return them to the client.

2. **File Upload**  
   Once the client has the auth parameters, it can call the `.upload` function with the necessary data.

### Generating Authentication Parameters

The following example demonstrates how to create an API route that generates authentication parameters using the ImageKit [backend SDKs](/quick-start-guides#back-end).

You can find your [private key](/api-keys#private-key) and [public key](/api-keys#public-key) in the ImageKit dashboard.

{% tabs %}
{% tab title="Node.js" %}
```js
const express = require('express');
const ImageKit = require('@imagekit/nodejs'); // Node.js SDK
const app = express();

const client = new ImageKit({
  privateKey: process.env.IMAGEKIT_PRIVATE_KEY
});

// allow cross-origin requests
app.use(function(req, res, next) {
  res.header("Access-Control-Allow-Origin", "*");
  res.header("Access-Control-Allow-Headers", 
    "Origin, X-Requested-With, Content-Type, Accept");
  next();
});

app.get('/auth', function (req, res) {
  // Your application logic to authenticate the user
  // For example, you can check if the user is logged in or has the necessary permissions
  // If the user is not authenticated, you can return an error response
  const { token, expire, signature } = client.helper.getAuthenticationParameters();
  res.send({ token, expire, signature, publicKey: process.env.IMAGEKIT_PUBLIC_KEY });
});

app.listen(3000, function () {
  console.log('Live at Port 3000');
});
```
{% /tab %}

{% tab title="Go" %}
```go
package main

import (
	"encoding/json"
	"log"
	"net/http"
	"os"

	"github.com/imagekit-developer/imagekit-go/v2"
	"github.com/imagekit-developer/imagekit-go/v2/option"
)

func main() {
	client := imagekit.NewClient(
		option.WithPrivateKey(os.Getenv("IMAGEKIT_PRIVATE_KEY")),
	)

	http.HandleFunc("/auth", func(w http.ResponseWriter, r *http.Request) {
		// Enable CORS
		w.Header().Set("Access-Control-Allow-Origin", "*")
		w.Header().Set("Access-Control-Allow-Headers", "Origin, X-Requested-With, Content-Type, Accept")

		// Your application logic to authenticate the user
		// For example, you can check if the user is logged in or has the necessary permissions
		// If the user is not authenticated, you can return an error response

		authParams := client.Helper.GetAuthenticationParameters("", 0)
		
		response := map[string]interface{}{
			"token":     authParams["token"],
			"expire":    authParams["expire"],
			"signature": authParams["signature"],
			"publicKey": os.Getenv("IMAGEKIT_PUBLIC_KEY"),
		}

		w.Header().Set("Content-Type", "application/json")
		json.NewEncoder(w).Encode(response)
	})

	log.Println("Live at Port 3000")
	log.Fatal(http.ListenAndServe(":3000", nil))
}
```
{% /tab %}

{% tab title="Python" %}
```python
import os
from flask import Flask, jsonify
from imagekitio import ImageKit

app = Flask(__name__)

imagekit = ImageKit(
    private_key=os.environ.get("IMAGEKIT_PRIVATE_KEY")
)

# Enable CORS
@app.after_request
def after_request(response):
    response.headers.add('Access-Control-Allow-Origin', '*')
    response.headers.add('Access-Control-Allow-Headers', 'Origin, X-Requested-With, Content-Type, Accept')
    return response

@app.route('/auth')
def get_auth():
    # Your application logic to authenticate the user
    # For example, you can check if the user is logged in or has the necessary permissions
    # If the user is not authenticated, you can return an error response
    
    auth_params = imagekit.helper.get_authentication_parameters()
    
    return jsonify({
        'token': auth_params['token'],
        'expire': auth_params['expire'],
        'signature': auth_params['signature'],
        'publicKey': os.environ.get('IMAGEKIT_PUBLIC_KEY')
    })

if __name__ == '__main__':
    app.run(port=3000)
```
{% /tab %}

{% tab title="Ruby" %}
```ruby
require 'sinatra'
require 'imagekitio'
require 'json'

# Enable CORS
before do
  headers['Access-Control-Allow-Origin'] = '*'
  headers['Access-Control-Allow-Headers'] = 'Origin, X-Requested-With, Content-Type, Accept'
end

client = Imagekitio::Client.new(private_key: ENV['IMAGEKIT_PRIVATE_KEY'])

get '/auth' do
  content_type :json
  
  # Your application logic to authenticate the user
  # For example, you can check if the user is logged in or has the necessary permissions
  # If the user is not authenticated, you can return an error response
  
  auth_params = client.helper.get_authentication_parameters
  
  {
    token: auth_params[:token],
    expire: auth_params[:expire],
    signature: auth_params[:signature],
    publicKey: ENV['IMAGEKIT_PUBLIC_KEY']
  }.to_json
end

# Start the server
set :port, 3000
```
{% /tab %}

{% tab title="Java" %}
```java
import io.imagekit.client.ImageKitClient;
import io.imagekit.client.okhttp.ImageKitOkHttpClient;
import spark.Spark;
import com.google.gson.Gson;
import java.util.Map;
import java.util.HashMap;

// Using Spark framework (http://sparkjava.com)
public class AuthServer {
    public static void main(String[] args) {
        ImageKitClient client = ImageKitOkHttpClient.builder()
            .privateKey(System.getenv("IMAGEKIT_PRIVATE_KEY"))
            .build();

        Gson gson = new Gson();

        // Enable CORS
        Spark.before((request, response) -> {
            response.header("Access-Control-Allow-Origin", "*");
            response.header("Access-Control-Allow-Headers", "Origin, X-Requested-With, Content-Type, Accept");
        });

        Spark.get("/auth", (request, response) -> {
            // Your application logic to authenticate the user
            // For example, you can check if the user is logged in or has the necessary permissions
            // If the user is not authenticated, you can return an error response

            Map<String, Object> authParams = client.helper().getAuthenticationParameters(null, null);
            
            Map<String, Object> responseData = new HashMap<>();
            responseData.put("token", authParams.get("token"));
            responseData.put("expire", authParams.get("expire"));
            responseData.put("signature", authParams.get("signature"));
            responseData.put("publicKey", System.getenv("IMAGEKIT_PUBLIC_KEY"));

            response.type("application/json");
            return gson.toJson(responseData);
        });

        Spark.port(3000);
        System.out.println("Live at Port 3000");
    }
}
```
{% /tab %}

{% tab title=".Net" %}
```csharp
using Imagekit;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

ImageKitClient client = new() { PrivateKey = Environment.GetEnvironmentVariable("IMAGEKIT_PRIVATE_KEY") };

app.Use(async (context, next) =>
{
    context.Response.Headers["Access-Control-Allow-Origin"] = "*";
    context.Response.Headers["Access-Control-Allow-Headers"] = "Origin, X-Requested-With, Content-Type, Accept";
    await next();
});

app.MapGet("/auth", () =>
{
    // Your application logic to authenticate the user
    var authParams = client.Helper.GetAuthenticationParameters();
    return new
    {
        token = authParams.Token,
        expire = authParams.Expire,
        signature = authParams.Signature,
        publicKey = Environment.GetEnvironmentVariable("IMAGEKIT_PUBLIC_KEY"),
    };
});

Console.WriteLine("Live at Port 3000");
app.Run("http://localhost:3000");
```
{% /tab %}
{% /tabs %}

Now your client-side code can call this API route to retrieve the upload parameters.

The example below demonstrates how to use the `.upload` function in a client component to upload a file, including error handling for various upload scenarios. You can copy and paste this code into your client component and customize it as needed.

```js
import {
    ImageKitAbortError,
    ImageKitInvalidRequestError,
    ImageKitServerError,
    ImageKitUploadNetworkError,
    upload,
} from "@imagekit/react";
import { useRef, useState } from "react";

// UploadExample component demonstrates file uploading using ImageKit's React SDK.
const UploadExample = () => {
    // State to keep track of the current upload progress (percentage)
    const [progress, setProgress] = useState(0);

    // Create a ref for the file input element to access its files easily
    const fileInputRef = useRef<HTMLInputElement>(null);

    // Create an AbortController instance to provide an option to cancel the upload if needed.
    const abortController = new AbortController();

    /**
     * Authenticates and retrieves the necessary upload credentials from the server.
     *
     * This function calls the authentication API endpoint to receive upload parameters like signature,
     * expire time, token, and publicKey.
     *
     * @returns {Promise<{signature: string, expire: string, token: string, publicKey: string}>} The authentication parameters.
     * @throws {Error} Throws an error if the authentication request fails.
     */
    const authenticator = async () => {
        try {
            // Perform the request to the upload authentication endpoint.
            const response = await fetch("/auth");
            if (!response.ok) {
                // If the server response is not successful, extract the error text for debugging.
                const errorText = await response.text();
                throw new Error(`Request failed with status ${response.status}: ${errorText}`);
            }

            // Parse and destructure the response JSON for upload credentials.
            const data = await response.json();
            const { signature, expire, token, publicKey } = data;
            return { signature, expire, token, publicKey };
        } catch (error) {
            // Log the original error for debugging before rethrowing a new error.
            console.error("Authentication error:", error);
            throw new Error("Authentication request failed");
        }
    };

    /**
     * Handles the file upload process.
     *
     * This function:
     * - Validates file selection.
     * - Retrieves upload authentication credentials.
     * - Initiates the file upload via the ImageKit SDK.
     * - Updates the upload progress.
     * - Catches and processes errors accordingly.
     */
    const handleUpload = async () => {
        // Access the file input element using the ref
        const fileInput = fileInputRef.current;
        if (!fileInput || !fileInput.files || fileInput.files.length === 0) {
            alert("Please select a file to upload");
            return;
        }

        // Extract the first file from the file input
        const file = fileInput.files[0];

        // Retrieve authentication parameters for the upload.
        let authParams;
        try {
            authParams = await authenticator();
        } catch (authError) {
            console.error("Failed to authenticate for upload:", authError);
            return;
        }
        const { signature, expire, token, publicKey } = authParams;

        // Call the ImageKit SDK upload function with the required parameters and callbacks.
        try {
            const uploadResponse = await upload({
                // Authentication parameters
                expire,
                token,
                signature,
                publicKey,
                file,
                fileName: file.name, // Optionally set a custom file name
                // Progress callback to update upload progress state
                onProgress: (event) => {
                    setProgress((event.loaded / event.total) * 100);
                },
                // Abort signal to allow cancellation of the upload if needed.
                abortSignal: abortController.signal,
            });
            console.log("Upload response:", uploadResponse);
        } catch (error) {
            // Handle specific error types provided by the ImageKit SDK.
            if (error instanceof ImageKitAbortError) {
                console.error("Upload aborted:", error.reason);
            } else if (error instanceof ImageKitInvalidRequestError) {
                console.error("Invalid request:", error.message);
            } else if (error instanceof ImageKitUploadNetworkError) {
                console.error("Network error:", error.message);
            } else if (error instanceof ImageKitServerError) {
                console.error("Server error:", error.message);
            } else {
                // Handle any other errors that may occur.
                console.error("Upload error:", error);
            }
        }
    };

    return (
        <>
            {/* File input element using React ref */}
            <input type="file" ref={fileInputRef} />
            {/* Button to trigger the upload process */}
            <button type="button" onClick={handleUpload}>
                Upload file
            </button>
            <br />
            {/* Display the current upload progress */}
            Upload progress: <progress value={progress} max={100}></progress>
        </>
    );
};

export default UploadExample;
```

## Supported Transformations

The SDK gives a name to each transformation parameter (e.g. `height` maps to `h`, `width` maps to `w`). If the property does not match any of the following supported options, it is added as is in the URL.

If you want to generate transformations without any modifications, use the `raw` parameter. For example, the SDK doesn't provide a nice way to write [conditional transformations](/conditional-transformations), so you can use the `raw` parameter to add them as is.

Check [transformation documentation](/transformations) for a complete reference on all transformations supported by ImageKit.

| Transformation Name        | URL Parameter                                                                                  |
| -------------------------- | ---------------------------------------------------------------------------------------------- |
| width                      | w                                                                                              |
| height                     | h                                                                                              |
| aspectRatio                | ar                                                                                             |
| quality                    | q                                                                                              |
| aiRemoveBackground         | e-bgremove (ImageKit powered)                                                                  |
| aiRemoveBackgroundExternal | e-removedotbg (Using third party)                                                              |
| aiEdit                     | e-edit                                                                                         |
| aiUpscale                  | e-upscale                                                                                      |
| aiRetouch                  | e-retouch                                                                                      |
| aiVariation                | e-genvar                                                                                       |
| aiDropShadow               | e-dropshadow                                                                                   |
| aiChangeBackground         | e-changebg                                                                                     |
| colorize                   | e-colorize                                                                                     |
| gradient                   | e-gradient                                                                                     |
| distort                    | e-distort                                                                                      |
| crop                       | c                                                                                              |
| cropMode                   | cm                                                                                             |
| x                          | x                                                                                              |
| y                          | y                                                                                              |
| xCenter                    | xc                                                                                             |
| yCenter                    | yc                                                                                             |
| focus                      | fo                                                                                             |
| format                     | f                                                                                              |
| radius                     | r                                                                                              |
| background                 | bg                                                                                             |
| border                     | b                                                                                              |
| rotation                   | rt                                                                                             |
| blur                       | bl                                                                                             |
| named                      | n                                                                                              |
| dpr                        | dpr                                                                                            |
| progressive                | pr                                                                                             |
| lossless                   | lo                                                                                             |
| trim                       | t                                                                                              |
| metadata                   | md                                                                                             |
| colorProfile               | cp                                                                                             |
| defaultImage               | di                                                                                             |
| original                   | orig                                                                                           |
| videoCodec                 | vc                                                                                             |
| audioCodec                 | ac                                                                                             |
| grayscale                  | e-grayscale                                                                                    |
| contrastStretch            | e-contrast                                                                                     |
| shadow                     | e-shadow                                                                                       |
| sharpen                    | e-sharpen                                                                                      |
| unsharpMask                | e-usm                                                                                          |
| gradient                   | e-gradient                                                                                     |
| flip                       | fl                                                                                             |
| opacity                    | o                                                                                              |
| zoom                       | z                                                                                              |
| page                       | pg                                                                                             |
| startOffset                | so                                                                                             |
| endOffset                  | eo                                                                                             |
| duration                   | du                                                                                             |
| streamingResolutions       | sr                                                                                             |
| colorReplace               | cr                                                                                             |
| overlay                    | Generates the correct layer syntax for image, video, text, subtitle, and solid color overlays. |
| raw                        | The string provided in raw will be added in the URL as is.                                     |


## Handling Unsupported Transformations

If you specify a transformation parameter that is not explicitly supported by the SDK, it is added “as-is” in the generated URL. This provides flexibility for using new or custom transformations without waiting for an SDK update. However add `@ts-ignore` to avoid TypeScript errors for unsupported transformations, or add transformation as a string in the `raw` parameter.

For example:

```jsx
import { Image, ImageKitProvider } from '@imagekit/react';
export default function UnsupportedTransformation() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Image
        src="/photo.jpg"
        alt="Photo with unsupported transformation"
        transformation={[
          { unsupportedTransformation: "value" }
        ]}
      />
    </ImageKitProvider>
  );
}

// Output: https://ik.imagekit.io/your_imagekit_id/photo.jpg?tr=unsupportedTransformation-value
```

## Overlay Reference

This SDK provides `overlay` as a transformation parameter. The overlay can be a text, image, video, subtitle, or solid color.

Overlays in ImageKit are applied using layers, allowing you to stack multiple overlays on top of each other. Each overlay can be styled and positioned independently. For more details, refer to the [layer documentation](/transformations#overlay-using-layers).

The SDK automatically generates the correct layer syntax for image, video, text, subtitle, and solid color overlays. You can also specify the overlay position, size, and other properties.

The table below outlines the available overlay configuration options:

{% table %}

- Option {% width="30%" %}
- Description and Example {% width="70%" %}

---

- **type**  
  (Required)
- Specifies the type of overlay. Supported values: `text`, `image`, `video`, `subtitle`, `solidColor`. Example: `type: "text"`

---

- **text**  
  (Required for text overlays)
- The text content to display. Example: `text: "ImageKit"`

---

- **input**  
  (Required for image, video, or subtitle overlays)
- Relative path to the overlay asset. Example: `input: "logo.png"` or `input: "overlay-video.mp4"`

---

- **color**  
  (Required for solidColor overlays)
- RGB/RGBA hex code or color name for the overlay color. Example: `color: "FF0000"`

---

- **encoding**
- Accepted values: `auto`, `plain`, `base64`. [Check this](#encoding-options) for more details. Example: `encoding: "auto"`

---

- **transformation**
- An array of transformation objects to style the overlay independently of the base asset. Each overlay type has its own set of supported transformations.
  - For example, for text overlays, you can specify `fontSize`, `fontColor`, `background`, etc. Example: `transformation: [{ fontSize: 20, fontColor: "FF0000" }]`. Check out the [text overlay transformations](#text-overlay-transformations) section for more options.
  - For image overlays, you can specify `width`, `height`, `radius`, etc. Example: `transformation: [{ width: 100, height: 100 }]`. Check [reference](/add-overlays-on-images#list-of-supported-image-transformations-in-image-layers) for complete list of transformations supported on image overlays.
  - For video overlays, you can specify `width`, `height`, `rotation`, etc. Example: `transformation: [{ width: 100, height: 100 }]`. Check [reference](/add-overlays-on-videos#list-of-transformations-supported-on-image-overlay) for complete list of transformations supported on video overlays.
  - For subtitle overlays, you can specify `fontSize`, `fontColor`, `background`, etc. Example: `transformation: [{ fontSize: 20, fontColor: "FF0000" }]`. Check out the [subtitle overlay transformations](#subtitle-overlay-transformations) section for more options.
  - For solid color overlays, you can specify `width`, `height`, `radius`, etc. Example: `transformation: [{ width: 100, height: 100 }]`. Check out the [solid color overlay transformations](#solid-color-overlay-transformations) section for more options.


---

- **layerMode**
- Controls how the layer blends with the base image or underlying content. 
  - By default, layers completely cover the base image beneath them. Layer modes change this behavior. 
  - Supported values: `multiply`, `displace`, `cutout`, `cutter`, Check [reference](/add-overlays-on-images#layer-modes)

---

- **position**
- Sets the overlay’s position relative to the base asset. Accepts an object with `x`, `y`, or `focus`. Example: `position: { x: 10, y: 20 }` or `position: { focus: "center" }`

---

- **timing**
- (For video base) Specifies when the overlay appears using `start`, `duration`, and `end` (in seconds); if both `duration` and `end` are set, `duration` is ignored. Example: `timing: { start: 5, duration: 10 }`

{% /table %}

### Encoding Options

Overlay encoding options define how the overlay input is converted for URL construction. When set to `auto`, the SDK automatically determines whether to use plain text or Base64 encoding based on the input content.

For text overlays:
- If `auto` is used, the SDK checks the text overlay input: if it is URL-safe, it uses the format `i-{input}` (plain text); otherwise, it applies Base64 encoding with the format `ie-{base64_encoded_input}`.
- You can force a specific method by setting encoding to `plain` (always use `i-{input}`) or `base64` (always use `ie-{base64}`).
- Note: In all cases, the text is percent-encoded to ensure URL safety.

For image, video, and subtitle overlays:
- The input path is processed by removing any leading/trailing slashes and replacing inner slashes with `@@` when `plain` is used.
- Similarly, if `auto` is used, the SDK determines whether to apply plain text or Base64 encoding based on the characters present.
- For explicit behavior, use `plain` or `base64` to enforce the desired encoding.

Use `auto` for most cases to let the SDK optimize encoding, and use `plain` or `base64` when a specific encoding method is required.

### Solid Color Overlay Transformations

| Option     | Description                                                                                                                                                                                                                   | Example             |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| width      | Specifies the width of the solid color overlay block (in pixels or as an arithmetic expression).                                                                                                                              | `width: 100`        |
| height     | Specifies the height of the solid color overlay block (in pixels or as an arithmetic expression).                                                                                                                             | `height: 50`        |
| radius     | Specifies the corner radius of the solid color overlay block or shape. Can be a number or `"max"` for circular/oval shapes.                                                                                                   | `radius: "max"`     |
| alpha      | Specifies the transparency level of the solid color overlay. Supports integers from 1 (most transparent) to 9 (least transparent).                                                                                            | `alpha: 5`          |
| background | Specifies the background color of the solid color overlay. Accepts an RGB hex code, an RGBA code, or a standard color name.                                                                                                   | `background: "red"` |
| gradient   | Only works if base asset is an image. Creates a linear gradient with two colors. Pass `true` for a default gradient, or provide a string for a custom gradient. [Learn more](/effects-and-enhancements#gradient---e-gradient) | `gradient: true`    |

### Text Overlay Transformations

| Option         | Description                                                                                                                                                              | Example                    |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- |
| width          | Specifies the maximum width (in pixels) of the overlaid text. The text wraps automatically, and arithmetic expressions are supported (e.g., `bw_mul_0.2` or `bh_div_2`). | `width: 400`               |
| fontSize       | Specifies the font size of the overlaid text. Accepts a numeric value or an arithmetic expression.                                                                       | `fontSize: 50`             |
| fontFamily     | Specifies the font family of the overlaid text. Choose from the supported fonts or provide a custom font.                                                                | `fontFamily: "Arial"`      |
| fontColor      | Specifies the font color of the overlaid text. Accepts an RGB hex code, an RGBA code, or a standard color name.                                                          | `fontColor: "FF0000"`      |
| innerAlignment | Specifies the inner alignment of the text when it doesn’t occupy the full width. Supported values: `left`, `right`, `center`.                                            | `innerAlignment: "center"` |
| padding        | Specifies the padding around the text overlay. Can be a single integer or multiple values separated by underscores; arithmetic expressions are accepted.                 | `padding: 10`              |
| alpha          | Specifies the transparency level of the text overlay. Accepts an integer between `1` and `9`.                                                                            | `alpha: 5`                 |
| typography     | Specifies the typography style of the text. Supported values: `b` for bold, `i` for italics, and `b_i` for bold with italics.                                            | `typography: "b"`          |
| background     | Specifies the background color of the text overlay. Accepts an RGB hex code, an RGBA code, or a color name.                                                              | `background: "red"`        |
| radius         | Specifies the corner radius of the text overlay. Accepts a numeric value or `max` for circular/oval shape.                                                               | `radius: "max"`            |
| rotation       | Specifies the rotation angle of the text overlay. Accepts a numeric value for clockwise rotation or a string prefixed with `N` for counterclockwise rotation.            | `rotation: 90`             |
| flip           | Specifies the flip option for the text overlay. Supported values: `h`, `v`, `h_v`, `v_h`.                                                                                | `flip: "h"`                |
| lineHeight     | Specifies the line height for multi-line text. Accepts a numeric value or an arithmetic expression.                                                                      | `lineHeight: 20`           |

### Subtitle Overlay Transformations

| Option      | Description                                                                                               | Example                 |
| ----------- | --------------------------------------------------------------------------------------------------------- | ----------------------- |
| background  | Specifies the subtitle background color using a standard color name, RGB color code, or RGBA color code.  | `background: "blue"`    |
| fontSize    | Sets the font size of subtitle text.                                                                      | `fontSize: 16`          |
| fontFamily  | Sets the font family of subtitle text.                                                                    | `fontFamily: "Arial"`   |
| color       | Specifies the font color of subtitle text using standard color name, RGB, or RGBA color code.             | `color: "FF0000"`       |
| typography  | Sets the typography style of subtitle text. Supported values: `b`, `i`, `b_i`.                            | `typography: "b"`       |
| fontOutline | Specifies the font outline for subtitles. Requires an outline width and color separated by an underscore. | `fontOutline: "2_blue"` |
| fontShadow  | Specifies the font shadow for subtitles. Requires shadow color and indent separated by an underscore.     | `fontShadow: "blue_2"`  |


## Video Player SDK

Looking to embed videos with advanced playback features? The **ImageKit Video Player SDK** is a powerful video player built on Video.js with enhanced capabilities like **AI-generated subtitles and chapters**, shoppable videos, playlists, and more.

### Quick Example

Install the Video Player SDK:

```bash
npm install @imagekit/video-player
```

Create a fully-featured video player component:

```jsx
import { IKVideoPlayer } from '@imagekit/video-player/react';
import '@imagekit/video-player/styles.css';

function VideoPage() {
  const ikOptions = {
    imagekitId: 'YOUR_IMAGEKIT_ID',
    seekThumbnails: true, // Show previews on hover
    floatingWhenNotVisible: 'right', // Sticky player on scroll
    logo: {
      showLogo: true,
      logoImageUrl: 'https://your-domain.com/logo.png',
      logoOnclickUrl: 'https://your-domain.com'
    }
  };

  const source = {
    src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
    info: {
      title: 'Product Demo',
      description: 'Watch our latest product in action'
    },
    
    // AI-powered features - no manual work required!
    chapters: true, // Auto-generate chapters from video content
    textTracks: [{
      autoGenerate: true, // AI speech-to-text transcription
      default: true,
      maxChars: 60,
      highlightWords: true, // Karaoke-like word highlighting
      translations: [
        { langCode: 'es', label: 'Spanish' },
        { langCode: 'fr', label: 'French' },
        { langCode: 'de', label: 'German' }
      ]
    }],
    
    transformation: [
      { width: 800, height: 600 },
      { quality: 80 }
    ]
  };

  return (
    <div>
      <h1>Video Player Demo</h1>
      <IKVideoPlayer
        ikOptions={ikOptions}
        source={source}
      />
    </div>
  );
}

export default VideoPage;
```

{% callout style="info" %}
**AI-Powered Features:** The example above uses ImageKit's AI to automatically generate accurate subtitles in 50+ languages, create intelligent chapters, and enable word-level highlighting—all without manual transcription work.
{% /callout %}

[**Explore Video Player SDK →**](/video-player/overview)


---

# Source: /integration/vuejs

---
title: Vue ImageKit SDK
description: >-
  Real-time image & video resizing, automatic optimization, responsive images, and file uploading in Vue 3 using ImageKit.io.
---

The **Vue ImageKit SDK** is a Vue-specific wrapper built on top of the core ImageKit JavaScript SDK. It brings ImageKit’s URL generation, transformation, responsive-image handling, and file-upload capabilities to Vue 3 in a lightweight package with full TypeScript support.  

Source code is available on [GitHub](https://github.com/imagekit-developer/imagekit-vuejs) under the MIT license.

The SDK works in both SSR (e.g. Nuxt 3) and CSR (Vite / Vue CLI).

## Installation & Setup

Install the SDK via npm, yarn, or pnpm:

```bash
npm i @imagekit/vue
# or
yarn add @imagekit/vue
# or
pnpm add @imagekit/vue
```

What's included in the SDK:

{% table %}

- Export {% width="30%" %}
- Description {% width="70%" %}

---

- [`Image`](#image-component) component  
- `<img>` wrapper with automatic `src`/`srcset` generation, lazy-loading, transformations, etc.

---

- [`Video`](#video-component) component  
- `<video>` wrapper with automatic URL generation & transformations

---

- `ImageKitProvider` component  
- Provides default `urlEndpoint` / `transformationPosition` to all nested Image & Video components

---

- [`buildSrc`](/integration/javascript#buildsrc-parameters), [`buildTransformationString`](/integration/javascript#buildtransformationstring-parameters)  
- Low-level helpers for manual URL building

---

- [`getResponsiveImageAttributes`](/integration/javascript#getresponsiveimageattributes-parameters)  
- Generates `src`, `srcset`, `sizes` for a plain HTML `<img>`

---

- [`upload`](#upload-parameters) utility  
- Browser-side file uploads (uses Upload v1 API)

---

- Error classes  
- `ImageKitInvalidRequestError`, `ImageKitAbortError`, `ImageKitUploadNetworkError`, `ImageKitServerError`

---

- TypeScript types  
- `ImageKitProviderProps`, `IKImageProps`, `IKVideoProps`, `SrcOptions`, `UploadOptions`, `UploadResponse`, `Transformation`, `GetImageAttributesOptions`, and `ResponsiveImageAttributes` etc.

{% /table %}

## Quick example

```jsx
<script setup lang="ts">
import { Image } from '@imagekit/vue'
</script>

<template>
  <Image
    url-endpoint="https://ik.imagekit.io/your_imagekit_id"
    src="/profile.png"
    width="500"
    height="500"
    alt="Author photo" />
</template>
```

To avoid repeating `urlEndpoint` everywhere, you can wrap your components in an `ImageKitProvider` component. All nested `Image` and `Video` components will inherit the `urlEndpoint` and `transformationPosition` props from the provider.

Any children will be rendered as-is, so you can use it to wrap your entire app or just a part of it.

```jsx
<script setup lang="ts">
import { ImageKitProvider, Image } from '@imagekit/vue'
</script>

<template>
  <ImageKitProvider url-endpoint="https://ik.imagekit.io/your_imagekit_id">
    <Image
      src="/profile.png"
      width="500"
      height="500"
      alt="Author photo" />
  </ImageKitProvider>
</template>
```

## Image component

The `Image` component is a wrapper around the HTML `img` element. It allows you to use ImageKit’s URL generation and transformation, lazy-loading, responsive images etc.
 
It accepts every regular `<img>` attribute plus the following ImageKit-specific props. All other attributes (class, id, data-, aria-, etc.) are forwarded untouched except `srcset`. The SDK will generate the `srcset` attribute automatically and ignore any custom `srcset` you provide.

{% table %}

- Parameter {% width="30%" %}
- Description and Example {% width="70%" %}

---

- **urlEndpoint**  
- The base URL endpoint from your [ImageKit dashboard](https://imagekit.io/dashboard/url-endpoints).
  To avoid passing this prop in every component, you can wrap your components in an `ImageKitProvider` and set the `urlEndpoint` there. In case you pass it in the component, it will override the value set in the provider.
  
  Example: `https://ik.imagekit.io/your_imagekit_id`.

---

- **src**  
  (Required)  
- A relative or absolute path to the image.

  - If a **relative path** is provided, it is appended to the `urlEndpoint`.
  - If an **absolute path** is provided, it is used as-is and the `urlEndpoint` is ignored.
  - **Do not include query parameters** directly in the `src`. Use the `queryParameters` prop instead.
  - **When using a web proxy**, you can pass the full image URL and prepend it with a `/`. For example - `/https://example.com/image.jpg`.

  **Examples:**  
  Relative - `/default-image.jpg`  
  Absolute - `https://example.com/image.jpg`  
  Web Proxy - `/https://example.com/image.jpg`

---

- **width**
- The width of the image in pixels (in numbers). This is used to calculate the srcSet attribute and is only utilized when sizes is not provided. The prop is set on the `<img>` element as it is. If provided value is not a number, then `srcset` is generated using the full list of device breakpoints
  
  Example: `width="300"`

---

- **transformation**
- An array of transformation objects. Each object can include properties like `width`, `height`, `rotation`, overlays, and advanced effects.  
  
  Example: `[ { width: 300, height: 300 } ]`  
  
  See all [supported transformation](#supported-transformations) options and how to [handle unsupported transformations](#handling-unsupported-transformations).

---

- **queryParameters**
- An object with additional query parameters to append to the URL.  
  Example: `{ v: 2 }`

---

- **responsive**
- A boolean that determines if responsive image functionality is enabled. By default, this is `true`, meaning that a `srcset` attribute is automatically generated for responsive images. Set it to `false` to disable this behavior and only apply explicitly defined transformations.

---

- **deviceBreakpoints**  
  (number[])
- It allows you to specify a list of device width breakpoints.

  Defaults to `[640, 750, 828, 1080, 1200, 1920, 2048, 3840]`.

---

- **imageBreakpoints**  
  (number[])
- It allows you to specify a list of image width breakpoints. It is concatenated with `deviceBreakpoints` before calculating `srcSet`. 
  
  Defaults to `[16, 32, 48, 64, 96, 128, 256, 384]`.

---

- **transformationPosition**
- Specifies whether the transformation string is included in the URL path or as a query parameter. Defaults to `"query"`.  
  Example: `"query"` or `"path"`

{% /table %}

## Video component

The `Video` component is a lightweight wrapper around the HTML `video` element. It allows you to use ImageKit’s URL generation and transformation capabilities. It supports all [HTML video attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video#attributes) and additionally accepts the following ImageKit-specific props - `urlEndpoint`, `transformation`, `transformationPosition`, and `queryParameters`. For the definition of these props, refer to the [Image component](#image-component) section.

```jsx
<Video
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/movie.mp4"
  controls
  width="640"
  height="360" />
```

## Height and Width Transformations

With ImageKit, you can resize images on the fly using the `width` and `height` properties. The SDK automatically generates the appropriate URL with the specified dimensions.

```jsx
<Image
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/photo.jpg"
  width="300"
  height="300"
  :transformation="[{ width: 300, height: 300 }]"
  alt="Square thumb" />
```

## Responsive Images

The `<Image>` component in Vue SDK comes with built-in support for **responsive images**, enabled by default. It automatically generates the appropriate `srcset` attributes ensuring images are delivered in the most optimal dimension for various screen sizes.

Behind the scenes, it utilizes the [`getResponsiveImageAttributes`](/integration/javascript#getresponsiveimageattributes-parameters) helper from the core JavaScript SDK to compute these responsive attributes.

To disable responsive behavior, simply set the `responsive` prop to `false`. This will prevent the component from generating the `srcset` attributes automatically.

{% callout style="info" %}
**Note:** If you have enabled the "Restrict unnamed transformations" setting (see [Basic Security](/media-delivery-basic-security#restrict-unnamed-transformations)), hardcoded width/crop transformations may be added by default causing request failures. Setting `responsive` to `false` prevents these additional transformations from being applied.
{% /callout %}

## Lazy Loading Images

The `Image` component supports lazy loading by default. You can control this behavior using the [`loading`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/img#loading) prop.

By default, `loading` is set to `lazy`, which defers loading the image until it is near the viewport.

If set to `eager`, the image loads immediately.

```jsx
<Image
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/photo.jpg"
  width="300"
  height="300"
  loading="eager"
  alt="Eager load" />
```

## Lazy Loading Videos

To lazy load a video using `Video` component, you can set the `preload` attribute to `none` and specify a `poster` image by extracting a thumbnail from the video.

The [`buildSrc`](/integration/javascript#buildsrc-parameters) utility function is used to generate the thumbnail URL. It accepts the same parameters as the `Video`/`Image` component and returns a URL with the specified transformations.

Refer to the [create thumbnail](/create-video-thumbnails) documentation for detailed instructions on generating a thumbnail from a video using ImageKit.

```jsx
<script setup lang="ts">
import { Video, buildSrc } from '@imagekit/vue'

const posterUrl = buildSrc({
  urlEndpoint: 'https://ik.imagekit.io/your_imagekit_id',
  src: '/movie.mp4/ik-thumbnail.jpg'
})
</script>

<template>
  <Video
    url-endpoint="https://ik.imagekit.io/your_imagekit_id"
    src="/movie.mp4"
    preload="none"
    controls
    :poster="posterUrl" />
</template>
```

## Chained Transformations

You can chain multiple transformations together by passing an array of transformation objects. Each object can specify different properties, such as width, height, cropping, overlays, and effects. See [chained transformations](/transformations#chained-transformations) for more details.

```jsx
<Image
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/profile.png"
  :transformation="[
    { width: 400, height: 300 },
    { rotation: 90 }
  ]"
  width="400"
  height="300"
  alt="Rotated" />
```

## Adding Overlays

You can add overlays to images and videos. The overlay can be a text, image, video, or subtitle.

Besides the overlay type, you can also specify the position, size, and other properties of the overlay. Check the [overlay options](#overlay-reference) for more details.

### Image Overlay

```jsx
<Image
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/background.png"
  :transformation="[
    { overlay: { type: 'image', input: 'logo.png' } }
  ]"
  width="400"
  height="300"
  alt="Background with image overlay" />
```

You can independently transform the overlay image by passing a transformation array inside the `overlay` object. The transformation will be applied to the overlay image only.

```jsx
<Image
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/background.png"
  :transformation="[
    { 
      overlay: { 
        type: 'image',
        input: 'logo.png',
        transformation: [{ width: 100, height: 100 }]
      } 
    }
  ]"
  width="400"
  height="300"
  alt="Background with image overlay" />
```

Image overlays support a wide range of transformations. Check [reference](/add-overlays-on-images#list-of-supported-image-transformations-in-image-layers) for the complete list of transformations supported on image overlays.

### Solid Color Overlay

You can add a solid color overlay to images and videos.

```jsx
<Image
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/background.jpg"
  width="400"
  height="300"
  :transformation="[
    { 
      overlay: { 
        type: 'solidColor', 
        color: 'FF0000',
      } 
    }
  ]" />
```

You can also specify the width, height, and other properties of the solid color overlay. For example:

```jsx
<Image
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/background.jpg"
  width="400"
  height="300"
  :transformation="[
    { 
      overlay: { 
        type: 'solidColor', 
        color: 'FF0000',
        transformation: [
          { width: 100, height: 100 }
        ]
      } 
    }
  ]" />
```

For more options related to styling the solid color overlay, check the [solid color overlay transformations](#solid-color-overlay-transformations) section.

### Text Overlay

You can add text overlays to images and videos.

```jsx
<Image
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/background.jpg"
  width="400"
  height="300"
  :transformation="[
    { 
      overlay: { 
        type: 'text', 
        text: 'Hello World',
      } 
    }
  ]" />
```

You can also specify the font size, color, and other properties of the text overlay. For example:

```jsx
<Image
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/background.jpg"
  width="400"
  height="300"
  :transformation="[
    { 
      overlay: { 
        type: 'text', 
        text: "Hello, ImageKit!",
        transformation: [
          { fontSize: 20, fontColor: 'FF0000' }
        ] 
      } 
    }
  ]" />
```

Check the [text overlay transformations](#text-overlay-transformations) section for more options related to styling the text.

### Video Overlay

You can add video overlays on videos only.

```jsx
<Video
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/background.mp4"
  controls
  :transformation="[
    { 
      overlay: { 
        type: 'video', 
        input: 'overlay.mp4',
      } 
    }
  ]" />
```

Additionally, you can specify the start and duration for the overlay video. For example:

```jsx
<Video
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/background.mp4"
  controls
  :transformation="[
    { 
      overlay: { 
        type: 'video', 
        input: 'overlay.mp4',
        timing: { start: 5, duration: 10 }
      } 
    }
  ]" />
```

You can also independently transform the overlay video. For example, to resize the overlay video:

```jsx
<Video
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/background.mp4"
  controls
  :transformation="[
    { 
      overlay: { 
        type: 'video', 
        input: 'overlay.mp4',
        transformation: [{ width: 100, height: 100 }]
      } 
    }
  ]" />
```

All supported [video transformations](/video-transformation) can also be applied to overlay videos.

If you're overlaying an image on a base video, refer to [this list](/add-overlays-on-videos#list-of-transformations-supported-on-image-overlay) for all the transformations supported on image overlays.

### Subtitle Overlay

You can add subtitle overlays on videos.

```jsx
<Video
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/background.mp4"
  controls
  :transformation="[
    { 
      overlay: { 
        type: 'subtitle', 
        input: 'subtitle.srt',
      } 
    }
  ]" />
```

The subtitle overlay can be styled with various properties such as font size, color, and outline. See the [Subtitle Overlay Transformations](#subtitle-overlay-transformations) section for all styling options.

## Background Removal Using AI

```jsx
<Image
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/photo.jpg"
  alt="Photo with background removal"
  width="400"
  height="300"
  :transformation="[
    { aiRemoveBackground: true }
  ]" />
```

ImageKit supports multiple AI-powered transformations, like upscaling, generative fill, and more. More examples:

```jsx
<Image
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/photo.jpg"
  alt="Photo with AI drop shadow"
  width="400"
  height="300"
  :transformation="[
    { aiDropShadow: true }
  ]" />
```

Upscaling example:

```jsx
<Image
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/photo.jpg"
  alt="Photo with AI upscaling"
  width="400"
  height="300"
  :transformation="[
    { aiUpscale: true }
  ]" />
```

## Arithmetic Expressions

You can use arithmetic expressions to dynamically compute transformation values. For example, to set the width to half of the original image width:

```jsx
<Image
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/photo.jpg"
  alt="Photo with arithmetic width"
  width="400"
  height="300"
  :transformation="[
    { width: "iw_div_2" }
  ]" />
```

Check out the [Arithmetic Expressions](/arithmetic-expressions-in-transformations) reference for more examples and details.

## Uploading Files

The Vue.js SDK exports a utility function, `.upload`, which enables you to upload files to ImageKit. This `upload()` function leverages the [Upload V1 API](/api-reference/upload-file/upload-file), accepting an options object and returning a promise that resolves with the upload response.

The SDK automatically converts certain parameters into JSON strings, as required by the API. If a parameter is not explicitly supported by the SDK, it is included in the request as-is. For a complete list of parameters and expected formats, refer to the API documentation.

### upload() Parameters

The `upload()` function accepts a JSON object with the following parameters:

{% table %}

- Option {% width="30%" %}
- Description and Example {% width="70%" %}

---

- **file**  
  (Required)  
- The file content to be uploaded. Accepts binary data, a base64-encoded string, or a URL. Typically used with a File or Blob in the browser. Example: `file: fileInput.files[0]`

---

- **fileName**  
  (Required)  
- The name to assign to the uploaded file. Supports alphanumeric characters, dot, underscore, and dash. Any other character is replaced with `_`. Example: `fileName: "myImage.jpg"`

---

- **signature**  
  (Required)  
- The HMAC-SHA1 digest of the concatenation of "token + expire". The signing key is your ImageKit private API key. Must be computed on the server side. Example: `signature: "generated_signature"`

---

- **token**  
  (Required)  
- A unique value to identify and prevent replays. Typically a UUID (e.g., version 4). Example: `token: "unique_upload_token"`
  
  Check the [signature generation](#generating-authentication-parameters) section for more details on how to generate this value.

---

- **expire**  
  (Required)  
- A Unix timestamp in seconds, less than 1 hour in the future. Example: `expire: 1616161616`
  
  Check the [signature generation](#generating-authentication-parameters) section for more details on how to generate this value.

---

- **publicKey**  
  (Required)
- The public API key for your ImageKit account. This is used to identify the account making the upload request. Example: `publicKey: "your_public_api_key"`
  
  Check the [signature generation](#generating-authentication-parameters) section for more details on how to generate this value.

---

- **onProgress**
- A callback function to track the upload progress. It receives an event object with `loaded` and `total` properties. Example: `onProgress: (event) => console.log(event.loaded, event.total)`
  This is useful for showing upload progress to the user.

---
- **abortSignal**
- An optional `AbortSignal` object to abort the upload request. If the signal is already aborted, the upload will fail immediately.
  You can create an `AbortController` instance and pass its signal to the `upload()` function.

---

- **useUniqueFileName**
- Boolean flag to automatically generate a unique filename if set to true. Defaults to true. If false, the image is uploaded with the provided filename, replacing any existing file with the same name. Example: `useUniqueFileName: true`

---

- **folder**
- The folder path where the file will be stored, e.g., "/images/folder/". If the path doesn't exist, it is created on-the-fly. Example: `folder: "/images/uploads"`

---

- **isPrivateFile**
- Boolean to mark the file as private, restricting access to the original file URL. A private file requires signed URLs or named transformations for access. Defaults to false. Example: `isPrivateFile: false`

---

- **tags**
- Optionally set tags on the uploaded file. Can be a comma-separated string or an array of tags. Example: `tags: "summer,holiday"` or `tags: ["summer","holiday"]`

---

- **customCoordinates**
- A string in "x,y,width,height" format that defines the region of interest in an image (top-left coords and area size). Example: `customCoordinates: "10,10,100,100"`

---

- **responseFields**
- A comma-separated or array-based set of fields to return in the upload response. Example: `responseFields: "tags,customCoordinates"`

---

- **extensions**
- An array of extension objects to apply to the image, e.g., background removal, auto-tagging, etc. Example: `extensions: [{ name: "auto-tagging" }]`

---

- **webhookUrl**
- A webhook URL to receive the final status of any pending extensions once they've completed processing. Example: `webhookUrl: "https://example.com/webhook"`

---

- **overwriteFile**
- Defaults to true. If false, and "useUniqueFileName" is also false, the API immediately fails if a file with the same name/folder already exists. Example: `overwriteFile: true`

---

- **overwriteAITags**
- Defaults to true. If true, and an existing file is found at the same location, its AITags are removed. Set to false to keep existing AITags. Example: `overwriteAITags: true`

---

- **overwriteTags**
- Defaults to true. If no tags are specified in the request, existing tags are removed from overwritten files. Setting to false has no effect if the request includes tags. Example: `overwriteTags: true`

---

- **overwriteCustomMetadata**
- Defaults to true. If no customMetadata is specified in the request, existing customMetadata is removed from overwritten files. Setting to false has no effect if the request specifies customMetadata. Example: `overwriteCustomMetadata: true`

---

- **customMetadata**
- A stringified JSON or an object containing custom metadata fields to store with the file. Custom metadata fields must be pre-defined in your ImageKit configuration. Example: `customMetadata: {author: "John Doe"}`

---

- **transformation**
- Defines pre and post transformations to be applied to the file during upload. The SDK enforces certain validation rules for pre/post transformations. Example: `transformation: { pre: "w-200,h-200", post: [...] }`

---

- **xhr**
- An optional XMLHttpRequest instance for the upload. The SDK merges it with its own logic to handle progress events, etc. Example: `xhr: new XMLHttpRequest()`

---

- **checks**
- A string specifying the checks to be performed server-side before uploading to the media library, e.g., size or mime type checks. Example: `checks: "file.size' < '1MB'"`

{% /table %}


## Upload Example and Error Handling

The `.upload` function expects the following mandatory parameters:

- **`file` and `fileName`** – The file to be uploaded and the name you want to assign to it. The `file` value can be a `File` object, a base64-encoded string, or a URL.
- **Authentication parameters** – `token`, `signature`, `expire`, and `publicKey`.

Authentication is essential for secure file uploads from the browser. You should **never expose your private API key** in client-side code. Instead, generate these one-time authentication parameters on the **server side** and pass them to the client.

To simplify the process, all of our [backend SDKs](/quick-start-guides#back-end) include utility functions for generating authentication parameters.

### Upload Flow Overview

Here’s how the upload process using the SDK works:

1. **Client Request for Auth Parameters**  
   The client component calls an API route to fetch the authentication parameters.  
   You can implement your own application logic within this route to authenticate the user.  
   After that, use one of our backend SDKs to generate the required auth parameters and return them to the client.

2. **File Upload**  
   Once the client has the auth parameters, it can call the `.upload` function with the necessary data.

### Generating Authentication Parameters

The following example demonstrates how to create an API route that generates authentication parameters using the ImageKit [backend SDKs](/quick-start-guides#back-end).

You can find your [private key](/api-keys#private-key) and [public key](/api-keys#public-key) in the ImageKit dashboard.

{% tabs %}
{% tab title="Node.js" %}
```js
const express = require('express');
const ImageKit = require('@imagekit/nodejs'); // Node.js SDK
const app = express();

const client = new ImageKit({
  privateKey: process.env.IMAGEKIT_PRIVATE_KEY
});

// allow cross-origin requests
app.use(function(req, res, next) {
  res.header("Access-Control-Allow-Origin", "*");
  res.header("Access-Control-Allow-Headers", 
    "Origin, X-Requested-With, Content-Type, Accept");
  next();
});

app.get('/auth', function (req, res) {
  // Your application logic to authenticate the user
  // For example, you can check if the user is logged in or has the necessary permissions
  // If the user is not authenticated, you can return an error response
  const { token, expire, signature } = client.helper.getAuthenticationParameters();
  res.send({ token, expire, signature, publicKey: process.env.IMAGEKIT_PUBLIC_KEY });
});

app.listen(3000, function () {
  console.log('Live at Port 3000');
});
```
{% /tab %}

{% tab title="Go" %}
```go
package main

import (
	"encoding/json"
	"log"
	"net/http"
	"os"

	"github.com/imagekit-developer/imagekit-go/v2"
	"github.com/imagekit-developer/imagekit-go/v2/option"
)

func main() {
	client := imagekit.NewClient(
		option.WithPrivateKey(os.Getenv("IMAGEKIT_PRIVATE_KEY")),
	)

	http.HandleFunc("/auth", func(w http.ResponseWriter, r *http.Request) {
		// Enable CORS
		w.Header().Set("Access-Control-Allow-Origin", "*")
		w.Header().Set("Access-Control-Allow-Headers", "Origin, X-Requested-With, Content-Type, Accept")

		// Your application logic to authenticate the user
		// For example, you can check if the user is logged in or has the necessary permissions
		// If the user is not authenticated, you can return an error response

		authParams := client.Helper.GetAuthenticationParameters("", 0)
		
		response := map[string]interface{}{
			"token":     authParams["token"],
			"expire":    authParams["expire"],
			"signature": authParams["signature"],
			"publicKey": os.Getenv("IMAGEKIT_PUBLIC_KEY"),
		}

		w.Header().Set("Content-Type", "application/json")
		json.NewEncoder(w).Encode(response)
	})

	log.Println("Live at Port 3000")
	log.Fatal(http.ListenAndServe(":3000", nil))
}
```
{% /tab %}

{% tab title="Python" %}
```python
import os
from flask import Flask, jsonify
from imagekitio import ImageKit

app = Flask(__name__)

imagekit = ImageKit(
    private_key=os.environ.get("IMAGEKIT_PRIVATE_KEY")
)

# Enable CORS
@app.after_request
def after_request(response):
    response.headers.add('Access-Control-Allow-Origin', '*')
    response.headers.add('Access-Control-Allow-Headers', 'Origin, X-Requested-With, Content-Type, Accept')
    return response

@app.route('/auth')
def get_auth():
    # Your application logic to authenticate the user
    # For example, you can check if the user is logged in or has the necessary permissions
    # If the user is not authenticated, you can return an error response
    
    auth_params = imagekit.helper.get_authentication_parameters()
    
    return jsonify({
        'token': auth_params['token'],
        'expire': auth_params['expire'],
        'signature': auth_params['signature'],
        'publicKey': os.environ.get('IMAGEKIT_PUBLIC_KEY')
    })

if __name__ == '__main__':
    app.run(port=3000)
```
{% /tab %}

{% tab title="Ruby" %}
```ruby
require 'sinatra'
require 'imagekitio'
require 'json'

# Enable CORS
before do
  headers['Access-Control-Allow-Origin'] = '*'
  headers['Access-Control-Allow-Headers'] = 'Origin, X-Requested-With, Content-Type, Accept'
end

client = Imagekitio::Client.new(private_key: ENV['IMAGEKIT_PRIVATE_KEY'])

get '/auth' do
  content_type :json
  
  # Your application logic to authenticate the user
  # For example, you can check if the user is logged in or has the necessary permissions
  # If the user is not authenticated, you can return an error response
  
  auth_params = client.helper.get_authentication_parameters
  
  {
    token: auth_params[:token],
    expire: auth_params[:expire],
    signature: auth_params[:signature],
    publicKey: ENV['IMAGEKIT_PUBLIC_KEY']
  }.to_json
end

# Start the server
set :port, 3000
```
{% /tab %}

{% tab title="Java" %}
```java
import io.imagekit.client.ImageKitClient;
import io.imagekit.client.okhttp.ImageKitOkHttpClient;
import spark.Spark;
import com.google.gson.Gson;
import java.util.Map;
import java.util.HashMap;

// Using Spark framework (http://sparkjava.com)
public class AuthServer {
    public static void main(String[] args) {
        ImageKitClient client = ImageKitOkHttpClient.builder()
            .privateKey(System.getenv("IMAGEKIT_PRIVATE_KEY"))
            .build();

        Gson gson = new Gson();

        // Enable CORS
        Spark.before((request, response) -> {
            response.header("Access-Control-Allow-Origin", "*");
            response.header("Access-Control-Allow-Headers", "Origin, X-Requested-With, Content-Type, Accept");
        });

        Spark.get("/auth", (request, response) -> {
            // Your application logic to authenticate the user
            // For example, you can check if the user is logged in or has the necessary permissions
            // If the user is not authenticated, you can return an error response

            Map<String, Object> authParams = client.helper().getAuthenticationParameters(null, null);
            
            Map<String, Object> responseData = new HashMap<>();
            responseData.put("token", authParams.get("token"));
            responseData.put("expire", authParams.get("expire"));
            responseData.put("signature", authParams.get("signature"));
            responseData.put("publicKey", System.getenv("IMAGEKIT_PUBLIC_KEY"));

            response.type("application/json");
            return gson.toJson(responseData);
        });

        Spark.port(3000);
        System.out.println("Live at Port 3000");
    }
}
```
{% /tab %}

{% tab title=".Net" %}
```csharp
using Imagekit;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

ImageKitClient client = new() { PrivateKey = Environment.GetEnvironmentVariable("IMAGEKIT_PRIVATE_KEY") };

app.Use(async (context, next) =>
{
    context.Response.Headers["Access-Control-Allow-Origin"] = "*";
    context.Response.Headers["Access-Control-Allow-Headers"] = "Origin, X-Requested-With, Content-Type, Accept";
    await next();
});

app.MapGet("/auth", () =>
{
    // Your application logic to authenticate the user
    var authParams = client.Helper.GetAuthenticationParameters();
    return new
    {
        token = authParams.Token,
        expire = authParams.Expire,
        signature = authParams.Signature,
        publicKey = Environment.GetEnvironmentVariable("IMAGEKIT_PUBLIC_KEY"),
    };
});

Console.WriteLine("Live at Port 3000");
app.Run("http://localhost:3000");
```
{% /tab %}
{% /tabs %}

Now your client-side code can call this API route to retrieve the upload parameters.

The example below demonstrates how to use the `.upload` function in a client component to upload a file, including error handling for various upload scenarios. You can copy and paste this code into your client component and customize it as needed.

```jsx
<script setup lang="ts">
import {
  upload,
  ImageKitAbortError,
  ImageKitInvalidRequestError,
  ImageKitUploadNetworkError,
  ImageKitServerError
} from '@imagekit/vue'
import { ref } from 'vue'

const progress = ref(0)
const fileInput = ref<HTMLInputElement>()

const aborter = new AbortController()

async function authenticate() {
  const res = await fetch('/api/auth')
  if (!res.ok) throw new Error(await res.text())
  return (await res.json()) as {
    signature: string; expire: number; token: string; publicKey: string
  }
}

async function handleUpload() {
  const file = fileInput.value?.files?.[0]
  if (!file) return alert('Choose a file')

  let creds
  try { creds = await authenticate() } catch (e) {
    return console.error('Auth failed', e)
  }

  try {
    const resp = await upload({
      ...creds,
      file,
      fileName: file.name,
      onProgress: e => (progress.value = e.loaded / e.total * 100),
      abortSignal: aborter.signal
    })
    console.log('Upload OK', resp)
  } catch (err) {
    if (err instanceof ImageKitAbortError)        console.warn('Aborted')
    else if (err instanceof ImageKitInvalidRequestError) console.error('Bad request')
    else if (err instanceof ImageKitUploadNetworkError)  console.error('Network')
    else if (err instanceof ImageKitServerError)         console.error('Server side')
    else console.error(err)
  }
}
</script>

<template>
  <input type="file" ref="fileInput" />
  <button @click="handleUpload">Upload</button>
  <progress :value="progress" max="100" />
</template>
```

## Supported Transformations

The SDK gives a name to each transformation parameter (e.g. `height` maps to `h`, `width` maps to `w`). If the property does not match any of the following supported options, it is added as is in the URL.

If you want to generate transformations without any modifications, use the `raw` parameter. For example, the SDK doesn't provide a nice way to write [conditional transformations](/conditional-transformations), so you can use the `raw` parameter to add them as is.

Check [transformation documentation](/transformations) for a complete reference on all transformations supported by ImageKit.

| Transformation Name        | URL Parameter                                                                                  |
| -------------------------- | ---------------------------------------------------------------------------------------------- |
| width                      | w                                                                                              |
| height                     | h                                                                                              |
| aspectRatio                | ar                                                                                             |
| quality                    | q                                                                                              |
| aiRemoveBackground         | e-bgremove (ImageKit powered)                                                                  |
| aiRemoveBackgroundExternal | e-removedotbg (Using third party)                                                              |
| aiEdit                     | e-edit                                                                                         |
| aiUpscale                  | e-upscale                                                                                      |
| aiRetouch                  | e-retouch                                                                                      |
| aiVariation                | e-genvar                                                                                       |
| aiDropShadow               | e-dropshadow                                                                                   |
| aiChangeBackground         | e-changebg                                                                                     |
| colorize                   | e-colorize                                                                                     |
| gradient                   | e-gradient                                                                                     |
| distort                    | e-distort                                                                                      |
| crop                       | c                                                                                              |
| cropMode                   | cm                                                                                             |
| x                          | x                                                                                              |
| y                          | y                                                                                              |
| xCenter                    | xc                                                                                             |
| yCenter                    | yc                                                                                             |
| focus                      | fo                                                                                             |
| format                     | f                                                                                              |
| radius                     | r                                                                                              |
| background                 | bg                                                                                             |
| border                     | b                                                                                              |
| rotation                   | rt                                                                                             |
| blur                       | bl                                                                                             |
| named                      | n                                                                                              |
| dpr                        | dpr                                                                                            |
| progressive                | pr                                                                                             |
| lossless                   | lo                                                                                             |
| trim                       | t                                                                                              |
| metadata                   | md                                                                                             |
| colorProfile               | cp                                                                                             |
| defaultImage               | di                                                                                             |
| original                   | orig                                                                                           |
| videoCodec                 | vc                                                                                             |
| audioCodec                 | ac                                                                                             |
| grayscale                  | e-grayscale                                                                                    |
| contrastStretch            | e-contrast                                                                                     |
| shadow                     | e-shadow                                                                                       |
| sharpen                    | e-sharpen                                                                                      |
| unsharpMask                | e-usm                                                                                          |
| gradient                   | e-gradient                                                                                     |
| flip                       | fl                                                                                             |
| opacity                    | o                                                                                              |
| zoom                       | z                                                                                              |
| page                       | pg                                                                                             |
| startOffset                | so                                                                                             |
| endOffset                  | eo                                                                                             |
| duration                   | du                                                                                             |
| streamingResolutions       | sr                                                                                             |
| colorReplace               | cr                                                                                             |
| overlay                    | Generates the correct layer syntax for image, video, text, subtitle, and solid color overlays. |
| raw                        | The string provided in raw will be added in the URL as is.                                     |


## Handling Unsupported Transformations

If you specify a transformation parameter that is not explicitly supported by the SDK, it is added “as-is” in the generated URL. This provides flexibility for using new or custom transformations without waiting for an SDK update. However add `@ts-ignore` to avoid TypeScript errors for unsupported transformations, or add transformation as a string in the `raw` parameter.

For example:

```jsx
<Image
  url-endpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/photo.jpg"
  alt="Photo with unsupported transformation width"
  // @ts-ignore
  :transformation="[
    { unsupportedTransformation: "value" }
  ]" />
// Output: https://ik.imagekit.io/your_imagekit_id/photo.jpg?tr=unsupportedTransformation-value
```

## Overlay Reference

This SDK provides `overlay` as a transformation parameter. The overlay can be a text, image, video, subtitle, or solid color.

Overlays in ImageKit are applied using layers, allowing you to stack multiple overlays on top of each other. Each overlay can be styled and positioned independently. For more details, refer to the [layer documentation](/transformations#overlay-using-layers).

The SDK automatically generates the correct layer syntax for image, video, text, subtitle, and solid color overlays. You can also specify the overlay position, size, and other properties.

The table below outlines the available overlay configuration options:

{% table %}

- Option {% width="30%" %}
- Description and Example {% width="70%" %}

---

- **type**  
  (Required)
- Specifies the type of overlay. Supported values: `text`, `image`, `video`, `subtitle`, `solidColor`. Example: `type: "text"`

---

- **text**  
  (Required for text overlays)
- The text content to display. Example: `text: "ImageKit"`

---

- **input**  
  (Required for image, video, or subtitle overlays)
- Relative path to the overlay asset. Example: `input: "logo.png"` or `input: "overlay-video.mp4"`

---

- **color**  
  (Required for solidColor overlays)
- RGB/RGBA hex code or color name for the overlay color. Example: `color: "FF0000"`

---

- **encoding**
- Accepted values: `auto`, `plain`, `base64`. [Check this](#encoding-options) for more details. Example: `encoding: "auto"`

---

- **transformation**
- An array of transformation objects to style the overlay independently of the base asset. Each overlay type has its own set of supported transformations.
  - For example, for text overlays, you can specify `fontSize`, `fontColor`, `background`, etc. Example: `transformation: [{ fontSize: 20, fontColor: "FF0000" }]`. Check out the [text overlay transformations](#text-overlay-transformations) section for more options.
  - For image overlays, you can specify `width`, `height`, `radius`, etc. Example: `transformation: [{ width: 100, height: 100 }]`. Check [reference](/add-overlays-on-images#list-of-supported-image-transformations-in-image-layers) for complete list of transformations supported on image overlays.
  - For video overlays, you can specify `width`, `height`, `rotation`, etc. Example: `transformation: [{ width: 100, height: 100 }]`. Check [reference](/add-overlays-on-videos#list-of-transformations-supported-on-image-overlay) for complete list of transformations supported on video overlays.
  - For subtitle overlays, you can specify `fontSize`, `fontColor`, `background`, etc. Example: `transformation: [{ fontSize: 20, fontColor: "FF0000" }]`. Check out the [subtitle overlay transformations](#subtitle-overlay-transformations) section for more options.
  - For solid color overlays, you can specify `width`, `height`, `radius`, etc. Example: `transformation: [{ width: 100, height: 100 }]`. Check out the [solid color overlay transformations](#solid-color-overlay-transformations) section for more options.


---

- **layerMode**
- Controls how the layer blends with the base image or underlying content. 
  - By default, layers completely cover the base image beneath them. Layer modes change this behavior. 
  - Supported values: `multiply`, `displace`, `cutout`, `cutter`, Check [reference](/add-overlays-on-images#layer-modes)

---

- **position**
- Sets the overlay’s position relative to the base asset. Accepts an object with `x`, `y`, or `focus`. Example: `position: { x: 10, y: 20 }` or `position: { focus: "center" }`

---

- **timing**
- (For video base) Specifies when the overlay appears using `start`, `duration`, and `end` (in seconds); if both `duration` and `end` are set, `duration` is ignored. Example: `timing: { start: 5, duration: 10 }`

{% /table %}

### Encoding Options

Overlay encoding options define how the overlay input is converted for URL construction. When set to `auto`, the SDK automatically determines whether to use plain text or Base64 encoding based on the input content.

For text overlays:
- If `auto` is used, the SDK checks the text overlay input: if it is URL-safe, it uses the format `i-{input}` (plain text); otherwise, it applies Base64 encoding with the format `ie-{base64_encoded_input}`.
- You can force a specific method by setting encoding to `plain` (always use `i-{input}`) or `base64` (always use `ie-{base64}`).
- Note: In all cases, the text is percent-encoded to ensure URL safety.

For image, video, and subtitle overlays:
- The input path is processed by removing any leading/trailing slashes and replacing inner slashes with `@@` when `plain` is used.
- Similarly, if `auto` is used, the SDK determines whether to apply plain text or Base64 encoding based on the characters present.
- For explicit behavior, use `plain` or `base64` to enforce the desired encoding.

Use `auto` for most cases to let the SDK optimize encoding, and use `plain` or `base64` when a specific encoding method is required.

### Solid Color Overlay Transformations

| Option     | Description                                                                                                                                                                                                                   | Example             |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| width      | Specifies the width of the solid color overlay block (in pixels or as an arithmetic expression).                                                                                                                              | `width: 100`        |
| height     | Specifies the height of the solid color overlay block (in pixels or as an arithmetic expression).                                                                                                                             | `height: 50`        |
| radius     | Specifies the corner radius of the solid color overlay block or shape. Can be a number or `"max"` for circular/oval shapes.                                                                                                   | `radius: "max"`     |
| alpha      | Specifies the transparency level of the solid color overlay. Supports integers from 1 (most transparent) to 9 (least transparent).                                                                                            | `alpha: 5`          |
| background | Specifies the background color of the solid color overlay. Accepts an RGB hex code, an RGBA code, or a standard color name.                                                                                                   | `background: "red"` |
| gradient   | Only works if base asset is an image. Creates a linear gradient with two colors. Pass `true` for a default gradient, or provide a string for a custom gradient. [Learn more](/effects-and-enhancements#gradient---e-gradient) | `gradient: true`    |

### Text Overlay Transformations

| Option         | Description                                                                                                                                                              | Example                    |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- |
| width          | Specifies the maximum width (in pixels) of the overlaid text. The text wraps automatically, and arithmetic expressions are supported (e.g., `bw_mul_0.2` or `bh_div_2`). | `width: 400`               |
| fontSize       | Specifies the font size of the overlaid text. Accepts a numeric value or an arithmetic expression.                                                                       | `fontSize: 50`             |
| fontFamily     | Specifies the font family of the overlaid text. Choose from the supported fonts or provide a custom font.                                                                | `fontFamily: "Arial"`      |
| fontColor      | Specifies the font color of the overlaid text. Accepts an RGB hex code, an RGBA code, or a standard color name.                                                          | `fontColor: "FF0000"`      |
| innerAlignment | Specifies the inner alignment of the text when it doesn’t occupy the full width. Supported values: `left`, `right`, `center`.                                            | `innerAlignment: "center"` |
| padding        | Specifies the padding around the text overlay. Can be a single integer or multiple values separated by underscores; arithmetic expressions are accepted.                 | `padding: 10`              |
| alpha          | Specifies the transparency level of the text overlay. Accepts an integer between `1` and `9`.                                                                            | `alpha: 5`                 |
| typography     | Specifies the typography style of the text. Supported values: `b` for bold, `i` for italics, and `b_i` for bold with italics.                                            | `typography: "b"`          |
| background     | Specifies the background color of the text overlay. Accepts an RGB hex code, an RGBA code, or a color name.                                                              | `background: "red"`        |
| radius         | Specifies the corner radius of the text overlay. Accepts a numeric value or `max` for circular/oval shape.                                                               | `radius: "max"`            |
| rotation       | Specifies the rotation angle of the text overlay. Accepts a numeric value for clockwise rotation or a string prefixed with `N` for counterclockwise rotation.            | `rotation: 90`             |
| flip           | Specifies the flip option for the text overlay. Supported values: `h`, `v`, `h_v`, `v_h`.                                                                                | `flip: "h"`                |
| lineHeight     | Specifies the line height for multi-line text. Accepts a numeric value or an arithmetic expression.                                                                      | `lineHeight: 20`           |

### Subtitle Overlay Transformations

| Option      | Description                                                                                               | Example                 |
| ----------- | --------------------------------------------------------------------------------------------------------- | ----------------------- |
| background  | Specifies the subtitle background color using a standard color name, RGB color code, or RGBA color code.  | `background: "blue"`    |
| fontSize    | Sets the font size of subtitle text.                                                                      | `fontSize: 16`          |
| fontFamily  | Sets the font family of subtitle text.                                                                    | `fontFamily: "Arial"`   |
| color       | Specifies the font color of subtitle text using standard color name, RGB, or RGBA color code.             | `color: "FF0000"`       |
| typography  | Sets the typography style of subtitle text. Supported values: `b`, `i`, `b_i`.                            | `typography: "b"`       |
| fontOutline | Specifies the font outline for subtitles. Requires an outline width and color separated by an underscore. | `fontOutline: "2_blue"` |
| fontShadow  | Specifies the font shadow for subtitles. Requires shadow color and indent separated by an underscore.     | `fontShadow: "blue_2"`  |


## Video Player SDK

Looking to embed videos with advanced playback features? The **ImageKit Video Player SDK** is a powerful video player built on Video.js with enhanced capabilities like **AI-generated subtitles and chapters**, shoppable videos, playlists, and more.

### Quick Example

Install the Video Player SDK:

```bash
npm install @imagekit/video-player
```

Create a fully-featured video player component:

```html
<template>
  <div>
    <h1>Video Player Demo</h1>
    <IKVideoPlayer
      :ikOptions="ikOptions"
      :source="source"
    />
  </div>
</template>

<script setup lang="ts">
import { IKVideoPlayer } from '@imagekit/video-player/vue';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID',
  seekThumbnails: true, // Show previews on hover
  floatingWhenNotVisible: 'right', // Sticky player on scroll
  logo: {
    showLogo: true,
    logoImageUrl: 'https://your-domain.com/logo.png',
    logoOnclickUrl: 'https://your-domain.com'
  }
};

const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  info: {
    title: 'Product Demo',
    description: 'Watch our latest product in action'
  },
  
  // AI-powered features - no manual work required!
  chapters: true, // Auto-generate chapters from video content
  textTracks: [{
    autoGenerate: true, // AI speech-to-text transcription
    default: true,
    maxChars: 60,
    highlightWords: true, // Karaoke-like word highlighting
    translations: [
      { langCode: 'es', label: 'Spanish' },
      { langCode: 'fr', label: 'French' },
      { langCode: 'de', label: 'German' }
    ]
  }],
  
  transformation: [
    { width: 800, height: 600 },
    { quality: 80 }
  ]
};
</script>
```

{% callout style="info" %}
**AI-Powered Features:** The example above uses ImageKit's AI to automatically generate accurate subtitles in 50+ languages, create intelligent chapters, and enable word-level highlighting—all without manual transcription work.
{% /callout %}

[**Explore Video Player SDK →**](/video-player/overview)


---

# Source: /integration/nextjs

---
title: Next.js ImageKit SDK
description: Real-time image & video resizing, automatic optimization, and file uploading in Next.js using ImageKit.io.
---

The Next.js ImageKit SDK is a framework-specific wrapper built on top of the ImageKit JavaScript SDK. It seamlessly integrates ImageKit’s URL generation, image and video optimizations, and file upload capabilities with Next.js.

The SDK is lightweight and has first-class TypeScript support. You can view the [source code](https://github.com/imagekit-developer/imagekit-next) on Github.

## Installation and Setup

Install the Next.js SDK via npm or yarn:

```bash
npm install @imagekit/next
# or
yarn add @imagekit/next
```

Ensure your project is using Next.js version 13 or above, as this is required by the SDK.

The SDK is designed to work with both the App Router and the Pages Router. It can be used in any component, including both server components and client components. Internally, the SDK applies the `use client` directive appropriately, ensuring that you don't need to create additional wrapping boundaries.

The SDK exports `Image` and `Video` components that are drop-in replacements for Next.js native `Image` and HTML `video` elements. These components automatically handle the URL generation and transformation logic, making it easy to integrate ImageKit into your Next.js application.

```jsx
//import Image from 'next/image'
import { Image } from '@imagekit/next';

export default function Page() {
  return (
    <Image
      urlEndpoint="https://ik.imagekit.io/your_imagekit_id" // New prop
      src="/profile.png"
      width={500}
      height={500}
      alt="Picture of the author"
    />
  )
}
```

You can wrap `Image` and `Video` components inside the `ImageKitProvider` to set default values for `urlEndpoint` and `transformationPosition`. This allows you to avoid repeating these values in every component, making your code cleaner and more maintainable.

```jsx
import { Image, ImageKitProvider } from '@imagekit/next';

export default function Page() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Image
        src="/profile.png"
        width={500}
        height={500}
        alt="Picture of the author"
      />
    </ImageKitProvider>
  )
}
```

Besides `Image` and `Video`, the SDK also provides utility functions and error classes that can be used independently of the components.

#### Utility functions
- [`buildSrc`](/integration/javascript#buildsrc-parameters) – Generates URLs for images and videos based on your URL endpoint and transformation parameters.
- [`buildTransformationString`](/integration/javascript#buildtransformationstring-parameters) – Converts array of transformation objects into a URL query string.
- [`upload`](/integration/javascript#upload-parameters) – Facilitates file uploads to ImageKit with built-in support for common error handling, progress tracking, and abort functionality.

Refer to linked documentation for detailed usage of these utility functions.

#### Error classes for upload error handling
- `ImageKitInvalidRequestError` - For invalid requests.
- `ImageKitAbortError` - For aborted uploads.
- `ImageKitUploadNetworkError` - For network errors during upload.
- `ImageKitServerError` - For server-side errors.

#### Next.js Specific Components
- [`Image`](#image-component) – A drop-in replacement for Next.js Image component with ImageKit transformations. It is a wrapper around the native Next.js Image component, extending its functionality to support ImageKit-specific features.
- [`Video`](#video-component) – A lightweight wrapper for the HTML video element that automatically generates URLs for video assets with ImageKit transformations.
- `ImageKitProvider` & `ImageKitContext` – Components that let you configure default settings (such as `urlEndpoint` and `transformationPosition`) for all nested Image and Video components.

#### Type definitions
The SDK provides TypeScript definitions for all components and utility functions, ensuring type safety and autocompletion in your IDE. Exported types include `ImageKitProviderProps`, `IKImageProps`, `IKVideoProps`, `SrcOptions`, `UploadOptions`, `UploadResponse`, and `Transformation`.

## Image Component

The `Image` component is a wrapper around the native Next.js `Image` component. It allows you to use ImageKit’s URL generation and transformation capabilities while maintaining the benefits of Next.js’ built-in lazy loading, responsive images and other capabilities.
 
It supports all [Next.js Image props](https://nextjs.org/docs/app/api-reference/components/image#props) and additionally accepts the following ImageKit-specific props:

{% callout style="info" %}
**Notes**
1. If you are using the `loader` prop, the SDK silently ignores it. The SDK uses its own loader function to generate the URL for the image. You can use [`buildSrc`](/integration/javascript#buildsrc-parameters) to generate the URL manually if you need to customize the URL generation process.
2. If you pass `unoptimized=true`, the SDK will not apply any transformations or optimizations to the image. Essentially, the SDK adds a `tr=orig-true` parameter to serve the original image as it is.
3. `src` does not accept a [statically imported](https://nextjs.org/docs/app/building-your-application/optimizing/images#local-images) image file. It should be a relative or absolute path to the image.
{% /callout %}

{% table %}

- Parameter {% width="30%" %}
- Description and Example {% width="70%" %}

---

- **urlEndpoint**  
- The base URL endpoint from your [ImageKit dashboard](https://imagekit.io/dashboard/url-endpoints).
  To avoid passing this prop in every component, you can wrap your components in an `ImageKitProvider` and set the `urlEndpoint` there. In case you pass it in the component, it will override the value set in the provider.
  
  Example: `https://ik.imagekit.io/your_imagekit_id`.

---

- **src**  
  (Required)  
- A relative or absolute path to the image.

  - If a **relative path** is provided, it is appended to the `urlEndpoint`.
  - If an **absolute path** is provided, it is used as-is and the `urlEndpoint` is ignored.
  - **Do not include query parameters** directly in the `src`. Use the `queryParameters` prop instead.
  - **When using a web proxy**, you can pass the full image URL and prepend it with a `/`. For example - `/https://example.com/image.jpg`.
  - Do not pass a [statically imported image](https://nextjs.org/docs/app/building-your-application/optimizing/images#local-images).

  **Examples:**  
  Relative - `/default-image.jpg`  
  Absolute - `https://example.com/image.jpg`  
  Web Proxy - `/https://example.com/image.jpg`

---

- **transformation**
- An array of transformation objects. Each object can include properties like `width`, `height`, `rotation`, overlays, and advanced effects.  
  
  Example: `[ { width: 300, height: 300 } ]`  
  
  See all [supported transformation](#supported-transformations) options and how to [handle unsupported transformations](#handling-unsupported-transformations).

---

- **queryParameters**
- An object with additional query parameters to append to the URL.  
  Example: `{ v: 2 }`

---

- **responsive**
- A boolean that determines if responsive image functionality is enabled. By default, this is `true`, meaning that a `srcset` attribute is automatically generated for responsive images. Set it to `false` to disable this behavior and only apply explicitly defined transformations.

---

- **transformationPosition**
- Specifies whether the transformation string is included in the URL path or as a query parameter. Defaults to `"query"`.  
  Example: `"query"` or `"path"`

{% /table %}

## Video Component

The `Video` component is a lightweight wrapper around the HTML `video` element. It allows you to use ImageKit’s URL generation and transformation capabilities. It supports all [HTML video attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video#attributes) and additionally accepts the following ImageKit-specific props - `urlEndpoint`, `transformation`, `transformationPosition`, and `queryParameters`. For the definition of these props, refer to the [Image component](#image-component) section.

```js
import { Video } from '@imagekit/next';
export default function Page() {
  return (
    <Video
      urlEndpoint="https://ik.imagekit.io/your_imagekit_id"
      src="/video.mp4"
      controls
      width={500}
      height={500}
    />
  )
}
```

## Height and Width Transformations

With ImageKit, you can resize images on the fly using the `width` and `height` properties. The SDK automatically generates the appropriate URL with the specified dimensions.

```jsx
//import Image from 'next/image'
import { Image } from '@imagekit/next';

export default function Page() {
  return (
    <Image
      urlEndpoint="https://ik.imagekit.io/your_imagekit_id"
      src="/profile.png"
      width={500}
      height={500}
      alt="Picture of the author"
      transformation={[{ width: 500, height: 500 }]}
    />
  )
}
```

## Responsive Images

The `Image` component supports responsive images by default because it's built on top of the Next.js `Image` component. Check the [Next.js documentation](https://nextjs.org/docs/app/api-reference/components/image#responsive-images) for more details.

If you want to turn off responsive images, you can set `responsive` to `false`. This will disable the automatic generation of `srcset` attributes.

{% callout style="info" %}
**Note:** If you have enabled the "Restrict unnamed transformations" setting (see [Basic Security Features](/media-delivery-basic-security#restrict-unnamed-transformations)), hardcoded width/crop transformations may be added by default causing request failures. Setting `responsive` to `false` prevents these additional transformations from being applied.
{% /callout %}

## Lazy Loading Images

The `Image` component supports lazy loading by default. You can control this behavior using the [`loading`](https://nextjs.org/docs/app/api-reference/components/image#loading) prop.

By default, `loading` is set to `lazy`, which defers loading the image until it is near the viewport.

If set to `eager`, the image loads immediately.

```jsx
import { Image } from '@imagekit/next';
export default function Page() {
  return (
    <Image
      urlEndpoint="https://ik.imagekit.io/your_imagekit_id"
      src="/profile.png"
      width={500}
      height={500}
      alt="Picture of the author"
      loading="lazy" // Use "eager" to load immediately. `lazy` is the default value
    />
  )
}
```

## Lazy Loading with Placeholder

To show a placeholder while the image is loading, you can either use Next.js's built-in [`blurDataURL`](https://nextjs.org/docs/app/api-reference/components/image#blurdataurl) along with [`placeholder`](https://nextjs.org/docs/app/api-reference/components/image#placeholder) prop. But this requires you to generate a base64-encoded placeholder image beforehand. Which is not always feasible.

Alternatively, you can generate a placeholder image URL using ImageKit's [`buildSrc`](/integration/javascript#buildsrc-parameters) utility function and set it as a background image in the `style` prop. Then you can use the [`onLoad`](https://nextjs.org/docs/app/api-reference/components/image#onload) event to remove the background image (placeholder) once the image has loaded.

{% callout style="info" %}
**Good to know**  
Next.js uses the same technique by applying a background image through inline styles. However, it's important to note that with server-side rendering (SSR), the image often loads before the JavaScript bundle has executed. This delays the triggering of the `onLoad` event, which can lead to a situation where both the placeholder and the actual image are visible at the same time. The same behavior applies to the `blurDataURL` prop. You can simulate a slow network in a production build with SSR to observe this effect.
{% /callout %}

```jsx
"use client" // This component must be a client component
import { Image, buildSrc } from "@imagekit/next";
import { useState } from "react";
export default function Page() {
  const [showPlaceholder, setShowPlaceholder] = useState(true);
  return (
    <Image
      src="/default-image.jpg"
      alt="Next.js logo"
      width={400}
      height={400}
      loading="eager"
      style={showPlaceholder ? {
        backgroundImage: `url(${buildSrc({
          urlEndpoint: "https://ik.imagekit.io/ikmedia",
          src: "/default-image.jpg",
          transformation: [
            // {}, // Any other transformation you want to apply
            {
              quality: 10,
              blur: 90,
            }
          ]
        })})`,
        backgroundSize: "cover",
        backgroundRepeat: "no-repeat",
      } : {}}
      onLoad={() => {
        setShowPlaceholder(false);
      }}
    />
  )
}
```

## Lazy Loading Videos
To lazy load a video using `Video` component, you can set the `preload` attribute to `none` and specify a `poster` image by extracting a thumbnail from the video.

The [`buildSrc`](/integration/javascript#buildsrc-parameters) utility function is used to generate the thumbnail URL. It accepts the same parameters as the `Video`/`Image` component and returns a URL with the specified transformations.

Refer to the [create thumbnail](/create-video-thumbnails) documentation for detailed instructions on generating a thumbnail from a video using ImageKit.

```jsx
import { Video, buildSrc } from '@imagekit/next';
export default function Page() {
  return (
    <Video
      urlEndpoint="https://ik.imagekit.io/your_imagekit_id"
      src="/video.mp4"
      controls
      preload="none"
      poster={buildSrc({
        urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
        src: `/video.mp4/ik-thumbnail.jpg`, // Append ik-thumbnail.jpg after the video URL
      })}
    />
  )
}
```

## Chained Transformations

You can chain multiple transformations together by passing an array of transformation objects. Each object can specify different properties, such as width, height, cropping, overlays, and effects. See [chained transformations](/transformations#chained-transformations) for more details.

```jsx
import { Image } from '@imagekit/next';
export default function Page() {
  return (
    <Image
      urlEndpoint="https://ik.imagekit.io/your_imagekit_id"
      src="/profile.png"
      width={500}
      height={500}
      alt="Picture of the author"
      transformation={[
        { width: 400, height: 300 },
        { rotation: 90 }
      ]}
    />
  )
}
```

## Adding Overlays

You can add overlays to images and videos. The overlay can be a text, image, video, or subtitle.

Besides the overlay type, you can also specify the position, size, and other properties of the overlay. Check the [overlay options](#overlay-reference) for more details.

### Image Overlay

```jsx
import { Image, ImageKitProvider } from '@imagekit/next';

export default function ImageOverlayExample() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Image
        src="/background.jpg"
        alt="Background with image overlay"
        width={600}
        height={400}
        transformation={[
          { overlay: { type: "image", input: "logo.png" } }
        ]}
      />
    </ImageKitProvider>
  );
}
```

You can independently transform the overlay image by passing a transformation array inside the `overlay` object. The transformation will be applied to the overlay image only.

```jsx
import { Image, ImageKitProvider } from '@imagekit/next';
export default function ImageOverlayExample() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Image
        src="/background.jpg"
        alt="Background with image overlay"
        width={600}
        height={400}
        transformation={[
          { 
            overlay: { 
              type: "image",
              input: "logo.png",
              transformation: [{ width: 100, height: 100 }] // Transformations for the overlay image and not the background image
            } 
          }
        ]}
      />
    </ImageKitProvider>
  );
}
```

Image overlays support a wide range of transformations. Check [reference](/add-overlays-on-images#list-of-supported-image-transformations-in-image-layers) for the complete list of transformations supported on image overlays.

### Solid Color Overlay

You can add a solid color overlay to images and videos.

```jsx
import { Image, ImageKitProvider } from '@imagekit/next';
export default function ColorOverlayExample() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Image
        src="/background.jpg"
        alt="Background with solid color overlay"
        width={600}
        height={400}
        transformation={[
          { 
            overlay: { 
              type: "solidColor",
              color: "FF0000" 
            } 
          }
        ]}
      />
    </ImageKitProvider>
  );
}
```

You can also specify the width, height, and other properties of the solid color overlay. For example:

```jsx
import { Image, ImageKitProvider } from '@imagekit/next';
export default function ColorOverlayExample() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Image
        src="/background.jpg"
        alt="Background with 100x100 solid color overlay"
        width={600}
        height={400}
        transformation={[
          { 
            overlay: { 
              type: "solidColor",
              color: "FF0000",
              transformation: [
                { width: 100, height: 100 }
              ]
            } 
          }
        ]}
      />
    </ImageKitProvider>
  );
}
```

For more options related to styling the solid color overlay, check the [solid color overlay transformations](#solid-color-overlay-transformations) section.

### Text Overlay

You can add text overlays to images and videos.

```jsx
import { Image, ImageKitProvider } from '@imagekit/next';
export default function TextOverlayExample() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Image
        src="/background.jpg"
        alt="Background with text overlay"
        width={600}
        height={400}
        transformation={[
          { 
            overlay: { 
              type: "text", 
              text: "Hello, ImageKit!" 
            } 
          }
        ]}
      />
    </ImageKitProvider>
  );
}
```

You can also specify the font size, color, and other properties of the text overlay. For example:

```jsx
import { Image, ImageKitProvider } from '@imagekit/next';

export default function TextOverlayExample() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Image
        src="/background.jpg"
        alt="Background with text overlay"
        width={600}
        height={400}
        transformation={[
          { 
            overlay: { 
              type: "text", 
              text: "Hello, ImageKit!", 
              transformation: [
                { fontSize: 20, fontColor: "FF0000" } // Specify font size and color of the text
              ] 
            } 
          }
        ]}
      />
    </ImageKitProvider>
  );
}
```

Check the [text overlay transformations](#text-overlay-transformations) section for more options related to styling the text.

### Video Overlay

You can add video overlays on videos only.

```jsx
import { Video, ImageKitProvider } from '@imagekit/next';

export default function VideoOverlayExample() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Video
        src="/background.mp4"
        controls
        transformation={[
          { 
            overlay: { 
              type: "video", 
              input: "overlay.mp4" 
            } 
          }
        ]}
      />
    </ImageKitProvider>
  );
}
```

Additionally, you can specify the start and duration for the overlay video. For example:

```jsx
import { Video, ImageKitProvider } from '@imagekit/next';
export default function VideoOverlayExample() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Video
        src="/background.mp4"
        controls
        transformation={[
          { 
            overlay: { 
              type: "video", 
              input: "overlay.mp4",
              timing: { start: 5, duration: 10 } // Overlay appears at 5 seconds and lasts for 10 seconds
            } 
          }
        ]}
      />
    </ImageKitProvider>
  );
}
```

You can also independently transform the overlay video. For example, to resize the overlay video:

```jsx
import { Video, ImageKitProvider } from '@imagekit/next';
export default function VideoOverlayExample() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Video
        src="/background.mp4"
        controls
        transformation={[
          { 
            overlay: { 
              type: "video", 
              input: "overlay.mp4",
              transformation: [
                { width: 100, height: 100 } // Transformations for the overlay video and not the background video
              ] 
            } 
          }
        ]}
      />
    </ImageKitProvider>
  );
}
```

All supported [video transformations](/video-transformation) can also be applied to overlay videos.

If you're overlaying an image on a base video, refer to [this list](/add-overlays-on-videos#list-of-transformations-supported-on-image-overlay) for all the transformations supported on image overlays.

### Subtitle Overlay

You can add subtitle overlays on videos.

```jsx
import { Video, ImageKitProvider } from '@imagekit/next';

export default function SubtitleOverlayExample() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Video
        src="/background.mp4"
        controls
        transformation={[
          { 
            overlay: { 
              type: "subtitle", 
              input: "subtitle.srt" 
            } 
          }
        ]}
      />
    </ImageKitProvider>
  );
}
```

The subtitle overlay can be styled with various properties such as font size, color, and outline. See the [Subtitle Overlay Transformations](#subtitle-overlay-transformations) section for all styling options.

## Background Removal Using AI

```jsx
import { Image, ImageKitProvider } from '@imagekit/next';

export default function BackgroundRemovalExample() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Image
        src="/photo.jpg"
        alt="Photo with background removal"
        width={500}
        height={500}
        transformation={[
          { aiRemoveBackground: true }
        ]}
      />
    </ImageKitProvider>
  );
}
```

ImageKit supports multiple AI-powered transformations, like upscaling, generative fill, and more. More examples:

```jsx
import { Image, ImageKitProvider } from '@imagekit/next';
export default function AIDropShadow() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Image
        src="/photo.jpg"
        alt="Photo with AI drop shadow"
        width={500}
        height={500}
        transformation={[
          { aiDropShadow: true }
        ]}
      />
    </ImageKitProvider>
  );
}
```

Upscaling example:

```jsx
import { Image, ImageKitProvider } from '@imagekit/next';
export default function AIUpscaleExample() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Image
        src="/photo.jpg"
        alt="Photo with AI upscaling"
        width={500}
        height={500}
        transformation={[
          { aiUpscale: true }
        ]}
      />
    </ImageKitProvider>
  );
}
```

## Arithmetic Expressions

You can use arithmetic expressions to dynamically compute transformation values. For example, to set the width to half of the original image width:

```jsx
import { Image, ImageKitProvider } from '@imagekit/next';

export default function ArithmeticExample() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Image
        src="/photo.jpg"
        alt="Photo with arithmetic width"
        width={300}
        height={200}
        transformation={[
          { width: "iw_div_2" }
        ]}
      />
    </ImageKitProvider>
  );
}
```

Check out the [Arithmetic Expressions](/arithmetic-expressions-in-transformations) reference for more examples and details.

## Uploading Files

The Next.js SDK exports a utility function, `.upload`, which enables you to upload files to ImageKit. This `upload()` function leverages the [Upload V1 API](/api-reference/upload-file/upload-file), accepting an options object and returning a promise that resolves with the upload response.

The SDK automatically converts certain parameters into JSON strings, as required by the API. If a parameter is not explicitly supported by the SDK, it is included in the request as-is. For a complete list of parameters and expected formats, refer to the API documentation.

### upload() Parameters

The `upload()` function accepts a JSON object with the following parameters:

{% table %}

- Option {% width="30%" %}
- Description and Example {% width="70%" %}

---

- **file**  
  (Required)  
- The file content to be uploaded. Accepts binary data, a base64-encoded string, or a URL. Typically used with a File or Blob in the browser. Example: `file: fileInput.files[0]`

---

- **fileName**  
  (Required)  
- The name to assign to the uploaded file. Supports alphanumeric characters, dot, underscore, and dash. Any other character is replaced with `_`. Example: `fileName: "myImage.jpg"`

---

- **signature**  
  (Required)  
- The HMAC-SHA1 digest of the concatenation of "token + expire". The signing key is your ImageKit private API key. Must be computed on the server side. Example: `signature: "generated_signature"`

---

- **token**  
  (Required)  
- A unique value to identify and prevent replays. Typically a UUID (e.g., version 4). Example: `token: "unique_upload_token"`
  
  Check the [signature generation](#generating-authentication-parameters) section for more details on how to generate this value.

---

- **expire**  
  (Required)  
- A Unix timestamp in seconds, less than 1 hour in the future. Example: `expire: 1616161616`
  
  Check the [signature generation](#generating-authentication-parameters) section for more details on how to generate this value.

---

- **publicKey**  
  (Required)
- The public API key for your ImageKit account. This is used to identify the account making the upload request. Example: `publicKey: "your_public_api_key"`
  
  Check the [signature generation](#generating-authentication-parameters) section for more details on how to generate this value.

---

- **onProgress**
- A callback function to track the upload progress. It receives an event object with `loaded` and `total` properties. Example: `onProgress: (event) => console.log(event.loaded, event.total)`
  This is useful for showing upload progress to the user.

---
- **abortSignal**
- An optional `AbortSignal` object to abort the upload request. If the signal is already aborted, the upload will fail immediately.
  You can create an `AbortController` instance and pass its signal to the `upload()` function.

---

- **useUniqueFileName**
- Boolean flag to automatically generate a unique filename if set to true. Defaults to true. If false, the image is uploaded with the provided filename, replacing any existing file with the same name. Example: `useUniqueFileName: true`

---

- **folder**
- The folder path where the file will be stored, e.g., "/images/folder/". If the path doesn't exist, it is created on-the-fly. Example: `folder: "/images/uploads"`

---

- **isPrivateFile**
- Boolean to mark the file as private, restricting access to the original file URL. A private file requires signed URLs or named transformations for access. Defaults to false. Example: `isPrivateFile: false`

---

- **tags**
- Optionally set tags on the uploaded file. Can be a comma-separated string or an array of tags. Example: `tags: "summer,holiday"` or `tags: ["summer","holiday"]`

---

- **customCoordinates**
- A string in "x,y,width,height" format that defines the region of interest in an image (top-left coords and area size). Example: `customCoordinates: "10,10,100,100"`

---

- **responseFields**
- A comma-separated or array-based set of fields to return in the upload response. Example: `responseFields: "tags,customCoordinates"`

---

- **extensions**
- An array of extension objects to apply to the image, e.g., background removal, auto-tagging, etc. Example: `extensions: [{ name: "auto-tagging" }]`

---

- **webhookUrl**
- A webhook URL to receive the final status of any pending extensions once they've completed processing. Example: `webhookUrl: "https://example.com/webhook"`

---

- **overwriteFile**
- Defaults to true. If false, and "useUniqueFileName" is also false, the API immediately fails if a file with the same name/folder already exists. Example: `overwriteFile: true`

---

- **overwriteAITags**
- Defaults to true. If true, and an existing file is found at the same location, its AITags are removed. Set to false to keep existing AITags. Example: `overwriteAITags: true`

---

- **overwriteTags**
- Defaults to true. If no tags are specified in the request, existing tags are removed from overwritten files. Setting to false has no effect if the request includes tags. Example: `overwriteTags: true`

---

- **overwriteCustomMetadata**
- Defaults to true. If no customMetadata is specified in the request, existing customMetadata is removed from overwritten files. Setting to false has no effect if the request specifies customMetadata. Example: `overwriteCustomMetadata: true`

---

- **customMetadata**
- A stringified JSON or an object containing custom metadata fields to store with the file. Custom metadata fields must be pre-defined in your ImageKit configuration. Example: `customMetadata: {author: "John Doe"}`

---

- **transformation**
- Defines pre and post transformations to be applied to the file during upload. The SDK enforces certain validation rules for pre/post transformations. Example: `transformation: { pre: "w-200,h-200", post: [...] }`

---

- **xhr**
- An optional XMLHttpRequest instance for the upload. The SDK merges it with its own logic to handle progress events, etc. Example: `xhr: new XMLHttpRequest()`

---

- **checks**
- A string specifying the checks to be performed server-side before uploading to the media library, e.g., size or mime type checks. Example: `checks: "file.size' < '1MB'"`

{% /table %}


## Upload Example and Error Handling

The `.upload` function expects the following mandatory parameters:

- **`file` and `fileName`** – The file to be uploaded and the name you want to assign to it. The `file` value can be a `File` object, a base64-encoded string, or a URL.
- **Authentication parameters** – `token`, `signature`, `expire`, and `publicKey`.

Authentication is essential for secure file uploads from the browser. You should **never expose your private API key** in client-side code. Instead, generate these one-time authentication parameters on the **server side** and pass them to the client.

To simplify this process, the Next.js SDK provides a utility function: `getUploadAuthParams`. You can use this in your API route to generate the required authentication parameters. It takes your [private](/api-keys#private-key) and [public](/api-keys#public-key) keys as input and returns the `token`, `expire`, and `signature`.

### Upload Flow Overview

Here’s how the upload process using the SDK works:

1. **Client Request for Auth Parameters**  
   The client component calls an API route to fetch the authentication parameters.  
   You can implement your own application logic within this route to authenticate the user.  
   After that, use `getUploadAuthParams` to generate the upload credentials.

2. **File Upload**  
   Once the client has the auth parameters, it can call the `.upload` function with the necessary data.

### Generating Authentication Parameters

Create an API route at either:

- `app/api/upload-auth/route.ts` (for **App Router**)
- `pages/api/upload-auth.ts` (for **Pages Router**)

In this route, use the `getUploadAuthParams` function provided by `@imagekit/next/server` to generate the required upload parameters.

This function takes your private and public keys and returns the `token`, `expire`, and `signature`. You can also implement custom logic in this route to ensure that only **authenticated or authorized** users can request upload credentials.

{% linetabs %}
{% linetab title="App router" %}
```js
// File: app/api/upload-auth/route.ts
import { getUploadAuthParams } from "@imagekit/next/server"

export async function GET() {
    // Your application logic to authenticate the user
    // For example, you can check if the user is logged in or has the necessary permissions
    // If the user is not authenticated, you can return an error response

    const { token, expire, signature } = getUploadAuthParams({
        privateKey: process.env.IMAGEKIT_PRIVATE_KEY as string, // Never expose this on client side
        publicKey: process.env.IMAGEKIT_PUBLIC_KEY as string,
        // expire: 30 * 60, // Optional, controls the expiry time of the token in seconds, maximum 1 hour in the future
        // token: "random-token", // Optional, a unique token for request
    })

    return Response.json({ token, expire, signature, publicKey: process.env.IMAGEKIT_PUBLIC_KEY })
}
```
{% /linetab %}
{% linetab title="Pages router" %}
```js
// File: pages/api/upload-auth.ts
import { getUploadAuthParams } from "@imagekit/next/server"
import type { NextApiRequest, NextApiResponse } from 'next'

export default function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  // Your application logic to authenticate the user
  // For example, you can check if the user is logged in or has the necessary permissions
  // If the user is not authenticated, you can return an error response

  const { token, expire, signature } = getUploadAuthParams({
    privateKey: process.env.IMAGEKIT_PRIVATE_KEY as string, // Never expose this on client side
    publicKey: process.env.IMAGEKIT_PUBLIC_KEY as string,
    // expire: 30 * 60, // Optional, controls the expiry time of the token in seconds, maximum 1 hour in the future
    // token: "random-token", // Optional, a unique token for request
  })

  res.status(200).json({ token, expire, signature, publicKey: process.env.IMAGEKIT_PUBLIC_KEY })
}
```
{% /linetab %}
{% /linetabs %}

Now your client-side code can call this API route to retrieve the upload parameters.

The example below demonstrates how to use the `.upload` function in a client component to upload a file, including error handling for various upload scenarios. You can copy and paste this code into your client component and customize it as needed.

```js
"use client" // This component must be a client component

import {
    ImageKitAbortError,
    ImageKitInvalidRequestError,
    ImageKitServerError,
    ImageKitUploadNetworkError,
    upload,
} from "@imagekit/next";
import { useRef, useState } from "react";

// UploadExample component demonstrates file uploading using ImageKit's Next.js SDK.
const UploadExample = () => {
    // State to keep track of the current upload progress (percentage)
    const [progress, setProgress] = useState(0);

    // Create a ref for the file input element to access its files easily
    const fileInputRef = useRef<HTMLInputElement>(null);

    // Create an AbortController instance to provide an option to cancel the upload if needed.
    const abortController = new AbortController();

    /**
     * Authenticates and retrieves the necessary upload credentials from the server.
     *
     * This function calls the authentication API endpoint to receive upload parameters like signature,
     * expire time, token, and publicKey.
     *
     * @returns {Promise<{signature: string, expire: string, token: string, publicKey: string}>} The authentication parameters.
     * @throws {Error} Throws an error if the authentication request fails.
     */
    const authenticator = async () => {
        try {
            // Perform the request to the upload authentication endpoint.
            const response = await fetch("/api/upload-auth");
            if (!response.ok) {
                // If the server response is not successful, extract the error text for debugging.
                const errorText = await response.text();
                throw new Error(`Request failed with status ${response.status}: ${errorText}`);
            }

            // Parse and destructure the response JSON for upload credentials.
            const data = await response.json();
            const { signature, expire, token, publicKey } = data;
            return { signature, expire, token, publicKey };
        } catch (error) {
            // Log the original error for debugging before rethrowing a new error.
            console.error("Authentication error:", error);
            throw new Error("Authentication request failed");
        }
    };

    /**
     * Handles the file upload process.
     *
     * This function:
     * - Validates file selection.
     * - Retrieves upload authentication credentials.
     * - Initiates the file upload via the ImageKit SDK.
     * - Updates the upload progress.
     * - Catches and processes errors accordingly.
     */
    const handleUpload = async () => {
        // Access the file input element using the ref
        const fileInput = fileInputRef.current;
        if (!fileInput || !fileInput.files || fileInput.files.length === 0) {
            alert("Please select a file to upload");
            return;
        }

        // Extract the first file from the file input
        const file = fileInput.files[0];

        // Retrieve authentication parameters for the upload.
        let authParams;
        try {
            authParams = await authenticator();
        } catch (authError) {
            console.error("Failed to authenticate for upload:", authError);
            return;
        }
        const { signature, expire, token, publicKey } = authParams;

        // Call the ImageKit SDK upload function with the required parameters and callbacks.
        try {
            const uploadResponse = await upload({
                // Authentication parameters
                expire,
                token,
                signature,
                publicKey,
                file,
                fileName: file.name, // Optionally set a custom file name
                // Progress callback to update upload progress state
                onProgress: (event) => {
                    setProgress((event.loaded / event.total) * 100);
                },
                // Abort signal to allow cancellation of the upload if needed.
                abortSignal: abortController.signal,
            });
            console.log("Upload response:", uploadResponse);
        } catch (error) {
            // Handle specific error types provided by the ImageKit SDK.
            if (error instanceof ImageKitAbortError) {
                console.error("Upload aborted:", error.reason);
            } else if (error instanceof ImageKitInvalidRequestError) {
                console.error("Invalid request:", error.message);
            } else if (error instanceof ImageKitUploadNetworkError) {
                console.error("Network error:", error.message);
            } else if (error instanceof ImageKitServerError) {
                console.error("Server error:", error.message);
            } else {
                // Handle any other errors that may occur.
                console.error("Upload error:", error);
            }
        }
    };

    return (
        <>
            {/* File input element using React ref */}
            <input type="file" ref={fileInputRef} />
            {/* Button to trigger the upload process */}
            <button type="button" onClick={handleUpload}>
                Upload file
            </button>
            <br />
            {/* Display the current upload progress */}
            Upload progress: <progress value={progress} max={100}></progress>
        </>
    );
};

export default UploadExample;
```

## Supported Transformations

The SDK gives a name to each transformation parameter (e.g. `height` maps to `h`, `width` maps to `w`). If the property does not match any of the following supported options, it is added as is in the URL.

If you want to generate transformations without any modifications, use the `raw` parameter. For example, the SDK doesn't provide a nice way to write [conditional transformations](/conditional-transformations), so you can use the `raw` parameter to add them as is.

Check [transformation documentation](/transformations) for a complete reference on all transformations supported by ImageKit.

| Transformation Name        | URL Parameter                                                                                  |
| -------------------------- | ---------------------------------------------------------------------------------------------- |
| width                      | w                                                                                              |
| height                     | h                                                                                              |
| aspectRatio                | ar                                                                                             |
| quality                    | q                                                                                              |
| aiRemoveBackground         | e-bgremove (ImageKit powered)                                                                  |
| aiRemoveBackgroundExternal | e-removedotbg (Using third party)                                                              |
| aiEdit                     | e-edit                                                                                         |
| aiUpscale                  | e-upscale                                                                                      |
| aiRetouch                  | e-retouch                                                                                      |
| aiVariation                | e-genvar                                                                                       |
| aiDropShadow               | e-dropshadow                                                                                   |
| aiChangeBackground         | e-changebg                                                                                     |
| colorize                   | e-colorize                                                                                     |
| gradient                   | e-gradient                                                                                     |
| distort                    | e-distort                                                                                      |
| crop                       | c                                                                                              |
| cropMode                   | cm                                                                                             |
| x                          | x                                                                                              |
| y                          | y                                                                                              |
| xCenter                    | xc                                                                                             |
| yCenter                    | yc                                                                                             |
| focus                      | fo                                                                                             |
| format                     | f                                                                                              |
| radius                     | r                                                                                              |
| background                 | bg                                                                                             |
| border                     | b                                                                                              |
| rotation                   | rt                                                                                             |
| blur                       | bl                                                                                             |
| named                      | n                                                                                              |
| dpr                        | dpr                                                                                            |
| progressive                | pr                                                                                             |
| lossless                   | lo                                                                                             |
| trim                       | t                                                                                              |
| metadata                   | md                                                                                             |
| colorProfile               | cp                                                                                             |
| defaultImage               | di                                                                                             |
| original                   | orig                                                                                           |
| videoCodec                 | vc                                                                                             |
| audioCodec                 | ac                                                                                             |
| grayscale                  | e-grayscale                                                                                    |
| contrastStretch            | e-contrast                                                                                     |
| shadow                     | e-shadow                                                                                       |
| sharpen                    | e-sharpen                                                                                      |
| unsharpMask                | e-usm                                                                                          |
| gradient                   | e-gradient                                                                                     |
| flip                       | fl                                                                                             |
| opacity                    | o                                                                                              |
| zoom                       | z                                                                                              |
| page                       | pg                                                                                             |
| startOffset                | so                                                                                             |
| endOffset                  | eo                                                                                             |
| duration                   | du                                                                                             |
| streamingResolutions       | sr                                                                                             |
| colorReplace               | cr                                                                                             |
| overlay                    | Generates the correct layer syntax for image, video, text, subtitle, and solid color overlays. |
| raw                        | The string provided in raw will be added in the URL as is.                                     |


## Handling Unsupported Transformations

If you specify a transformation parameter that is not explicitly supported by the SDK, it is added “as-is” in the generated URL. This provides flexibility for using new or custom transformations without waiting for an SDK update. However add `@ts-ignore` to avoid TypeScript errors for unsupported transformations, or add transformation as a string in the `raw` parameter.

For example:

```jsx
import { Image, ImageKitProvider } from '@imagekit/next';

export default function UnsupportedTransformationExample() {
  return (
    <ImageKitProvider urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
      <Image
        src="/photo.jpg"
        alt="Photo with unsupported transformation"
        // @ts-ignore
        transformation={[
          { unsupportedTransformation: "value" }
        ]}
      />
    </ImageKitProvider>
  );
}
// Output: https://ik.imagekit.io/your_imagekit_id/photo.jpg?tr=unsupportedTransformation-value
```

## Overlay Reference

This SDK provides `overlay` as a transformation parameter. The overlay can be a text, image, video, subtitle, or solid color.

Overlays in ImageKit are applied using layers, allowing you to stack multiple overlays on top of each other. Each overlay can be styled and positioned independently. For more details, refer to the [layer documentation](/transformations#overlay-using-layers).

The SDK automatically generates the correct layer syntax for image, video, text, subtitle, and solid color overlays. You can also specify the overlay position, size, and other properties.

The table below outlines the available overlay configuration options:

{% table %}

- Option {% width="30%" %}
- Description and Example {% width="70%" %}

---

- **type**  
  (Required)
- Specifies the type of overlay. Supported values: `text`, `image`, `video`, `subtitle`, `solidColor`. Example: `type: "text"`

---

- **text**  
  (Required for text overlays)
- The text content to display. Example: `text: "ImageKit"`

---

- **input**  
  (Required for image, video, or subtitle overlays)
- Relative path to the overlay asset. Example: `input: "logo.png"` or `input: "overlay-video.mp4"`

---

- **color**  
  (Required for solidColor overlays)
- RGB/RGBA hex code or color name for the overlay color. Example: `color: "FF0000"`

---

- **encoding**
- Accepted values: `auto`, `plain`, `base64`. [Check this](#encoding-options) for more details. Example: `encoding: "auto"`

---

- **transformation**
- An array of transformation objects to style the overlay independently of the base asset. Each overlay type has its own set of supported transformations.
  - For example, for text overlays, you can specify `fontSize`, `fontColor`, `background`, etc. Example: `transformation: [{ fontSize: 20, fontColor: "FF0000" }]`. Check out the [text overlay transformations](#text-overlay-transformations) section for more options.
  - For image overlays, you can specify `width`, `height`, `radius`, etc. Example: `transformation: [{ width: 100, height: 100 }]`. Check [reference](/add-overlays-on-images#list-of-supported-image-transformations-in-image-layers) for complete list of transformations supported on image overlays.
  - For video overlays, you can specify `width`, `height`, `rotation`, etc. Example: `transformation: [{ width: 100, height: 100 }]`. Check [reference](/add-overlays-on-videos#list-of-transformations-supported-on-image-overlay) for complete list of transformations supported on video overlays.
  - For subtitle overlays, you can specify `fontSize`, `fontColor`, `background`, etc. Example: `transformation: [{ fontSize: 20, fontColor: "FF0000" }]`. Check out the [subtitle overlay transformations](#subtitle-overlay-transformations) section for more options.
  - For solid color overlays, you can specify `width`, `height`, `radius`, etc. Example: `transformation: [{ width: 100, height: 100 }]`. Check out the [solid color overlay transformations](#solid-color-overlay-transformations) section for more options.


---

- **layerMode**
- Controls how the layer blends with the base image or underlying content. 
  - By default, layers completely cover the base image beneath them. Layer modes change this behavior. 
  - Supported values: `multiply`, `displace`, `cutout`, `cutter`, Check [reference](/add-overlays-on-images#layer-modes)

---

- **position**
- Sets the overlay’s position relative to the base asset. Accepts an object with `x`, `y`, or `focus`. Example: `position: { x: 10, y: 20 }` or `position: { focus: "center" }`

---

- **timing**
- (For video base) Specifies when the overlay appears using `start`, `duration`, and `end` (in seconds); if both `duration` and `end` are set, `duration` is ignored. Example: `timing: { start: 5, duration: 10 }`

{% /table %}

### Encoding Options

Overlay encoding options define how the overlay input is converted for URL construction. When set to `auto`, the SDK automatically determines whether to use plain text or Base64 encoding based on the input content.

For text overlays:
- If `auto` is used, the SDK checks the text overlay input: if it is URL-safe, it uses the format `i-{input}` (plain text); otherwise, it applies Base64 encoding with the format `ie-{base64_encoded_input}`.
- You can force a specific method by setting encoding to `plain` (always use `i-{input}`) or `base64` (always use `ie-{base64}`).
- Note: In all cases, the text is percent-encoded to ensure URL safety.

For image, video, and subtitle overlays:
- The input path is processed by removing any leading/trailing slashes and replacing inner slashes with `@@` when `plain` is used.
- Similarly, if `auto` is used, the SDK determines whether to apply plain text or Base64 encoding based on the characters present.
- For explicit behavior, use `plain` or `base64` to enforce the desired encoding.

Use `auto` for most cases to let the SDK optimize encoding, and use `plain` or `base64` when a specific encoding method is required.

### Solid Color Overlay Transformations

| Option     | Description                                                                                                                                                                                                                   | Example             |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| width      | Specifies the width of the solid color overlay block (in pixels or as an arithmetic expression).                                                                                                                              | `width: 100`        |
| height     | Specifies the height of the solid color overlay block (in pixels or as an arithmetic expression).                                                                                                                             | `height: 50`        |
| radius     | Specifies the corner radius of the solid color overlay block or shape. Can be a number or `"max"` for circular/oval shapes.                                                                                                   | `radius: "max"`     |
| alpha      | Specifies the transparency level of the solid color overlay. Supports integers from 1 (most transparent) to 9 (least transparent).                                                                                            | `alpha: 5`          |
| background | Specifies the background color of the solid color overlay. Accepts an RGB hex code, an RGBA code, or a standard color name.                                                                                                   | `background: "red"` |
| gradient   | Only works if base asset is an image. Creates a linear gradient with two colors. Pass `true` for a default gradient, or provide a string for a custom gradient. [Learn more](/effects-and-enhancements#gradient---e-gradient) | `gradient: true`    |

### Text Overlay Transformations

| Option         | Description                                                                                                                                                              | Example                    |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- |
| width          | Specifies the maximum width (in pixels) of the overlaid text. The text wraps automatically, and arithmetic expressions are supported (e.g., `bw_mul_0.2` or `bh_div_2`). | `width: 400`               |
| fontSize       | Specifies the font size of the overlaid text. Accepts a numeric value or an arithmetic expression.                                                                       | `fontSize: 50`             |
| fontFamily     | Specifies the font family of the overlaid text. Choose from the supported fonts or provide a custom font.                                                                | `fontFamily: "Arial"`      |
| fontColor      | Specifies the font color of the overlaid text. Accepts an RGB hex code, an RGBA code, or a standard color name.                                                          | `fontColor: "FF0000"`      |
| innerAlignment | Specifies the inner alignment of the text when it doesn’t occupy the full width. Supported values: `left`, `right`, `center`.                                            | `innerAlignment: "center"` |
| padding        | Specifies the padding around the text overlay. Can be a single integer or multiple values separated by underscores; arithmetic expressions are accepted.                 | `padding: 10`              |
| alpha          | Specifies the transparency level of the text overlay. Accepts an integer between `1` and `9`.                                                                            | `alpha: 5`                 |
| typography     | Specifies the typography style of the text. Supported values: `b` for bold, `i` for italics, and `b_i` for bold with italics.                                            | `typography: "b"`          |
| background     | Specifies the background color of the text overlay. Accepts an RGB hex code, an RGBA code, or a color name.                                                              | `background: "red"`        |
| radius         | Specifies the corner radius of the text overlay. Accepts a numeric value or `max` for circular/oval shape.                                                               | `radius: "max"`            |
| rotation       | Specifies the rotation angle of the text overlay. Accepts a numeric value for clockwise rotation or a string prefixed with `N` for counterclockwise rotation.            | `rotation: 90`             |
| flip           | Specifies the flip option for the text overlay. Supported values: `h`, `v`, `h_v`, `v_h`.                                                                                | `flip: "h"`                |
| lineHeight     | Specifies the line height for multi-line text. Accepts a numeric value or an arithmetic expression.                                                                      | `lineHeight: 20`           |

### Subtitle Overlay Transformations

| Option      | Description                                                                                               | Example                 |
| ----------- | --------------------------------------------------------------------------------------------------------- | ----------------------- |
| background  | Specifies the subtitle background color using a standard color name, RGB color code, or RGBA color code.  | `background: "blue"`    |
| fontSize    | Sets the font size of subtitle text.                                                                      | `fontSize: 16`          |
| fontFamily  | Sets the font family of subtitle text.                                                                    | `fontFamily: "Arial"`   |
| color       | Specifies the font color of subtitle text using standard color name, RGB, or RGBA color code.             | `color: "FF0000"`       |
| typography  | Sets the typography style of subtitle text. Supported values: `b`, `i`, `b_i`.                            | `typography: "b"`       |
| fontOutline | Specifies the font outline for subtitles. Requires an outline width and color separated by an underscore. | `fontOutline: "2_blue"` |
| fontShadow  | Specifies the font shadow for subtitles. Requires shadow color and indent separated by an underscore.     | `fontShadow: "blue_2"`  |


---

# Source: /integration/astro

---
title: Astro ImageKit SDK
description: Real-time image & video resizing, automatic optimization, and file uploading in Astro using ImageKit.io.
---

Astro's built-in image pipeline runs every image through a local sharp process at build time (or through your server's `/_image` endpoint at request time). That works for a handful of static assets, but it falls apart once you have a large media library, user-uploaded content, or videos: builds get slow, your server does the resizing on every request, and there is no CDN in front of the output.

The Astro ImageKit SDK fixes this by registering a custom **image service** that emits ImageKit URLs instead. You keep using Astro's native `<Image />`, `<Picture />`, and `getImage()` from `astro:assets` exactly as before, but the rendered URLs now point at `ik.imagekit.io`, with transformations, responsive `srcset`, format conversion, and CDN caching handled by ImageKit. Local imports keep flowing through sharp, so existing pages don't break.

The SDK also ships a `<Video>` component, an `<OgImage>` helper for social cards, and a server-side helper for client-side uploads. It works with Astro 3.2 and above. You can view the [source code](https://github.com/imagekit-developer/imagekit-astro) on GitHub.

## How it works

The image service is host-aware. For each image, it inspects the `src` and routes the request to one of two backends:

1. **ImageKit fast path.** When `src` is an ImageKit URL (your `urlEndpoint` host, any `additionalEndpoints` host, or a bare/relative path like `"folder/photo.jpg"`), the service builds an ImageKit URL with the requested transformations and points the browser straight at `https://ik.imagekit.io/...`. There is no `/_image` round trip, just a CDN-cached URL with `?tr=...` parameters.
2. **Sharp fallback.** When `src` is a local Astro asset (`import` of an image, or markdown `![](../foo.jpg)`) or an absolute URL on a non-ImageKit host, the service delegates to Astro's bundled sharp service, exactly as if you had no integration installed.

You can drop the integration into an existing Astro project without breaking any local-asset usage.

## Installation and Setup

Install the Astro SDK via npm, pnpm, or yarn:

```bash
npm install @imagekit/astro
# or
pnpm add @imagekit/astro
# or
yarn add @imagekit/astro
```

If you also call utilities from `@imagekit/javascript` directly (e.g. `buildSrc`, `upload`), install it explicitly so strict package managers (e.g. pnpm) can resolve it:

```bash
npm install @imagekit/javascript
```

### Configure the Integration

Add the ImageKit integration to your Astro config:

```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import imagekit from '@imagekit/astro/integration';

export default defineConfig({
  integrations: [imagekit()],
});
```

Provide your ImageKit URL endpoint either via the `IMAGEKIT_URL_ENDPOINT` environment variable in `.env`:

```bash
IMAGEKIT_URL_ENDPOINT=https://ik.imagekit.io/your_imagekit_id
```

or by passing it directly to the integration:

```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import imagekit from '@imagekit/astro/integration';

export default defineConfig({
  integrations: [
    imagekit({
      urlEndpoint: 'https://ik.imagekit.io/your_imagekit_id',
    }),
  ],
});
```

{% callout style="info" %}
Get your URL endpoint from the [ImageKit dashboard](https://imagekit.io/dashboard/url-endpoints).
{% /callout %}

The integration sets `image.service` to `@imagekit/astro/image-service`. ImageKit URLs are returned directly from the image service and skip Astro's `/_image` endpoint, so you don't need to add ImageKit hosts to `image.domains` or `image.remotePatterns`.

Full list of integration options:

{% table %}

- Option {% width="30%" %}
- Description {% width="70%" %}

---

- **urlEndpoint**
- The ImageKit URL endpoint. If omitted, falls back to the `IMAGEKIT_URL_ENDPOINT` environment variable.

---

- **transformationPosition**
- Where to place transformations in the URL: `"query"` (default, `?tr=...`) or `"path"` (`/tr:.../`).

---

- **additionalEndpoints**
- Extra ImageKit URL endpoints (other accounts or custom domains). Hostnames listed here are recognized by the image service so absolute URLs on those hosts also get ImageKit transformations applied.

  Example: `additionalEndpoints: ['https://ik.imagekit.io/another_account']`

{% /table %}

### TypeScript support

The integration uses Astro's [`injectTypes()`](https://docs.astro.build/en/reference/integrations-reference/#injecttypes-option) helper to register ImageKit-specific props (`urlEndpoint`, `transformation`, `queryParameters`, `transformationPosition`) on Astro's `Astro.CustomImageProps` namespace. You get full autocomplete and type-checking on `<Image />`, `<Picture />`, and `getImage()` for these props.

Run `astro sync` (or start the dev server) once after installing so Astro picks up the injected types.

## Image Component

There is no separate `Image` component in `@imagekit/astro`. Continue using Astro's built-in [`<Image />`](https://docs.astro.build/en/reference/modules/astro-assets/#image-) (and `<Picture />`) from `astro:assets`. Once the integration is installed, every render flows through the ImageKit image service.

In addition to all standard [Astro Image props](https://docs.astro.build/en/reference/modules/astro-assets/#image--1), the integration adds the following ImageKit-specific props:

{% callout style="info" %}
**Notes**
1. `src` should be a relative path (appended to `urlEndpoint`) or an absolute ImageKit URL. Local statically-imported images and absolute URLs on non-ImageKit hosts are routed through Astro's sharp service.
2. The component-level `width` and `height` control the rendered HTML dimensions. To force a server-side resize, pass them inside `transformation`.
{% /callout %}

{% table %}

- Parameter {% width="30%" %}
- Description and Example {% width="70%" %}

---

- **urlEndpoint**
- The base URL endpoint from your [ImageKit dashboard](https://imagekit.io/dashboard/url-endpoints). Overrides the value passed to `imagekit({ urlEndpoint })` in `astro.config.mjs` and the `IMAGEKIT_URL_ENDPOINT` env var for this image only.

  Example: `https://ik.imagekit.io/your_imagekit_id`

---

- **src**  
  (Required)
- A relative or absolute path to the image.

  - If a **relative path** is provided, it is appended to the `urlEndpoint`.
  - If an **absolute path** on an ImageKit host is provided, it is used as-is and the `urlEndpoint` is ignored.
  - **Do not include query parameters** directly in the `src`. Use the `queryParameters` prop instead.
  - **When using a Web Proxy**, you can pass the full source URL prepended with a `/`, e.g. `/https://example.com/image.jpg`.

  **Examples:**  
  Relative: `/default-image.jpg`  
  Absolute: `https://ik.imagekit.io/demo/default-image.jpg`  
  Web Proxy: `/https://example.com/image.jpg`

---

- **transformation**
- An array of transformation objects. Each object can include properties like `width`, `height`, `rotation`, overlays, and advanced effects.

  Example: `[{ width: 300, height: 300 }]`

  See all [supported transformations](#supported-transformations).

---

- **queryParameters**
- An object with additional query parameters to append to the URL.

  Example: `{ v: 2 }`

---

- **transformationPosition**
- Specifies whether the transformation string is included in the URL path or as a query parameter. Defaults to `"query"`.

  Example: `"query"` or `"path"`

{% /table %}

### Basic Usage

```jsx
---
import { Image } from 'astro:assets';
---

<Image
  src="/default-image.jpg"
  alt="A sample image"
  width={400}
  height={300}
/>
```

When `IMAGEKIT_URL_ENDPOINT` is configured (or you pass `urlEndpoint` to `imagekit()` in `astro.config.mjs`), `urlEndpoint` does not need to be set per image. To override it for a single image:

```jsx
---
import { Image } from 'astro:assets';
---

<Image
  urlEndpoint="https://ik.imagekit.io/another_account"
  src="/default-image.jpg"
  alt="A sample image"
  width={400}
  height={300}
/>
```

### Image with Transformations

```jsx
---
import { Image } from 'astro:assets';
---

<Image
  src="/default-image.jpg"
  alt="Resized image"
  width={600}
  height={400}
  transformation={[{ width: 600, height: 400, focus: 'auto' }]}
/>
```

### Astro-Specific Props

All Astro `<Image />` props work as documented:

```jsx
---
import { Image, Picture } from 'astro:assets';
---

<!-- Quality presets (low | mid | high | max) map to ImageKit q-25/50/75/100 -->
<Image src="/photo.jpg" alt="" width={800} height={600} quality="high" />

<!-- Density-based srcset -->
<Image src="/icon.png" alt="" width={100} height={100} densities={[1.5, 2]} />

<!-- Explicit widths with sizes -->
<Image
  src="/photo.jpg"
  alt=""
  widths={[240, 540, 720]}
  sizes="(max-width: 360px) 240px, (max-width: 720px) 540px, 720px"
  width={720}
  height={480}
/>

<!-- Layout modes (Astro 5+) -->
<Image src="/hero.jpg" alt="" width={1200} height={630} layout="full-width" />

<!-- Loading and priority -->
<Image src="/hero.jpg" alt="" width={1200} height={630} loading="eager" fetchpriority="high" />

<!-- <Picture> works the same way -->
<Picture src="/photo.jpg" alt="" widths={[400, 800, 1200]} formats={['avif', 'webp']} />
```

{% callout style="info" %}
Astro's `format` prop is honored and emitted as `f-<format>` on the final transformation chain step, so `<Picture />` correctly requests one URL per format (`f-avif`, `f-webp`, etc.) and `<Image format="...">` works as expected. When `format` is unset, no `f-` parameter is emitted and ImageKit's default `f-auto` negotiation applies. Note: imported local assets cause Astro to auto-fill `format` from the file extension — to force `f-auto` in that case, override via `transformation: [{ format: 'auto' }]`.

Astro's `fit` and `position` props are still ignored — pass `crop`, `focus`, etc. via the `transformation` prop instead.
{% /callout %}

### Delivering Public Media via Web Proxy

If your source files already live on a public URL (for example, assets on another domain), you can use ImageKit Web Proxy and still use Astro's `<Image />` for transformations and optimization. Set up a Web Proxy origin and attach it to your URL endpoint by following the [Web Proxy guide](/integration/web-proxy), then pass the original public URL as part of `src` (prepended with a `/`):

```jsx
<Image
  src="/https://www.example.com/images/hero.jpg"
  alt="Hero image from web proxy"
  width={1200}
  height={630}
  transformation={[{ width: 1200, height: 630 }]}
/>
```

With `IMAGEKIT_URL_ENDPOINT=https://ik.imagekit.io/your_imagekit_id`, the generated URL pattern is:

```text
https://ik.imagekit.io/your_imagekit_id/https://www.example.com/images/hero.jpg?tr=w-1200,h-630
```

You can also use path-style transformations by setting `transformationPosition="path"`:

```jsx
<Image
  src="/https://www.example.com/images/banner.jpg"
  alt="Banner from web proxy"
  width={900}
  height={400}
  transformation={[{ width: 900, height: 400 }]}
  transformationPosition="path"
/>
```

## Video Component

The `Video` component wraps the HTML `<video>` element and generates ImageKit-optimized video URLs with transformations. It supports all [HTML video attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video#attributes) and also accepts the ImageKit-specific props: `urlEndpoint`, `transformation`, `transformationPosition`, and `queryParameters`. For the definition of these props, refer to the [Image component](#image-component) section.

```jsx
---
import { Video } from '@imagekit/astro';
---

<Video
  src="/sample-video.mp4"
  width={640}
  height={360}
  controls
/>
```

{% callout style="info" %}
The component-level `width` and `height` are HTML attributes only. To resize the video on ImageKit's side, pass them via the `transformation` prop.
{% /callout %}

### Video with Transformations

```jsx
<Video
  src="/sample-video.mp4"
  transformation={[{ width: 640, height: 360 }]}
  width={640}
  height={360}
  controls
/>
```

### Video with HTML Attributes

```jsx
<Video
  src="/sample-video.mp4"
  width={640}
  height={360}
  controls
  autoplay
  loop
  muted
  preload="none"
  poster="https://ik.imagekit.io/your_imagekit_id/video-thumbnail.jpg"
/>
```

### Lazy Loading Videos

To lazy load a video, set `preload` to `none` and specify a `poster` image. You can use [`buildSrc`](/integration/javascript#buildsrc-parameters) from `@imagekit/javascript` to generate a thumbnail URL from the video:

```jsx
---
import { Video } from '@imagekit/astro';
import { buildSrc } from '@imagekit/javascript';

const posterUrl = buildSrc({
  urlEndpoint: 'https://ik.imagekit.io/your_imagekit_id',
  src: '/video.mp4/ik-thumbnail.jpg',
});
---

<Video
  src="/video.mp4"
  controls
  preload="none"
  poster={posterUrl}
  width={640}
  height={360}
/>
```

Refer to the [create thumbnail](/create-video-thumbnails) documentation for more details on generating a thumbnail from a video.

## Height and Width Transformations

Resize images on the fly using the `width` and `height` transformation properties:

```jsx
---
import { Image } from 'astro:assets';
---

<Image
  src="/profile.png"
  alt="Profile picture"
  width={500}
  height={500}
  transformation={[{ width: 500, height: 500 }]}
/>
```

{% callout style="info" %}
The `width` and `height` props on the component control the rendered HTML dimensions. The `width` and `height` inside `transformation` control the ImageKit server-side resize. These can differ. For example, you might want a 1200px server resize but a 600px rendered width for retina displays.
{% /callout %}

## Responsive Images

Astro's `<Image />` and `<Picture />` already provide responsive image generation, and the ImageKit image service plugs into it. Use the standard Astro props to control how `srcset` and `sizes` are generated:

```jsx
<!-- Density-based srcset for fixed-size elements like icons or logos -->
<Image src="/icon.png" alt="App icon" width={100} height={100} densities={[1, 1.5, 2]} />

<!-- Explicit widths + sizes for fluid images -->
<Image
  src="/photo.jpg"
  alt="Gallery image"
  width={800}
  height={600}
  widths={[300, 600, 900, 1200]}
  sizes="(max-width: 640px) 300px, (max-width: 1024px) 600px, 900px"
/>

<!-- Layout-based responsive (Astro 5+) -->
<Image src="/hero.jpg" alt="" width={1920} height={1080} layout="full-width" />
<Image src="/article.jpg" alt="" width={800} height={600} layout="constrained" />
```

Each generated `srcset` entry is rewritten through ImageKit. To prevent upscaling beyond the source asset, the service appends a final `c-at_max` step (along with the requested width and quality) to every URL.

{% callout style="info" %}
If you have enabled the "Restrict unnamed transformations" setting (see [Basic Security Features](/media-delivery-basic-security#restrict-unnamed-transformations)), the auto-generated width/crop transformations may cause request failures. Either disable that setting, or render images without responsive variants by setting both `widths` and `densities` to `undefined` (or use a layout that does not generate variants).
{% /callout %}

## Lazy Loading Images

Astro's `<Image />` lazy-loads images by default. You can control this behaviour using the `loading` and `fetchpriority` attributes:

```jsx
<!-- Default: lazy loading -->
<Image src="/profile.png" alt="Lazy loaded" width={500} height={500} />

<!-- Eager loading for above-the-fold images -->
<Image
  src="/hero.jpg"
  alt="Hero image"
  width={1200}
  height={630}
  loading="eager"
  fetchpriority="high"
  decoding="sync"
/>
```

## Lazy Loading with Placeholder

You can show a low-quality, blurred placeholder while the full image loads by using ImageKit's `buildSrc` utility to generate a placeholder URL and setting it as a `background-image` on the `<Image>` element. Then use the `onload` attribute to remove the background image once the actual image has loaded.

```jsx
---
import { Image } from 'astro:assets';
import { buildSrc } from '@imagekit/javascript';

const placeholderUrl = buildSrc({
  urlEndpoint: 'https://ik.imagekit.io/your_imagekit_id',
  src: '/default-image.jpg',
  transformation: [{ quality: 10, blur: 90 }],
});

const placeholderStyle = `background-image: url(${placeholderUrl}); background-size: cover; background-repeat: no-repeat; background-position: center;`;
---

<Image
  src="/default-image.jpg"
  alt="Image with placeholder"
  width={400}
  height={400}
  loading="lazy"
  style={placeholderStyle}
  onload="this.style.backgroundImage='none'"
/>
```

## Chained Transformations

You can chain multiple transformations by passing an array of transformation objects. Each object in the array creates a separate [chained transformation](/transformations#chained-transformations) step:

```jsx
---
import { Image } from 'astro:assets';
---

<Image
  src="/photo.jpg"
  alt="Chained transformations"
  width={400}
  height={300}
  transformation={[
    { width: 400, height: 300 },  // First: resize
    { rotation: 90 },             // Then: rotate
  ]}
/>
```

## Adding Overlays

You can add overlays to images and videos. The overlay can be text, image, video, subtitle, or solid color.

### Image Overlay

```jsx
<Image
  src="/background.jpg"
  alt="Background with image overlay"
  width={600}
  height={400}
  transformation={[
    { overlay: { type: 'image', input: 'logo.png' } }
  ]}
/>
```

With independent overlay transformations:

```jsx
<Image
  src="/background.jpg"
  alt="Background with resized overlay"
  width={600}
  height={400}
  transformation={[
    {
      overlay: {
        type: 'image',
        input: 'logo.png',
        transformation: [{ width: 100, height: 100 }],
      },
    },
  ]}
/>
```

Image overlays support a wide range of transformations. Check [reference](/add-overlays-on-images#list-of-supported-image-transformations-in-image-layers) for the complete list of transformations supported on image overlays.

### Text Overlay

```jsx
<Image
  src="/background.jpg"
  alt="Background with text"
  width={600}
  height={400}
  transformation={[
    {
      overlay: {
        type: 'text',
        text: 'Hello, ImageKit!',
        transformation: [{ fontSize: 20, fontColor: 'FF0000' }],
      },
    },
  ]}
/>
```

Check the [text overlay transformations](#text-overlay-transformations) section for more options related to styling the text.

### Solid Color Overlay

```jsx
<Image
  src="/background.jpg"
  alt="Background with color overlay"
  width={600}
  height={400}
  transformation={[
    {
      overlay: {
        type: 'solidColor',
        color: 'FF0000',
        transformation: [{ width: 100, height: 100 }],
      },
    },
  ]}
/>
```

For more options related to styling the solid color overlay, check the [solid color overlay transformations](#solid-color-overlay-transformations) section.

### Video Overlay (on videos)

```jsx
<Video
  src="/background.mp4"
  controls
  transformation={[
    {
      overlay: {
        type: 'video',
        input: 'overlay.mp4',
        timing: { start: 5, duration: 10 },
      },
    },
  ]}
/>
```

All supported [video transformations](/video-transformation) can also be applied to overlay videos. If you're overlaying an image on a base video, refer to [this list](/add-overlays-on-videos#list-of-transformations-supported-on-image-overlay) for all the transformations supported on image overlays.

### Subtitle Overlay (on videos)

```jsx
<Video
  src="/background.mp4"
  controls
  transformation={[
    {
      overlay: {
        type: 'subtitle',
        input: 'subtitle.srt',
      },
    },
  ]}
/>
```

The subtitle overlay can be styled with various properties such as font size, color, and outline. See the [subtitle overlay transformations](#subtitle-overlay-transformations) section for all styling options.

For more details on overlay options, positioning, encoding, and styling, see the [overlay reference](#overlay-reference) section.

## Background Removal Using AI

```jsx
<Image
  src="/photo.jpg"
  alt="Background removed"
  width={500}
  height={500}
  transformation={[{ aiRemoveBackground: true }]}
/>
```

ImageKit supports multiple AI-powered transformations including upscaling, drop shadow, generative fill, and more:

```jsx
<!-- AI Drop Shadow -->
<Image
  src="/product.jpg"
  alt="Product with drop shadow"
  width={500}
  height={500}
  transformation={[{ aiDropShadow: true }]}
/>

<!-- AI Upscale -->
<Image
  src="/small-photo.jpg"
  alt="Upscaled photo"
  width={500}
  height={500}
  transformation={[{ aiUpscale: true }]}
/>
```

## Arithmetic Expressions

You can use arithmetic expressions to dynamically compute transformation values:

```jsx
<Image
  src="/photo.jpg"
  alt="Half-width image"
  width={300}
  height={200}
  transformation={[{ width: 'iw_div_2' }]}
/>
```

Check out the [Arithmetic Expressions](/arithmetic-expressions-in-transformations) reference for more examples.

## OG Image Component

The `OgImage` component renders OpenGraph and Twitter Card `<meta>` tags pointing at an ImageKit-optimized image. Use it inside the `<head>` of your layout. Only `src` and a title (one of `title`, `ogTitle`, or `twitterTitle`) are required. `width` and `height` default to `1200` × `630` and are automatically applied as an ImageKit transformation on top of any extra `transformation` you pass.


```jsx
---
import { OgImage } from '@imagekit/astro';
---

<html>
  <head>
    <OgImage
      src="/og-banner.jpg"
      title="My Page Title"
      description="Preview description for social cards"
      alt="OG image description"
    />
  </head>
  <body>...</body>
</html>
```

### Generated Meta Tags

The component emits the following tags (when applicable):

```html
<meta property="og:title" content="..." />
<meta property="og:description" content="..." />
<meta property="og:type" content="website" />
<meta property="og:image" content="..." />
<meta property="og:image:secure_url" content="..." />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta property="og:image:alt" content="..." />
<meta name="twitter:title" content="..." />
<meta name="twitter:description" content="..." />
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:image" content="..." />
<meta name="twitter:image:alt" content="..." />
```

ImageKit serves the optimal format automatically based on the requesting client (no `format` option needed).

### Component Props

{% table %}

- Option {% width="30%" %}
- Description {% width="70%" %}

---

- **src** (Required)
- Relative path or absolute ImageKit URL for the OG image.

---

- **title**
- Shared title for both OG and Twitter tags. At least one of `title`, `ogTitle`, or `twitterTitle` is required.

---

- **ogTitle** / **twitterTitle**
- Platform-specific title overrides. Falls back to `title`.

---

- **description**
- Shared description. Can be overridden with `ogDescription` or `twitterDescription`.

---

- **ogDescription** / **twitterDescription**
- Platform-specific description overrides. Falls back to `description`.

---

- **type**
- OpenGraph object type. Default: `"website"`. Common values: `website`, `article`, `book`, `profile`.

---

- **twitterCard**
- Twitter card type. Default: `summary_large_image`. Options: `summary`, `summary_large_image`, `app`, `player`.

---

- **alt**
- Alt text emitted as both `og:image:alt` and `twitter:image:alt`.

---

- **urlEndpoint**
- Overrides the integration / env var URL endpoint for this OG image only.

---

- **transformation**
- Optional array of ImageKit transformations to apply to the OG image. The component always appends a final `{ width, height }` step (using the values below), so you only need to pass `transformation` for additional effects (overlays, filters, etc.).

---

- **queryParameters**
- Additional query parameters to append to the OG image URL.

---

- **transformationPosition**
- `"path"` or `"query"` (default).

---

- **width** / **height**
- OG image dimensions. Defaults: `1200` × `630`. Used both for the `og:image:width` / `og:image:height` meta tags and as the final ImageKit resize transformation.

{% /table %}

### `getOgImageUrl` Helper

If you prefer to render meta tags manually, use the `getOgImageUrl` helper to build just the URL:

```jsx
---
import { getOgImageUrl } from '@imagekit/astro';

const ogImage = getOgImageUrl({
  src: '/og-banner.jpg',
  transformation: [{ width: 1200, height: 630 }],
});
---

<meta property="og:image" content={ogImage} />
```

## Uploading Files

Client-side uploads are powered by the `upload` function from `@imagekit/javascript` (install it directly). The function leverages the [Upload V1 API](/api-reference/upload-file/upload-file), accepting an options object and returning a promise that resolves with the upload response.

For the complete list of upload parameters, the response shape, and SDK validation rules, refer to the [JavaScript SDK upload reference](/integration/javascript#upload-parameters).

The Astro SDK provides a server-side helper, `getUploadAuthParams`, exported from `@imagekit/astro/server`, to generate the authentication parameters (`signature`, `token`, `expire`) required by the upload endpoint. Use it inside an Astro API route, never on the client.

### Upload Flow Overview

1. **Client requests auth parameters.** Your client-side code calls an Astro API endpoint to fetch the authentication parameters. You can implement your own application logic in this endpoint to authenticate the user before generating credentials.
2. **File upload.** Once the client has the auth parameters, it calls `upload()` with the file and credentials.

### Generating Authentication Parameters

Add your ImageKit keys to `.env`:

```bash
IMAGEKIT_PRIVATE_KEY=your_private_key
IMAGEKIT_PUBLIC_KEY=your_public_key
```

Create a server-side API endpoint in Astro that returns the auth parameters. Make sure to add an [adapter](https://docs.astro.build/en/guides/on-demand-rendering/) to your Astro project and render the upload endpoint on demand.

```jsx
// src/pages/api/upload-auth.ts
import type { APIRoute } from 'astro';
import { getUploadAuthParams } from '@imagekit/astro/server';

export const prerender = false;

export const GET: APIRoute = async () => {
  // Your application logic to authenticate the user
  // For example, you can check if the user is logged in or has the necessary permissions
  // If the user is not authenticated, you can return an error response

  const authParams = getUploadAuthParams({
    privateKey: import.meta.env.IMAGEKIT_PRIVATE_KEY, // Never expose this on client side
    publicKey: import.meta.env.IMAGEKIT_PUBLIC_KEY,
    // expire: 30 * 60, // Optional. Expiry in seconds; max 1 hour in the future. Default: 30 minutes.
    // token: 'random-token', // Optional. Auto-generated UUID if omitted.
  });

  return new Response(JSON.stringify(authParams), {
    status: 200,
    headers: { 'Content-Type': 'application/json' },
  });
};
```

`getUploadAuthParams` accepts these parameters:

{% table %}

- Parameter {% width="20%" %}
- Type {% width="15%" %}
- Required {% width="15%" %}
- Description {% width="50%" %}

---

- **privateKey**
- `string`
- Yes
- Your ImageKit private key.

---

- **publicKey**
- `string`
- Yes
- Your ImageKit public key.

---

- **token**
- `string`
- No
- Custom token. Auto-generated UUID if omitted.

---

- **expire**
- `number`
- No
- Expiry timestamp in seconds. Defaults to 30 minutes from now.

{% /table %}

It returns an object with `token`, `signature`, `expire`, and `publicKey`.

{% callout style="alert" %}
`getUploadAuthParams` must only be called on the server. Never expose your **private key** to the client.
{% /callout %}

### Upload Example and Error Handling

The example below demonstrates how to use the `upload` function on the client to upload a file, including error handling for the various upload scenarios. Copy and paste this code into a `.astro` page and customize as needed.

```html
---
// src/pages/upload.astro
---

<html>
  <body>
    <input type="file" id="file-input" />
    <button id="upload-btn">Upload</button>
    <div>Upload progress: <progress id="upload-progress" value="0" max="100"></progress></div>
    <pre id="result"></pre>

    <script>
      import {
        upload,
        ImageKitAbortError,
        ImageKitInvalidRequestError,
        ImageKitServerError,
        ImageKitUploadNetworkError,
      } from '@imagekit/javascript';

      const fileInput = document.getElementById('file-input') as HTMLInputElement;
      const uploadBtn = document.getElementById('upload-btn') as HTMLButtonElement;
      const progressBar = document.getElementById('upload-progress') as HTMLProgressElement;
      const result = document.getElementById('result') as HTMLPreElement;

      // Create an AbortController instance to provide an option to cancel the upload if needed.
      const abortController = new AbortController();

      /**
       * Authenticates and retrieves the necessary upload credentials from the server.
       */
      const authenticator = async () => {
        const response = await fetch('/api/upload-auth');
        if (!response.ok) {
          const errorText = await response.text();
          throw new Error(`Request failed with status ${response.status}: ${errorText}`);
        }
        const data = await response.json();
        const { signature, expire, token, publicKey } = data;
        return { signature, expire, token, publicKey };
      };

      uploadBtn.addEventListener('click', async () => {
        const file = fileInput.files?.[0];
        if (!file) {
          alert('Please select a file to upload');
          return;
        }

        // Retrieve authentication parameters for the upload.
        let authParams;
        try {
          authParams = await authenticator();
        } catch (authError) {
          console.error('Failed to authenticate for upload:', authError);
          return;
        }
        const { signature, expire, token, publicKey } = authParams;

        try {
          const response = await upload({
            // Authentication parameters
            expire,
            token,
            signature,
            publicKey,
            file,
            fileName: file.name,
            // Progress callback to update upload progress
            onProgress: (event) => {
              progressBar.value = (event.loaded / event.total) * 100;
            },
            // Abort signal to allow cancellation of the upload if needed.
            abortSignal: abortController.signal,
          });
          console.log('Upload response:', response);
          result.textContent = JSON.stringify(response, null, 2);
        } catch (error) {
          // Handle specific error types provided by the ImageKit SDK.
          if (error instanceof ImageKitAbortError) {
            console.error('Upload aborted:', error.reason);
          } else if (error instanceof ImageKitInvalidRequestError) {
            console.error('Invalid request:', error.message);
          } else if (error instanceof ImageKitUploadNetworkError) {
            console.error('Network error:', error.message);
          } else if (error instanceof ImageKitServerError) {
            console.error('Server error:', error.message);
          } else {
            console.error('Upload error:', error);
          }
        }
      });
    </script>
  </body>
</html>
```

## Loading Images from Your ImageKit Media Library

You can use [Astro Content Collections](https://docs.astro.build/en/guides/content-collections/) together with the [`@imagekit/nodejs`](https://www.npmjs.com/package/@imagekit/nodejs) SDK to power gallery and listing pages directly from your ImageKit Media Library, without hand-maintaining a list of URLs.

Install the Node SDK as a dev dependency (it's only used at build time):

```bash
npm install -D @imagekit/nodejs
```

Define a collection backed by `client.assets.list()`. The Node SDK returns an array of `File | Folder` objects directly, so pass `type: 'file'` to exclude folders and `fileType: 'image'` to limit results to images. Shape each entry as `{ id, ...data }`. Astro's content layer treats the top-level `id` as the entry key and validates everything else against your `schema`:

```jsx
// src/content.config.ts
import { defineCollection } from 'astro:content';
import { z } from 'astro/zod';
import ImageKit from '@imagekit/nodejs';
import type { Files } from '@imagekit/nodejs/resources/files/files';

const client = new ImageKit({
  privateKey: import.meta.env.IMAGEKIT_PRIVATE_KEY,
});

const gallery = defineCollection({
  loader: async () => {
    const assets = await client.assets.list({
      type: 'file',       // exclude folders
      fileType: 'image',  // only image files
      skip: 0,
      limit: 50,
    });

    return assets
      .filter((asset): asset is Files.File =>
        asset.type === 'file' && !!asset.fileId && !!asset.url
      )
      .map((asset) => ({
        id: asset.fileId ?? '',
        url: asset.url ?? '',
        width: asset.width ?? 0,
        height: asset.height ?? 0,
        name: asset.name ?? '',
        tags: asset.tags ?? [],
      }));
  },
  schema: z.object({
    url: z.string().url(),
    width: z.number(),
    height: z.number(),
    name: z.string(),
    tags: z.array(z.string()),
  }),
});

export const collections = { gallery };
```

After adding the collection, run `astro sync` (or start the dev server) so Astro generates the collection types used by `getCollection()`.

Render with `<Image>` from `astro:assets`. The integration's image service generates the ImageKit CDN URL with the correct transformations:

```jsx
---
import { Image } from 'astro:assets';
import { getCollection } from 'astro:content';

const photos = await getCollection('gallery');
---

{photos.map(({ data }) => (
  <Image
    src={data.url}
    width={data.width}
    height={data.height}
    alt={data.name}
    transformation={[{ width: 400, height: 300, focus: 'auto' }]}
  />
))}
```

{% callout style="warning" %}
Keep your `privateKey` in a server-only env var (e.g. `IMAGEKIT_PRIVATE_KEY` in `.env`, never prefixed with `PUBLIC_`). Collection loaders run at build time (or in SSR endpoints), never in the browser.
{% /callout %}

## Supported Transformations

The SDK gives a name to each transformation parameter (e.g. `height` maps to `h`, `width` maps to `w`). If the property does not match any of the following supported options, it is added as is in the URL.

If you want to generate transformations without any modifications, use the `raw` parameter. For example, the SDK doesn't provide a nice way to write [conditional transformations](/conditional-transformations), so you can use the `raw` parameter to add them as is.

Check [transformation documentation](/transformations) for a complete reference on all transformations supported by ImageKit.

| Transformation Name        | URL Parameter                                                                                  |
| -------------------------- | ---------------------------------------------------------------------------------------------- |
| width                      | w                                                                                              |
| height                     | h                                                                                              |
| aspectRatio                | ar                                                                                             |
| quality                    | q                                                                                              |
| aiRemoveBackground         | e-bgremove (ImageKit powered)                                                                  |
| aiRemoveBackgroundExternal | e-removedotbg (Using third party)                                                              |
| aiEdit                     | e-edit                                                                                         |
| aiUpscale                  | e-upscale                                                                                      |
| aiRetouch                  | e-retouch                                                                                      |
| aiVariation                | e-genvar                                                                                       |
| aiDropShadow               | e-dropshadow                                                                                   |
| aiChangeBackground         | e-changebg                                                                                     |
| colorize                   | e-colorize                                                                                     |
| gradient                   | e-gradient                                                                                     |
| distort                    | e-distort                                                                                      |
| crop                       | c                                                                                              |
| cropMode                   | cm                                                                                             |
| x                          | x                                                                                              |
| y                          | y                                                                                              |
| xCenter                    | xc                                                                                             |
| yCenter                    | yc                                                                                             |
| focus                      | fo                                                                                             |
| format                     | f                                                                                              |
| radius                     | r                                                                                              |
| background                 | bg                                                                                             |
| border                     | b                                                                                              |
| rotation                   | rt                                                                                             |
| blur                       | bl                                                                                             |
| named                      | n                                                                                              |
| dpr                        | dpr                                                                                            |
| progressive                | pr                                                                                             |
| lossless                   | lo                                                                                             |
| trim                       | t                                                                                              |
| metadata                   | md                                                                                             |
| colorProfile               | cp                                                                                             |
| defaultImage               | di                                                                                             |
| original                   | orig                                                                                           |
| videoCodec                 | vc                                                                                             |
| audioCodec                 | ac                                                                                             |
| grayscale                  | e-grayscale                                                                                    |
| contrastStretch            | e-contrast                                                                                     |
| shadow                     | e-shadow                                                                                       |
| sharpen                    | e-sharpen                                                                                      |
| unsharpMask                | e-usm                                                                                          |
| gradient                   | e-gradient                                                                                     |
| flip                       | fl                                                                                             |
| opacity                    | o                                                                                              |
| zoom                       | z                                                                                              |
| page                       | pg                                                                                             |
| startOffset                | so                                                                                             |
| endOffset                  | eo                                                                                             |
| duration                   | du                                                                                             |
| streamingResolutions       | sr                                                                                             |
| colorReplace               | cr                                                                                             |
| overlay                    | Generates the correct layer syntax for image, video, text, subtitle, and solid color overlays. |
| raw                        | The string provided in raw will be added in the URL as is.                                     |


## Handling Unsupported Transformations

If you specify a transformation parameter that is not explicitly supported by the SDK, it is added as-is in the generated URL. This provides flexibility for using new or custom transformations without waiting for an SDK update. Add `@ts-ignore` to avoid TypeScript errors, or use the `raw` parameter.

```jsx
<Image
  src="/photo.jpg"
  alt="Custom transformation"
  width={500}
  height={500}
  transformation={[
    // @ts-ignore
    { unsupportedTransformation: 'value' },
  ]}
/>
```

Or use the `raw` parameter:

```jsx
<Image
  src="/photo.jpg"
  alt="Raw transformation"
  width={500}
  height={500}
  transformation={[
    { raw: 'unsupportedTransformation-value' },
  ]}
/>
```

## Overlay Reference

This SDK provides `overlay` as a transformation parameter. The overlay can be a text, image, video, subtitle, or solid color.

Overlays in ImageKit are applied using layers, allowing you to stack multiple overlays on top of each other. Each overlay can be styled and positioned independently. For more details, refer to the [layer documentation](/transformations#overlay-using-layers).

The SDK automatically generates the correct layer syntax for image, video, text, subtitle, and solid color overlays. You can also specify the overlay position, size, and other properties.

The table below outlines the available overlay configuration options:

{% table %}

- Option {% width="30%" %}
- Description and Example {% width="70%" %}

---

- **type**  
  (Required)
- Specifies the type of overlay. Supported values: `text`, `image`, `video`, `subtitle`, `solidColor`. Example: `type: "text"`

---

- **text**  
  (Required for text overlays)
- The text content to display. Example: `text: "ImageKit"`

---

- **input**  
  (Required for image, video, or subtitle overlays)
- Relative path to the overlay asset. Example: `input: "logo.png"` or `input: "overlay-video.mp4"`

---

- **color**  
  (Required for solidColor overlays)
- RGB/RGBA hex code or color name for the overlay color. Example: `color: "FF0000"`

---

- **encoding**
- Accepted values: `auto`, `plain`, `base64`. [Check this](#encoding-options) for more details. Example: `encoding: "auto"`

---

- **transformation**
- An array of transformation objects to style the overlay independently of the base asset. Each overlay type has its own set of supported transformations.
  - For example, for text overlays, you can specify `fontSize`, `fontColor`, `background`, etc. Example: `transformation: [{ fontSize: 20, fontColor: "FF0000" }]`. Check out the [text overlay transformations](#text-overlay-transformations) section for more options.
  - For image overlays, you can specify `width`, `height`, `radius`, etc. Example: `transformation: [{ width: 100, height: 100 }]`. Check [reference](/add-overlays-on-images#list-of-supported-image-transformations-in-image-layers) for complete list of transformations supported on image overlays.
  - For video overlays, you can specify `width`, `height`, `rotation`, etc. Example: `transformation: [{ width: 100, height: 100 }]`. Check [reference](/add-overlays-on-videos#list-of-transformations-supported-on-image-overlay) for complete list of transformations supported on video overlays.
  - For subtitle overlays, you can specify `fontSize`, `fontColor`, `background`, etc. Example: `transformation: [{ fontSize: 20, fontColor: "FF0000" }]`. Check out the [subtitle overlay transformations](#subtitle-overlay-transformations) section for more options.
  - For solid color overlays, you can specify `width`, `height`, `radius`, etc. Example: `transformation: [{ width: 100, height: 100 }]`. Check out the [solid color overlay transformations](#solid-color-overlay-transformations) section for more options.


---

- **layerMode**
- Controls how the layer blends with the base image or underlying content. 
  - By default, layers completely cover the base image beneath them. Layer modes change this behavior. 
  - Supported values: `multiply`, `displace`, `cutout`, `cutter`, Check [reference](/add-overlays-on-images#layer-modes)

---

- **position**
- Sets the overlay’s position relative to the base asset. Accepts an object with `x`, `y`, or `focus`. Example: `position: { x: 10, y: 20 }` or `position: { focus: "center" }`

---

- **timing**
- (For video base) Specifies when the overlay appears using `start`, `duration`, and `end` (in seconds); if both `duration` and `end` are set, `duration` is ignored. Example: `timing: { start: 5, duration: 10 }`

{% /table %}

### Encoding Options

Overlay encoding options define how the overlay input is converted for URL construction. When set to `auto`, the SDK automatically determines whether to use plain text or Base64 encoding based on the input content.

For text overlays:
- If `auto` is used, the SDK checks the text overlay input: if it is URL-safe, it uses the format `i-{input}` (plain text); otherwise, it applies Base64 encoding with the format `ie-{base64_encoded_input}`.
- You can force a specific method by setting encoding to `plain` (always use `i-{input}`) or `base64` (always use `ie-{base64}`).
- Note: In all cases, the text is percent-encoded to ensure URL safety.

For image, video, and subtitle overlays:
- The input path is processed by removing any leading/trailing slashes and replacing inner slashes with `@@` when `plain` is used.
- Similarly, if `auto` is used, the SDK determines whether to apply plain text or Base64 encoding based on the characters present.
- For explicit behavior, use `plain` or `base64` to enforce the desired encoding.

Use `auto` for most cases to let the SDK optimize encoding, and use `plain` or `base64` when a specific encoding method is required.

### Solid Color Overlay Transformations

| Option     | Description                                                                                                                                                                                                                   | Example             |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| width      | Specifies the width of the solid color overlay block (in pixels or as an arithmetic expression).                                                                                                                              | `width: 100`        |
| height     | Specifies the height of the solid color overlay block (in pixels or as an arithmetic expression).                                                                                                                             | `height: 50`        |
| radius     | Specifies the corner radius of the solid color overlay block or shape. Can be a number or `"max"` for circular/oval shapes.                                                                                                   | `radius: "max"`     |
| alpha      | Specifies the transparency level of the solid color overlay. Supports integers from 1 (most transparent) to 9 (least transparent).                                                                                            | `alpha: 5`          |
| background | Specifies the background color of the solid color overlay. Accepts an RGB hex code, an RGBA code, or a standard color name.                                                                                                   | `background: "red"` |
| gradient   | Only works if base asset is an image. Creates a linear gradient with two colors. Pass `true` for a default gradient, or provide a string for a custom gradient. [Learn more](/effects-and-enhancements#gradient---e-gradient) | `gradient: true`    |

### Text Overlay Transformations

| Option         | Description                                                                                                                                                              | Example                    |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- |
| width          | Specifies the maximum width (in pixels) of the overlaid text. The text wraps automatically, and arithmetic expressions are supported (e.g., `bw_mul_0.2` or `bh_div_2`). | `width: 400`               |
| fontSize       | Specifies the font size of the overlaid text. Accepts a numeric value or an arithmetic expression.                                                                       | `fontSize: 50`             |
| fontFamily     | Specifies the font family of the overlaid text. Choose from the supported fonts or provide a custom font.                                                                | `fontFamily: "Arial"`      |
| fontColor      | Specifies the font color of the overlaid text. Accepts an RGB hex code, an RGBA code, or a standard color name.                                                          | `fontColor: "FF0000"`      |
| innerAlignment | Specifies the inner alignment of the text when it doesn’t occupy the full width. Supported values: `left`, `right`, `center`.                                            | `innerAlignment: "center"` |
| padding        | Specifies the padding around the text overlay. Can be a single integer or multiple values separated by underscores; arithmetic expressions are accepted.                 | `padding: 10`              |
| alpha          | Specifies the transparency level of the text overlay. Accepts an integer between `1` and `9`.                                                                            | `alpha: 5`                 |
| typography     | Specifies the typography style of the text. Supported values: `b` for bold, `i` for italics, and `b_i` for bold with italics.                                            | `typography: "b"`          |
| background     | Specifies the background color of the text overlay. Accepts an RGB hex code, an RGBA code, or a color name.                                                              | `background: "red"`        |
| radius         | Specifies the corner radius of the text overlay. Accepts a numeric value or `max` for circular/oval shape.                                                               | `radius: "max"`            |
| rotation       | Specifies the rotation angle of the text overlay. Accepts a numeric value for clockwise rotation or a string prefixed with `N` for counterclockwise rotation.            | `rotation: 90`             |
| flip           | Specifies the flip option for the text overlay. Supported values: `h`, `v`, `h_v`, `v_h`.                                                                                | `flip: "h"`                |
| lineHeight     | Specifies the line height for multi-line text. Accepts a numeric value or an arithmetic expression.                                                                      | `lineHeight: 20`           |

### Subtitle Overlay Transformations

| Option      | Description                                                                                               | Example                 |
| ----------- | --------------------------------------------------------------------------------------------------------- | ----------------------- |
| background  | Specifies the subtitle background color using a standard color name, RGB color code, or RGBA color code.  | `background: "blue"`    |
| fontSize    | Sets the font size of subtitle text.                                                                      | `fontSize: 16`          |
| fontFamily  | Sets the font family of subtitle text.                                                                    | `fontFamily: "Arial"`   |
| color       | Specifies the font color of subtitle text using standard color name, RGB, or RGBA color code.             | `color: "FF0000"`       |
| typography  | Sets the typography style of subtitle text. Supported values: `b`, `i`, `b_i`.                            | `typography: "b"`       |
| fontOutline | Specifies the font outline for subtitles. Requires an outline width and color separated by an underscore. | `fontOutline: "2_blue"` |
| fontShadow  | Specifies the font shadow for subtitles. Requires shadow color and indent separated by an underscore.     | `fontShadow: "blue_2"`  |


## Video Player SDK

Looking to embed videos with advanced playback features? The **ImageKit Video Player SDK** is a powerful video player built on Video.js with enhanced capabilities like **AI-generated subtitles and chapters**, shoppable videos, playlists, and more.

### Quick Example

Install the Video Player SDK:

```bash
npm install @imagekit/video-player
```

Create a fully-featured video player component:

```html
---
import { IKVideoPlayer } from '@imagekit/video-player/astro';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID',
  seekThumbnails: true, // Show previews on hover
  floatingWhenNotVisible: 'right', // Sticky player on scroll
  logo: {
    showLogo: true,
    logoImageUrl: 'https://your-domain.com/logo.png',
    logoOnclickUrl: 'https://your-domain.com'
  }
};

const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  info: {
    title: 'Product Demo',
    description: 'Watch our latest product in action'
  },

  // AI-powered features
  chapters: true, // Auto-generate chapters from video content
  textTracks: [{
    autoGenerate: true, // AI speech-to-text transcription
    default: true,
    maxChars: 60,
    highlightWords: true, // Karaoke-like word highlighting
    translations: [
      { langCode: 'es', label: 'Spanish' },
      { langCode: 'fr', label: 'French' },
      { langCode: 'de', label: 'German' }
    ]
  }],

  transformation: [
    { width: 800, height: 600 },
    { quality: 80 }
  ]
};
---

<div>
  <h1>Video Player Demo</h1>
  <IKVideoPlayer
    ikOptions={ikOptions}
    source={source}
  />
</div>
```

{% callout style="info" %}
**AI-Powered Features:** The example above uses ImageKit's AI to automatically generate accurate subtitles in 50+ languages, create intelligent chapters, and enable word-level highlighting, all without manual transcription work.
{% /callout %}

For private videos or accounts with restrict-unsigned-URLs enabled, see [generating signed URLs in Astro](/video-player/overview#generating-signed-urls).

[**Explore Video Player SDK ->**](/video-player/overview)


---

# Source: /integration/angular

---
title: Angular ImageKit SDK
description: Real-time image & video resizing, automatic optimization, responsive images, and file uploading in Angular using ImageKit.io.
---

The Angular ImageKit SDK is a wrapper built on top of the ImageKit JavaScript SDK. It seamlessly integrates ImageKit's URL generation, image and video optimization, responsive image handling, and file upload capabilities into Angular applications.

The SDK is lightweight and has first-class TypeScript support. It works with Angular 14+ (standalone components and directives). You can view the [source code](https://github.com/imagekit-developer/imagekit-angular) on Github.

## Installation and Setup

Install the Angular SDK via npm or yarn:

```bash
npm install @imagekit/angular
# or
yarn add @imagekit/angular
```

The SDK supports both server-side rendering (SSR) and client-side rendering (CSR), so it can be added to any Angular project.

This Angular SDK exports `IKImageDirective` and `IKVideoDirective` directives. These directives can be applied to native `<img>` and `<video>` elements to add ImageKit's optimization and transformation capabilities. They automatically handle URL generation, lazy loading, responsive images, and transformations while preserving all native HTML attributes.

### Modern Angular (14+) - Standalone Directives

For Angular 14 and above, you can import standalone directives directly:

```js
import { Component } from '@angular/core';
import { IKImageDirective, provideImageKit } from '@imagekit/angular';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [IKImageDirective],
  template: `
    <img
      ikSrc="/profile.png"
      [width]="500"
      [height]="500"
      alt="Picture of the author"
    />
  `
})
export class AppComponent {}
```

Configure the SDK globally using `provideImageKit()` in your application config:

```js
import { ApplicationConfig } from '@angular/core';
import { provideImageKit } from '@imagekit/angular';

export const appConfig: ApplicationConfig = {
  providers: [
    provideImageKit({
      urlEndpoint: 'https://ik.imagekit.io/your_imagekit_id',
    })
  ]
};
```

Besides `IKImageDirective` and `IKVideoDirective`, the SDK also provides utility functions and error classes that can be used independently of the components.

#### Utility functions
- [`buildSrc`](/integration/javascript#buildsrc-parameters) – Generates URLs for images and videos based on your URL endpoint and transformation parameters.
- [`buildTransformationString`](/integration/javascript#buildtransformationstring-parameters) – Converts array of transformation objects into a URL query string.
- [`upload`](/integration/javascript#upload-parameters) – Facilitates file uploads to ImageKit with built-in support for common error handling, progress tracking, and abort functionality.
- [`getResponsiveImageAttributes`](/integration/javascript#getresponsiveimageattributes-parameters) – Generates responsive image attributes that can be used on raw HTML image elements. This SDK however handles this automatically for you when using the `IKImageDirective` component with `[responsive]="true"` .

Refer to linked documentation for detailed usage of these utility functions.

#### Error classes for upload error handling
- `ImageKitInvalidRequestError` - For invalid requests.
- `ImageKitAbortError` - For aborted uploads.
- `ImageKitUploadNetworkError` - For network errors during upload.
- `ImageKitServerError` - For server-side errors.


## Image Directive

The `IKImageDirective` is applied to native HTML `<img>` elements using the `ikSrc` attribute. It enhances the image element with ImageKit's URL generation, transformations, lazy-loading, and responsive image capabilities.

**Important:** The directive selector is `img[ikSrc]`, meaning you must use `ikSrc` instead of the standard `src` attribute.
 
It preserves all [HTML img attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/img#attributes) and additionally accepts the following ImageKit-specific inputs:

{% table %}

- Parameter {% width="30%" %}
- Description and Example {% width="70%" %}

---

- **urlEndpoint**  
- The base URL endpoint from your [ImageKit dashboard](https://imagekit.io/dashboard/url-endpoints).
  To avoid passing this input in every component, you can configure it globally using `provideImageKit()`. If you pass it in the component, it will override the global value.
  
  Example: `https://ik.imagekit.io/your_imagekit_id`.

---

- **ikSrc**  
  (Required)  
- A relative or absolute path to the image. This replaces the standard `src` attribute when using the directive.

  - If a **relative path** is provided, it is appended to the `urlEndpoint`.
  - If an **absolute path** is provided, it is used as-is and the `urlEndpoint` is ignored.
  - **Do not include query parameters** directly in `ikSrc`. Use the `queryParameters` input instead.
  - **When using a web proxy**, you can pass the full image URL and prepend it with a `/`. For example - `/https://example.com/image.jpg`.

  **Examples:**  
  Relative - `ikSrc="/default-image.jpg"`  
  Absolute - `ikSrc="https://example.com/image.jpg"`  
  Web Proxy - `ikSrc="/https://example.com/image.jpg"`

---

- **width**
- The width of the image in pixels (in numbers). This is used to calculate the srcSet attribute and is only utilized when sizes is not provided. The prop is set on the `<img>` element as it is. If provided value is not a number, then `srcset` is generated using the full list of device breakpoints
  
  Example: `[width]="300"`

---

- **transformation**
- An array of transformation objects. Each object can include properties like `width`, `height`, `rotation`, overlays, and advanced effects.  
  
  Example: `[transformation]="[{ width: 300, height: 300 }]"`  
  
  See all [supported transformation](#supported-transformations) options and how to [handle unsupported transformations](#handling-unsupported-transformations).

---

- **queryParameters**
- An object with additional query parameters to append to the URL.  
  Example: `[queryParameters]="{ v: 2 }"`

---

- **responsive**
- A boolean that determines if responsive image functionality is enabled. By default, this is `true`, meaning that a `srcset` attribute is automatically generated for responsive images. Set it to `false` to disable this behavior and only apply explicitly defined transformations.

---

- **deviceBreakpoints**  
  (number[])
- It allows you to specify a list of device width breakpoints.

  Defaults to `[640, 750, 828, 1080, 1200, 1920, 2048, 3840]`.

---

- **imageBreakpoints**  
  (number[])
- It allows you to specify a list of image width breakpoints. It is concatenated with `deviceBreakpoints` before calculating `srcSet`. 
  
  Defaults to `[16, 32, 48, 64, 96, 128, 256, 384]`.

---

- **transformationPosition**
- Specifies whether the transformation string is included in the URL path or as a query parameter. Defaults to `"query"`.  
  Example: `transformationPosition="query"` or `transformationPosition="path"`

---

- **loading**
- Controls lazy loading behavior. Set to `"lazy"` (default) to defer loading until the image is near the viewport, or `"eager"` to load immediately.
  Example: `loading="lazy"`

{% /table %}

## Video Directive

The `IKVideoDirective` is applied to native HTML `<video>` elements using the `ikSrc` attribute. It enhances the video element with ImageKit's URL generation and transformation capabilities.

**Important:** The directive selector is `video[ikSrc]`, meaning you must use `ikSrc` instead of the standard `src` attribute.

It preserves all [HTML video attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video#attributes) and additionally accepts the following ImageKit-specific inputs - `urlEndpoint`, `transformation`, `transformationPosition`, and `queryParameters`. For the definition of these inputs, refer to the [Image directive](#image-directive) section.

```js
import { Component } from '@angular/core';
import { IKVideoDirective } from '@imagekit/angular';

@Component({
  selector: 'app-video-example',
  standalone: true,
  imports: [IKVideoDirective],
  template: `
    <video
      ikSrc="/video.mp4"
      [controls]="true"
      [width]="500"
      [height]="500"
    ></video>
  `
})
export class VideoExampleComponent {}
```

## Height and Width Transformations

With ImageKit, you can resize images on the fly using the `width` and `height` properties. The SDK automatically generates the appropriate URL with the specified dimensions.

```js
import { Component } from '@angular/core';
import { IKImageDirective, Transformations } from '@imagekit/angular';

@Component({
  selector: 'app-resize-example',
  standalone: true,
  imports: [IKImageDirective],
  template: `
    <img
      ikSrc="/profile.png"
      [width]="500"
      [height]="500"
      alt="Picture of the author"
      [transformation]="transformation"
    />
  `
})
export class ResizeExampleComponent {
  transformation: Transformations = [{ width: 500, height: 500 }];
}
```

## Responsive Images

The `IKImageDirective` includes built-in support for **responsive images**, enabled by default. It automatically generates appropriate `srcSet` attributes based on device and image breakpoints, ensuring optimal image delivery across screen sizes.

Under the hood, it leverages the [`getResponsiveImageAttributes`](/integration/javascript#getresponsiveimageattributes-parameters) utility from the core JavaScript SDK to generate these attributes.

If you want to turn off responsive images, you can set `responsive` to `false`. This will disable the automatic generation of `srcset` attributes.

{% callout style="info" %}
**Note:** If you have enabled the "Restrict unnamed transformations" setting (see [Basic Security](/media-delivery-basic-security#restrict-unnamed-transformations)), hardcoded width/crop transformations may be added by default causing request failures. Setting `responsive` to `false` prevents these additional transformations from being applied.
{% /callout %}

## Lazy Loading Images

The `IKImageDirective` supports lazy loading by default. You can control this behavior using the [`loading`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/img#loading) attribute.

By default, `loading` is set to `lazy`, which defers loading the image until it is near the viewport.

If set to `eager`, the image loads immediately.

```js
import { Component } from '@angular/core';
import { IKImageDirective } from '@imagekit/angular';

@Component({
  selector: 'app-lazy-load-example',
  standalone: true,
  imports: [IKImageDirective],
  template: `
    <img
      ikSrc="/profile.png"
      [width]="500"
      [height]="500"
      alt="Picture of the author"
      loading="lazy"
    />
  `
})
export class LazyLoadExampleComponent {}
```

## Lazy Loading with Placeholder

To display a placeholder while an image is loading, you can generate a placeholder image URL using ImageKit's [`buildSrc`](/integration/javascript#buildsrc-parameters) utility function and apply it as a background image using styles. You can use Angular's event binding to manage the placeholder visibility.

```js
import { Component } from '@angular/core';
import { IKImageDirective, buildSrc } from '@imagekit/angular';
import { NgStyle } from '@angular/common';

@Component({
  selector: 'app-placeholder-example',
  standalone: true,
  imports: [IKImageDirective, NgStyle],
  template: `
    <img
      ikSrc="/default-image.jpg"
      alt="Angular logo"
      [width]="400"
      [height]="400"
      loading="eager"
      [ngStyle]="imageStyle"
      (load)="onImageLoad()"
    />
  `
})
export class PlaceholderExampleComponent {
  showPlaceholder = true;

  get imageStyle() {
    if (!this.showPlaceholder) return {};
    
    return {
      backgroundImage: `url(${buildSrc({
        urlEndpoint: 'https://ik.imagekit.io/your_imagekit_id',
        src: '/default-image.jpg',
        transformation: [
          { quality: 10, blur: 90 }
        ]
      })})`,
      backgroundSize: 'cover',
      backgroundRepeat: 'no-repeat'
    };
  }

  onImageLoad() {
    this.showPlaceholder = false;
  }
}
```

## Lazy Loading Videos

To lazy load a video using `IKVideoDirective`, you can set the `preload` attribute to `none` and specify a `poster` image by extracting a thumbnail from the video.

The [`buildSrc`](/integration/javascript#buildsrc-parameters) utility function is used to generate the thumbnail URL. It accepts the same parameters as the `IKVideoDirective` and returns a URL with the specified transformations.

Refer to the [create thumbnail](/create-video-thumbnails) documentation for detailed instructions on generating a thumbnail from a video using ImageKit.

```js
import { Component } from '@angular/core';
import { IKVideoDirective, buildSrc } from '@imagekit/angular';

@Component({
  selector: 'app-video-lazy-load',
  standalone: true,
  imports: [IKVideoDirective],
  template: `
    <video
      ikSrc="/video.mp4"
      [controls]="true"
      preload="none"
      [poster]="posterUrl"
    ></video>
  `
})
export class VideoLazyLoadComponent {
  posterUrl = buildSrc({
    urlEndpoint: 'https://ik.imagekit.io/your_imagekit_id',
    src: '/video.mp4/ik-thumbnail.jpg'
  });
}
```

## Chained Transformations

You can chain multiple transformations together by passing an array of transformation objects. Each object can specify different properties, such as width, height, cropping, overlays, and effects. See [chained transformations](/transformations#chained-transformations) for more details.

```js
import { Component } from '@angular/core';
import { IKImageDirective, Transformations } from '@imagekit/angular';

@Component({
  selector: 'app-chained-transform',
  standalone: true,
  imports: [IKImageDirective],
  template: `
    <img
      ikSrc="/profile.png"
      [width]="500"
      [height]="500"
      alt="Picture of the author"
      [transformation]="transformations"
    />
  `
})
export class ChainedTransformComponent {
  transformations: Transformations = [
    { width: 400, height: 300 },
    { rotation: 90 }
  ];
}
```

## Adding Overlays

You can add overlays to images and videos. The overlay can be a text, image, video, or subtitle.

Besides the overlay type, you can also specify the position, size, and other properties of the overlay. Check the [overlay options](#overlay-reference) for more details.

### Image Overlay

```js
import { Component } from '@angular/core';
import { IKImageDirective, Transformations } from '@imagekit/angular';

@Component({
  selector: 'app-image-overlay',
  standalone: true,
  imports: [IKImageDirective],
  template: `
    <img
      ikSrc="/background.jpg"
      alt="Background with image overlay"
      [width]="600"
      [height]="400"
      [transformation]="transformations"
    />
  `
})
export class ImageOverlayComponent {
  transformations: Transformations = [
    { overlay: { type: 'image', input: 'logo.png' } }
  ];
}
```

You can independently transform the overlay image by passing a transformation array inside the `overlay` object. The transformation will be applied to the overlay image only.

```js
import { Component } from '@angular/core';
import { IKImageDirective, Transformations } from '@imagekit/angular';

@Component({
  selector: 'app-image-overlay-transform',
  standalone: true,
  imports: [IKImageDirective],
  template: `
    <img
      ikSrc="/background.jpg"
      alt="Background with transformed image overlay"
      [width]="600"
      [height]="400"
      [transformation]="transformations"
    />
  `
})
export class ImageOverlayTransformComponent {
  transformations: Transformations = [
    { 
      overlay: { 
        type: 'image',
        input: 'logo.png',
        transformation: [{ width: 100, height: 100 }]
      } 
    }
  ];
}
```

Image overlays support a wide range of transformations. Check [reference](/add-overlays-on-images#list-of-supported-image-transformations-in-image-layers) for the complete list of transformations supported on image overlays.

### Solid Color Overlay

You can add a solid color overlay to images and videos.

```js
import { Component } from '@angular/core';
import { IKImageDirective, Transformations } from '@imagekit/angular';

@Component({
  selector: 'app-color-overlay',
  standalone: true,
  imports: [IKImageDirective],
  template: `
    <img
      ikSrc="/background.jpg"
      alt="Background with solid color overlay"
      [width]="600"
      [height]="400"
      [transformation]="transformations"
    />
  `
})
export class SolidColorComponent {
  transformations: Transformations = [
    { 
      overlay: { 
        type: 'solidColor',
        color: 'FF0000' 
      } 
    }
  ];
}
```

You can also specify the width, height, and other properties of the solid color overlay. For example:

```js
import { Component } from '@angular/core';
import { IKImageDirective, Transformations } from '@imagekit/angular';

@Component({
  selector: 'app-color-overlay-sized',
  standalone: true,
  imports: [IKImageDirective],
  template: `
    <img
      ikSrc="/background.jpg"
      alt="Background with 100x100 solid color overlay"
      [width]="600"
      [height]="400"
      [transformation]="transformations"
    />
  `
})
export class ColorOverlaySizedComponent {
  transformations: Transformations = [
    { 
      overlay: { 
        type: 'solidColor',
        color: 'FF0000',
        transformation: [
          { width: 100, height: 100 }
        ]
      } 
    }
  ];
}
```

For more options related to styling the solid color overlay, check the [solid color overlay transformations](#solid-color-overlay-transformations) section.

### Text Overlay

You can add text overlays to images and videos.

```js
import { Component } from '@angular/core';
import { IKImageDirective, Transformations } from '@imagekit/angular';

@Component({
  selector: 'app-text-overlay',
  standalone: true,
  imports: [IKImageDirective],
  template: `
    <img
      ikSrc="/background.jpg"
      alt="Background with text overlay"
      [width]="600"
      [height]="400"
      [transformation]="transformations"
    />
  `
})
export class TextOverlayComponent {
  transformations: Transformations = [
    { 
      overlay: { 
        type: 'text', 
        text: 'Hello, ImageKit!' 
      } 
    }
  ];
}
```

You can also specify the font size, color, and other properties of the text overlay. For example:

```js
import { Component } from '@angular/core';
import { IKImageDirective, Transformations } from '@imagekit/angular';

@Component({
  selector: 'app-text-overlay-styled',
  standalone: true,
  imports: [IKImageDirective],
  template: `
    <img
      ikSrc="/background.jpg"
      alt="Background with styled text overlay"
      [width]="600"
      [height]="400"
      [transformation]="transformations"
    />
  `
})
export class TextOverlayStyledComponent {
  transformations: Transformations = [
    { 
      overlay: { 
        type: 'text', 
        text: 'Hello, ImageKit!', 
        transformation: [
          { fontSize: 20, fontColor: 'FF0000' }
        ] 
      } 
    }
  ];
}
```

Check the [text overlay transformations](#text-overlay-transformations) section for more options related to styling the text.

### Video Overlay

You can add video overlays on videos only.

```js
import { Component } from '@angular/core';
import { IKVideoDirective, Transformations } from '@imagekit/angular';

@Component({
  selector: 'app-video-overlay',
  standalone: true,
  imports: [IKVideoDirective],
  template: `
    <video
      ikSrc="/background.mp4"
      [controls]="true"
      [transformation]="transformations"
    ></video>
  `
})
export class VideoOverlayComponent {
  transformations: Transformations = [
    { 
      overlay: { 
        type: 'video', 
        input: 'overlay.mp4' 
      } 
    }
  ];
}
```

Additionally, you can specify the start and duration for the overlay video. For example:

```js
import { Component } from '@angular/core';
import { IKVideoDirective, Transformations } from '@imagekit/angular';

@Component({
  selector: 'app-video-overlay-timed',
  standalone: true,
  imports: [IKVideoDirective],
  template: `
    <video
      ikSrc="/background.mp4"
      [controls]="true"
      [transformation]="transformations"
    ></video>
  `
})
export class VideoOverlayTimedComponent {
  transformations: Transformations = [
    { 
      overlay: { 
        type: 'video', 
        input: 'overlay.mp4',
        timing: { start: 5, duration: 10 }
      } 
    }
  ];
}
```

You can also independently transform the overlay video. For example, to resize the overlay video:

```js
import { Component } from '@angular/core';
import { IKVideoDirective, Transformations } from '@imagekit/angular';

@Component({
  selector: 'app-video-overlay-transform',
  standalone: true,
  imports: [IKVideoDirective],
  template: `
    <video
      ikSrc="/background.mp4"
      [controls]="true"
      [transformation]="transformations"
    ></video>
  `
})
export class VideoOverlayTransformComponent {
  transformations: Transformations = [
    { 
      overlay: { 
        type: 'video', 
        input: 'overlay.mp4',
        transformation: [
          { width: 100, height: 100 }
        ] 
      } 
    }
  ];
}
```

All supported [video transformations](/video-transformation) can also be applied to overlay videos.

If you're overlaying an image on a base video, refer to [this list](/add-overlays-on-videos#list-of-transformations-supported-on-image-overlay) for all the transformations supported on image overlays.

### Subtitle Overlay

You can add subtitle overlays on videos.

```js
import { Component } from '@angular/core';
import { IKVideoDirective, Transformations } from '@imagekit/angular';

@Component({
  selector: 'app-subtitle-overlay',
  standalone: true,
  imports: [IKVideoDirective],
  template: `
    <video
      ikSrc="/background.mp4"
      [controls]="true"
      [transformation]="transformations"
    ></video>
  `
})
export class SubtitleOverlayComponent {
  transformations: Transformations = [
    { 
      overlay: { 
        type: 'subtitle', 
        input: 'subtitle.srt' 
      } 
    }
  ];
}
```

The subtitle overlay can be styled with various properties such as font size, color, and outline. See the [Subtitle Overlay Transformations](#subtitle-overlay-transformations) section for all styling options.

## Background Removal Using AI

```js
import { Component } from '@angular/core';
import { IKImageDirective, Transformations } from '@imagekit/angular';

@Component({
  selector: 'app-bg-removal',
  standalone: true,
  imports: [IKImageDirective],
  template: `
    <img
      ikSrc="/photo.jpg"
      alt="Photo with background removal"
      [width]="500"
      [height]="500"
      [transformation]="transformations"
    />
  `
})
export class BgRemovalComponent {
  transformations: Transformations = [
    { aiRemoveBackground: true }
  ];
}
```

ImageKit supports multiple AI-powered transformations, like upscaling, generative fill, and more. More examples:

```js
import { Component } from '@angular/core';
import { IKImageDirective, Transformations } from '@imagekit/angular';

@Component({
  selector: 'app-ai-drop-shadow',
  standalone: true,
  imports: [IKImageDirective],
  template: `
    <img
      ikSrc="/photo.jpg"
      alt="Photo with AI drop shadow"
      [width]="500"
      [height]="500"
      [transformation]="transformations"
    />
  `
})
export class AiDropShadowComponent {
  transformations: Transformations = [
    { aiDropShadow: true }
  ];
}
```

Upscaling example:

```js
import { Component } from '@angular/core';
import { IKImageDirective, Transformations } from '@imagekit/angular';

@Component({
  selector: 'app-ai-upscale',
  standalone: true,
  imports: [IKImageDirective],
  template: `
    <img
      ikSrc="/photo.jpg"
      alt="Photo with AI upscaling"
      [width]="500"
      [height]="500"
      [transformation]="transformations"
    />
  `
})
export class AiUpscaleComponent {
  transformations: Transformations = [
    { aiUpscale: true }
  ];
}
```

## Arithmetic Expressions

You can use arithmetic expressions to dynamically compute transformation values. For example, to set the width to half of the original image width:

```js
import { Component } from '@angular/core';
import { IKImageDirective, Transformations } from '@imagekit/angular';

@Component({
  selector: 'app-arithmetic',
  standalone: true,
  imports: [IKImageDirective],
  template: `
    <img
      ikSrc="/photo.jpg"
      alt="Photo with arithmetic width"
      [width]="300"
      [height]="200"
      [transformation]="transformations"
    />
  `
})
export class ArithmeticComponent {
  transformations: Transformations = [
    { width: 'iw_div_2' }
  ];
}
```

Check out the [Arithmetic Expressions](/arithmetic-expressions-in-transformations) reference for more examples and details.

## Uploading Files

The Angular SDK exports a utility function `upload()`, which enables you to upload files to ImageKit. The function wraps the core JavaScript SDK's `upload()` function, which leverages the [Upload V1 API](/api-reference/upload-file/upload-file).

The SDK automatically converts certain parameters into JSON strings, as required by the API. If a parameter is not explicitly supported by the SDK, it is included in the request as-is. For a complete list of parameters and expected formats, refer to the API documentation.

### upload() Parameters

The `upload()` function accepts a JSON object with the following parameters:

{% table %}

- Option {% width="30%" %}
- Description and Example {% width="70%" %}

---

- **file**  
  (Required)  
- The file content to be uploaded. Accepts binary data, a base64-encoded string, or a URL. Typically used with a File or Blob in the browser. Example: `file: fileInput.files[0]`

---

- **fileName**  
  (Required)  
- The name to assign to the uploaded file. Supports alphanumeric characters, dot, underscore, and dash. Any other character is replaced with `_`. Example: `fileName: "myImage.jpg"`

---

- **signature**  
  (Required)  
- The HMAC-SHA1 digest of the concatenation of "token + expire". The signing key is your ImageKit private API key. Must be computed on the server side. Example: `signature: "generated_signature"`

---

- **token**  
  (Required)  
- A unique value to identify and prevent replays. Typically a UUID (e.g., version 4). Example: `token: "unique_upload_token"`
  
  Check the [signature generation](#generating-authentication-parameters) section for more details on how to generate this value.

---

- **expire**  
  (Required)  
- A Unix timestamp in seconds, less than 1 hour in the future. Example: `expire: 1616161616`
  
  Check the [signature generation](#generating-authentication-parameters) section for more details on how to generate this value.

---

- **publicKey**  
  (Required)
- The public API key for your ImageKit account. This is used to identify the account making the upload request. Example: `publicKey: "your_public_api_key"`
  
  Check the [signature generation](#generating-authentication-parameters) section for more details on how to generate this value.

---

- **onProgress**
- A callback function to track the upload progress. It receives an event object with `loaded` and `total` properties. Example: `onProgress: (event) => console.log(event.loaded, event.total)`
  This is useful for showing upload progress to the user.

---
- **abortSignal**
- An optional `AbortSignal` object to abort the upload request. If the signal is already aborted, the upload will fail immediately.
  You can create an `AbortController` instance and pass its signal to the `upload()` function.

---

- **useUniqueFileName**
- Boolean flag to automatically generate a unique filename if set to true. Defaults to true. If false, the image is uploaded with the provided filename, replacing any existing file with the same name. Example: `useUniqueFileName: true`

---

- **folder**
- The folder path where the file will be stored, e.g., "/images/folder/". If the path doesn't exist, it is created on-the-fly. Example: `folder: "/images/uploads"`

---

- **isPrivateFile**
- Boolean to mark the file as private, restricting access to the original file URL. A private file requires signed URLs or named transformations for access. Defaults to false. Example: `isPrivateFile: false`

---

- **tags**
- Optionally set tags on the uploaded file. Can be a comma-separated string or an array of tags. Example: `tags: "summer,holiday"` or `tags: ["summer","holiday"]`

---

- **customCoordinates**
- A string in "x,y,width,height" format that defines the region of interest in an image (top-left coords and area size). Example: `customCoordinates: "10,10,100,100"`

---

- **responseFields**
- A comma-separated or array-based set of fields to return in the upload response. Example: `responseFields: "tags,customCoordinates"`

---

- **extensions**
- An array of extension objects to apply to the image, e.g., background removal, auto-tagging, etc. Example: `extensions: [{ name: "auto-tagging" }]`

---

- **webhookUrl**
- A webhook URL to receive the final status of any pending extensions once they've completed processing. Example: `webhookUrl: "https://example.com/webhook"`

---

- **overwriteFile**
- Defaults to true. If false, and "useUniqueFileName" is also false, the API immediately fails if a file with the same name/folder already exists. Example: `overwriteFile: true`

---

- **overwriteAITags**
- Defaults to true. If true, and an existing file is found at the same location, its AITags are removed. Set to false to keep existing AITags. Example: `overwriteAITags: true`

---

- **overwriteTags**
- Defaults to true. If no tags are specified in the request, existing tags are removed from overwritten files. Setting to false has no effect if the request includes tags. Example: `overwriteTags: true`

---

- **overwriteCustomMetadata**
- Defaults to true. If no customMetadata is specified in the request, existing customMetadata is removed from overwritten files. Setting to false has no effect if the request specifies customMetadata. Example: `overwriteCustomMetadata: true`

---

- **customMetadata**
- A stringified JSON or an object containing custom metadata fields to store with the file. Custom metadata fields must be pre-defined in your ImageKit configuration. Example: `customMetadata: {author: "John Doe"}`

---

- **transformation**
- Defines pre and post transformations to be applied to the file during upload. The SDK enforces certain validation rules for pre/post transformations. Example: `transformation: { pre: "w-200,h-200", post: [...] }`

---

- **xhr**
- An optional XMLHttpRequest instance for the upload. The SDK merges it with its own logic to handle progress events, etc. Example: `xhr: new XMLHttpRequest()`

---

- **checks**
- A string specifying the checks to be performed server-side before uploading to the media library, e.g., size or mime type checks. Example: `checks: "file.size' < '1MB'"`

{% /table %}


## Upload Example and Error Handling

The `upload()` function expects the following mandatory parameters:

- **`file` and `fileName`** – The file to be uploaded and the name you want to assign to it. The `file` value can be a `File` object, a base64-encoded string, or a URL.
- **Authentication parameters** – `token`, `signature` & `expire`

Authentication is essential for secure file uploads from the browser. You should **never expose your private API key** in client-side code. Instead, generate these one-time authentication parameters on the **server side** and pass them to the client.

To simplify the process, all of our [backend SDKs](/quick-start-guides#back-end) include utility functions for generating authentication parameters.

{% callout style="info" %}
**Note:** If you're using `HttpClient` in your components to fetch authentication parameters, make sure to provide it in your application. For standalone components, add `provideHttpClient()` to your application config providers.
{% /callout %}

### Upload Flow Overview

Here's how the upload process using the SDK works:

1. **Client Request for Auth Parameters**  
   The client component calls an API route to fetch the authentication parameters.  
   You can implement your own application logic within this route to authenticate the user.  
   After that, use one of our backend SDKs to generate the required auth parameters and return them to the client.

2. **File Upload**  
   Once the client has the auth parameters, it can call the `upload()` function with the necessary data.

### Generating Authentication Parameters

The following example demonstrates how to create an API route that generates authentication parameters using the ImageKit [backend SDKs](/quick-start-guides#back-end).

You can find your [private key](/api-keys#private-key) and [public key](/api-keys#public-key) in the ImageKit dashboard.

{% tabs %}
{% tab title="Node.js" %}
```js
const express = require('express');
const ImageKit = require('@imagekit/nodejs'); // Node.js SDK
const app = express();

const client = new ImageKit({
  privateKey: process.env.IMAGEKIT_PRIVATE_KEY
});

// allow cross-origin requests
app.use(function(req, res, next) {
  res.header("Access-Control-Allow-Origin", "*");
  res.header("Access-Control-Allow-Headers", 
    "Origin, X-Requested-With, Content-Type, Accept");
  next();
});

app.get('/auth', function (req, res) {
  // Your application logic to authenticate the user
  // For example, you can check if the user is logged in or has the necessary permissions
  // If the user is not authenticated, you can return an error response
  const { token, expire, signature } = client.helper.getAuthenticationParameters();
  res.send({ token, expire, signature, publicKey: process.env.IMAGEKIT_PUBLIC_KEY });
});

app.listen(3000, function () {
  console.log('Live at Port 3000');
});
```
{% /tab %}

{% tab title="Go" %}
```go
package main

import (
	"encoding/json"
	"log"
	"net/http"
	"os"

	"github.com/imagekit-developer/imagekit-go/v2"
	"github.com/imagekit-developer/imagekit-go/v2/option"
)

func main() {
	client := imagekit.NewClient(
		option.WithPrivateKey(os.Getenv("IMAGEKIT_PRIVATE_KEY")),
	)

	http.HandleFunc("/auth", func(w http.ResponseWriter, r *http.Request) {
		// Enable CORS
		w.Header().Set("Access-Control-Allow-Origin", "*")
		w.Header().Set("Access-Control-Allow-Headers", "Origin, X-Requested-With, Content-Type, Accept")

		// Your application logic to authenticate the user
		// For example, you can check if the user is logged in or has the necessary permissions
		// If the user is not authenticated, you can return an error response

		authParams := client.Helper.GetAuthenticationParameters("", 0)
		
		response := map[string]interface{}{
			"token":     authParams["token"],
			"expire":    authParams["expire"],
			"signature": authParams["signature"],
			"publicKey": os.Getenv("IMAGEKIT_PUBLIC_KEY"),
		}

		w.Header().Set("Content-Type", "application/json")
		json.NewEncoder(w).Encode(response)
	})

	log.Println("Live at Port 3000")
	log.Fatal(http.ListenAndServe(":3000", nil))
}
```
{% /tab %}

{% tab title="Python" %}
```python
import os
from flask import Flask, jsonify
from imagekitio import ImageKit

app = Flask(__name__)

imagekit = ImageKit(
    private_key=os.environ.get("IMAGEKIT_PRIVATE_KEY")
)

# Enable CORS
@app.after_request
def after_request(response):
    response.headers.add('Access-Control-Allow-Origin', '*')
    response.headers.add('Access-Control-Allow-Headers', 'Origin, X-Requested-With, Content-Type, Accept')
    return response

@app.route('/auth')
def get_auth():
    # Your application logic to authenticate the user
    # For example, you can check if the user is logged in or has the necessary permissions
    # If the user is not authenticated, you can return an error response
    
    auth_params = imagekit.helper.get_authentication_parameters()
    
    return jsonify({
        'token': auth_params['token'],
        'expire': auth_params['expire'],
        'signature': auth_params['signature'],
        'publicKey': os.environ.get('IMAGEKIT_PUBLIC_KEY')
    })

if __name__ == '__main__':
    app.run(port=3000)
```
{% /tab %}

{% tab title="Ruby" %}
```ruby
require 'sinatra'
require 'imagekitio'
require 'json'

# Enable CORS
before do
  headers['Access-Control-Allow-Origin'] = '*'
  headers['Access-Control-Allow-Headers'] = 'Origin, X-Requested-With, Content-Type, Accept'
end

client = Imagekitio::Client.new(private_key: ENV['IMAGEKIT_PRIVATE_KEY'])

get '/auth' do
  content_type :json
  
  # Your application logic to authenticate the user
  # For example, you can check if the user is logged in or has the necessary permissions
  # If the user is not authenticated, you can return an error response
  
  auth_params = client.helper.get_authentication_parameters
  
  {
    token: auth_params[:token],
    expire: auth_params[:expire],
    signature: auth_params[:signature],
    publicKey: ENV['IMAGEKIT_PUBLIC_KEY']
  }.to_json
end

# Start the server
set :port, 3000
```
{% /tab %}

{% tab title="Java" %}
```java
import io.imagekit.client.ImageKitClient;
import io.imagekit.client.okhttp.ImageKitOkHttpClient;
import spark.Spark;
import com.google.gson.Gson;
import java.util.Map;
import java.util.HashMap;

// Using Spark framework (http://sparkjava.com)
public class AuthServer {
    public static void main(String[] args) {
        ImageKitClient client = ImageKitOkHttpClient.builder()
            .privateKey(System.getenv("IMAGEKIT_PRIVATE_KEY"))
            .build();

        Gson gson = new Gson();

        // Enable CORS
        Spark.before((request, response) -> {
            response.header("Access-Control-Allow-Origin", "*");
            response.header("Access-Control-Allow-Headers", "Origin, X-Requested-With, Content-Type, Accept");
        });

        Spark.get("/auth", (request, response) -> {
            // Your application logic to authenticate the user
            // For example, you can check if the user is logged in or has the necessary permissions
            // If the user is not authenticated, you can return an error response

            Map<String, Object> authParams = client.helper().getAuthenticationParameters(null, null);
            
            Map<String, Object> responseData = new HashMap<>();
            responseData.put("token", authParams.get("token"));
            responseData.put("expire", authParams.get("expire"));
            responseData.put("signature", authParams.get("signature"));
            responseData.put("publicKey", System.getenv("IMAGEKIT_PUBLIC_KEY"));

            response.type("application/json");
            return gson.toJson(responseData);
        });

        Spark.port(3000);
        System.out.println("Live at Port 3000");
    }
}
```
{% /tab %}

{% tab title=".Net" %}
```csharp
using Imagekit;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

ImageKitClient client = new() { PrivateKey = Environment.GetEnvironmentVariable("IMAGEKIT_PRIVATE_KEY") };

app.Use(async (context, next) =>
{
    context.Response.Headers["Access-Control-Allow-Origin"] = "*";
    context.Response.Headers["Access-Control-Allow-Headers"] = "Origin, X-Requested-With, Content-Type, Accept";
    await next();
});

app.MapGet("/auth", () =>
{
    // Your application logic to authenticate the user
    var authParams = client.Helper.GetAuthenticationParameters();
    return new
    {
        token = authParams.Token,
        expire = authParams.Expire,
        signature = authParams.Signature,
        publicKey = Environment.GetEnvironmentVariable("IMAGEKIT_PUBLIC_KEY"),
    };
});

Console.WriteLine("Live at Port 3000");
app.Run("http://localhost:3000");
```
{% /tab %}
{% /tabs %}

Now your client-side code can call this API route to retrieve the upload parameters.

The example below demonstrates how to use the `upload()` function in a component to upload a file, including error handling for various upload scenarios.

```js
import { Component, inject } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { CommonModule } from '@angular/common';
import {
  upload,
  ImageKitAbortError,
  ImageKitInvalidRequestError,
  ImageKitUploadNetworkError,
  ImageKitServerError
} from '@imagekit/angular';

interface AuthResponse {
  signature: string;
  expire: number;
  token: string;
  publicKey: string;
}

@Component({
  selector: 'app-upload-example',
  standalone: true,
  imports: [CommonModule],
  template: `
    <div>
      <input 
        type="file" 
        (change)="onFileSelect($event)"
        #fileInput
      />
      <button 
        type="button" 
        (click)="handleUpload()"
        [disabled]="!selectedFile"
      >
        Upload file
      </button>
      <br />
      <div *ngIf="progress > 0">
        <progress [value]="progress" max="100"></progress>
        <span>{{ progress.toFixed(0) }}%</span>
      </div>
      <div *ngIf="uploadStatus">
        {{ uploadStatus }}
      </div>
    </div>
  `
})
export class UploadExampleComponent {
  private http = inject(HttpClient);
  
  selectedFile: File | null = null;
  progress = 0;
  uploadStatus = '';
  
  private abortController = new AbortController();

  onFileSelect(event: Event) {
    const target = event.target as HTMLInputElement;
    if (target.files && target.files.length > 0) {
      this.selectedFile = target.files[0];
      this.progress = 0;
      this.uploadStatus = '';
    }
  }

  async handleUpload() {
    const file = this.selectedFile;
    if (!file) {
      alert('Please select a file to upload');
      return;
    }

    try {
      // Fetch authentication parameters from your backend
      const authParams = await this.http.get<AuthResponse>('/auth').toPromise();
      
      if (!authParams) {
        throw new Error('Failed to get authentication parameters');
      }

      // Upload the file
      const response = await upload({
        file: file,
        fileName: file.name,
        signature: authParams.signature,
        expire: authParams.expire,
        token: authParams.token,
        publicKey: authParams.publicKey,
        onProgress: (event) => {
          this.progress = (event.loaded / event.total) * 100;
        },
        abortSignal: this.abortController.signal
      });

      this.uploadStatus = 'Upload successful!';
      console.log('Upload response:', response);
      
    } catch (error) {
      if (error instanceof ImageKitAbortError) {
        this.uploadStatus = 'Upload aborted';
        console.error('Upload aborted:', error.reason);
      } else if (error instanceof ImageKitInvalidRequestError) {
        this.uploadStatus = 'Invalid request';
        console.error('Invalid request:', error.message);
      } else if (error instanceof ImageKitUploadNetworkError) {
        this.uploadStatus = 'Network error';
        console.error('Network error:', error.message);
      } else if (error instanceof ImageKitServerError) {
        this.uploadStatus = 'Server error';
        console.error('Server error:', error.message);
      } else {
        this.uploadStatus = 'Upload failed';
        console.error('Upload error:', error);
      }
    }
  }

  // Optional: Method to abort the upload
  abortUpload() {
    this.abortController.abort();
  }
}
```

## Supported Transformations

The SDK gives a name to each transformation parameter (e.g. `height` maps to `h`, `width` maps to `w`). If the property does not match any of the following supported options, it is added as is in the URL.

If you want to generate transformations without any modifications, use the `raw` parameter. For example, the SDK doesn't provide a nice way to write [conditional transformations](/conditional-transformations), so you can use the `raw` parameter to add them as is.

Check [transformation documentation](/transformations) for a complete reference on all transformations supported by ImageKit.

| Transformation Name        | URL Parameter                                                                                  |
| -------------------------- | ---------------------------------------------------------------------------------------------- |
| width                      | w                                                                                              |
| height                     | h                                                                                              |
| aspectRatio                | ar                                                                                             |
| quality                    | q                                                                                              |
| aiRemoveBackground         | e-bgremove (ImageKit powered)                                                                  |
| aiRemoveBackgroundExternal | e-removedotbg (Using third party)                                                              |
| aiEdit                     | e-edit                                                                                         |
| aiUpscale                  | e-upscale                                                                                      |
| aiRetouch                  | e-retouch                                                                                      |
| aiVariation                | e-genvar                                                                                       |
| aiDropShadow               | e-dropshadow                                                                                   |
| aiChangeBackground         | e-changebg                                                                                     |
| colorize                   | e-colorize                                                                                     |
| gradient                   | e-gradient                                                                                     |
| distort                    | e-distort                                                                                      |
| crop                       | c                                                                                              |
| cropMode                   | cm                                                                                             |
| x                          | x                                                                                              |
| y                          | y                                                                                              |
| xCenter                    | xc                                                                                             |
| yCenter                    | yc                                                                                             |
| focus                      | fo                                                                                             |
| format                     | f                                                                                              |
| radius                     | r                                                                                              |
| background                 | bg                                                                                             |
| border                     | b                                                                                              |
| rotation                   | rt                                                                                             |
| blur                       | bl                                                                                             |
| named                      | n                                                                                              |
| dpr                        | dpr                                                                                            |
| progressive                | pr                                                                                             |
| lossless                   | lo                                                                                             |
| trim                       | t                                                                                              |
| metadata                   | md                                                                                             |
| colorProfile               | cp                                                                                             |
| defaultImage               | di                                                                                             |
| original                   | orig                                                                                           |
| videoCodec                 | vc                                                                                             |
| audioCodec                 | ac                                                                                             |
| grayscale                  | e-grayscale                                                                                    |
| contrastStretch            | e-contrast                                                                                     |
| shadow                     | e-shadow                                                                                       |
| sharpen                    | e-sharpen                                                                                      |
| unsharpMask                | e-usm                                                                                          |
| gradient                   | e-gradient                                                                                     |
| flip                       | fl                                                                                             |
| opacity                    | o                                                                                              |
| zoom                       | z                                                                                              |
| page                       | pg                                                                                             |
| startOffset                | so                                                                                             |
| endOffset                  | eo                                                                                             |
| duration                   | du                                                                                             |
| streamingResolutions       | sr                                                                                             |
| colorReplace               | cr                                                                                             |
| overlay                    | Generates the correct layer syntax for image, video, text, subtitle, and solid color overlays. |
| raw                        | The string provided in raw will be added in the URL as is.                                     |


## Handling Unsupported Transformations

If you specify a transformation parameter that is not explicitly supported by the SDK, it is added "as-is" in the generated URL. This provides flexibility for using new or custom transformations without waiting for an SDK update. However add `@ts-ignore` to avoid TypeScript errors for unsupported transformations, or add transformation as a string in the `raw` parameter.

For example:

```js
import { Component } from '@angular/core';
import { IKImageDirective, Transformations } from '@imagekit/angular';

@Component({
  selector: 'app-unsupported-transform',
  standalone: true,
  imports: [IKImageDirective],
  template: `
    <img
      ikSrc="/photo.jpg"
      alt="Photo with unsupported transformation"
      [transformation]="transformations"
    />
  `
})
export class UnsupportedTransformComponent {
  // @ts-ignore - unsupported transformation
  transformations: Transformations = [
    { unsupportedTransformation: "value" }
  ];
}
// Output URL: https://ik.imagekit.io/your_imagekit_id/photo.jpg?tr=unsupportedTransformation-value
```

## Overlay Reference

This SDK provides `overlay` as a transformation parameter. The overlay can be a text, image, video, subtitle, or solid color.

Overlays in ImageKit are applied using layers, allowing you to stack multiple overlays on top of each other. Each overlay can be styled and positioned independently. For more details, refer to the [layer documentation](/transformations#overlay-using-layers).

The SDK automatically generates the correct layer syntax for image, video, text, subtitle, and solid color overlays. You can also specify the overlay position, size, and other properties.

The table below outlines the available overlay configuration options:

{% table %}

- Option {% width="30%" %}
- Description and Example {% width="70%" %}

---

- **type**  
  (Required)
- Specifies the type of overlay. Supported values: `text`, `image`, `video`, `subtitle`, `solidColor`. Example: `type: "text"`

---

- **text**  
  (Required for text overlays)
- The text content to display. Example: `text: "ImageKit"`

---

- **input**  
  (Required for image, video, or subtitle overlays)
- Relative path to the overlay asset. Example: `input: "logo.png"` or `input: "overlay-video.mp4"`

---

- **color**  
  (Required for solidColor overlays)
- RGB/RGBA hex code or color name for the overlay color. Example: `color: "FF0000"`

---

- **encoding**
- Accepted values: `auto`, `plain`, `base64`. [Check this](#encoding-options) for more details. Example: `encoding: "auto"`

---

- **transformation**
- An array of transformation objects to style the overlay independently of the base asset. Each overlay type has its own set of supported transformations.
  - For example, for text overlays, you can specify `fontSize`, `fontColor`, `background`, etc. Example: `transformation: [{ fontSize: 20, fontColor: "FF0000" }]`. Check out the [text overlay transformations](#text-overlay-transformations) section for more options.
  - For image overlays, you can specify `width`, `height`, `radius`, etc. Example: `transformation: [{ width: 100, height: 100 }]`. Check [reference](/add-overlays-on-images#list-of-supported-image-transformations-in-image-layers) for complete list of transformations supported on image overlays.
  - For video overlays, you can specify `width`, `height`, `rotation`, etc. Example: `transformation: [{ width: 100, height: 100 }]`. Check [reference](/add-overlays-on-videos#list-of-transformations-supported-on-image-overlay) for complete list of transformations supported on video overlays.
  - For subtitle overlays, you can specify `fontSize`, `fontColor`, `background`, etc. Example: `transformation: [{ fontSize: 20, fontColor: "FF0000" }]`. Check out the [subtitle overlay transformations](#subtitle-overlay-transformations) section for more options.
  - For solid color overlays, you can specify `width`, `height`, `radius`, etc. Example: `transformation: [{ width: 100, height: 100 }]`. Check out the [solid color overlay transformations](#solid-color-overlay-transformations) section for more options.


---

- **layerMode**
- Controls how the layer blends with the base image or underlying content. 
  - By default, layers completely cover the base image beneath them. Layer modes change this behavior. 
  - Supported values: `multiply`, `displace`, `cutout`, `cutter`, Check [reference](/add-overlays-on-images#layer-modes)

---

- **position**
- Sets the overlay’s position relative to the base asset. Accepts an object with `x`, `y`, or `focus`. Example: `position: { x: 10, y: 20 }` or `position: { focus: "center" }`

---

- **timing**
- (For video base) Specifies when the overlay appears using `start`, `duration`, and `end` (in seconds); if both `duration` and `end` are set, `duration` is ignored. Example: `timing: { start: 5, duration: 10 }`

{% /table %}

### Encoding Options

Overlay encoding options define how the overlay input is converted for URL construction. When set to `auto`, the SDK automatically determines whether to use plain text or Base64 encoding based on the input content.

For text overlays:
- If `auto` is used, the SDK checks the text overlay input: if it is URL-safe, it uses the format `i-{input}` (plain text); otherwise, it applies Base64 encoding with the format `ie-{base64_encoded_input}`.
- You can force a specific method by setting encoding to `plain` (always use `i-{input}`) or `base64` (always use `ie-{base64}`).
- Note: In all cases, the text is percent-encoded to ensure URL safety.

For image, video, and subtitle overlays:
- The input path is processed by removing any leading/trailing slashes and replacing inner slashes with `@@` when `plain` is used.
- Similarly, if `auto` is used, the SDK determines whether to apply plain text or Base64 encoding based on the characters present.
- For explicit behavior, use `plain` or `base64` to enforce the desired encoding.

Use `auto` for most cases to let the SDK optimize encoding, and use `plain` or `base64` when a specific encoding method is required.

### Solid Color Overlay Transformations

| Option     | Description                                                                                                                                                                                                                   | Example             |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| width      | Specifies the width of the solid color overlay block (in pixels or as an arithmetic expression).                                                                                                                              | `width: 100`        |
| height     | Specifies the height of the solid color overlay block (in pixels or as an arithmetic expression).                                                                                                                             | `height: 50`        |
| radius     | Specifies the corner radius of the solid color overlay block or shape. Can be a number or `"max"` for circular/oval shapes.                                                                                                   | `radius: "max"`     |
| alpha      | Specifies the transparency level of the solid color overlay. Supports integers from 1 (most transparent) to 9 (least transparent).                                                                                            | `alpha: 5`          |
| background | Specifies the background color of the solid color overlay. Accepts an RGB hex code, an RGBA code, or a standard color name.                                                                                                   | `background: "red"` |
| gradient   | Only works if base asset is an image. Creates a linear gradient with two colors. Pass `true` for a default gradient, or provide a string for a custom gradient. [Learn more](/effects-and-enhancements#gradient---e-gradient) | `gradient: true`    |

### Text Overlay Transformations

| Option         | Description                                                                                                                                                              | Example                    |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- |
| width          | Specifies the maximum width (in pixels) of the overlaid text. The text wraps automatically, and arithmetic expressions are supported (e.g., `bw_mul_0.2` or `bh_div_2`). | `width: 400`               |
| fontSize       | Specifies the font size of the overlaid text. Accepts a numeric value or an arithmetic expression.                                                                       | `fontSize: 50`             |
| fontFamily     | Specifies the font family of the overlaid text. Choose from the supported fonts or provide a custom font.                                                                | `fontFamily: "Arial"`      |
| fontColor      | Specifies the font color of the overlaid text. Accepts an RGB hex code, an RGBA code, or a standard color name.                                                          | `fontColor: "FF0000"`      |
| innerAlignment | Specifies the inner alignment of the text when it doesn’t occupy the full width. Supported values: `left`, `right`, `center`.                                            | `innerAlignment: "center"` |
| padding        | Specifies the padding around the text overlay. Can be a single integer or multiple values separated by underscores; arithmetic expressions are accepted.                 | `padding: 10`              |
| alpha          | Specifies the transparency level of the text overlay. Accepts an integer between `1` and `9`.                                                                            | `alpha: 5`                 |
| typography     | Specifies the typography style of the text. Supported values: `b` for bold, `i` for italics, and `b_i` for bold with italics.                                            | `typography: "b"`          |
| background     | Specifies the background color of the text overlay. Accepts an RGB hex code, an RGBA code, or a color name.                                                              | `background: "red"`        |
| radius         | Specifies the corner radius of the text overlay. Accepts a numeric value or `max` for circular/oval shape.                                                               | `radius: "max"`            |
| rotation       | Specifies the rotation angle of the text overlay. Accepts a numeric value for clockwise rotation or a string prefixed with `N` for counterclockwise rotation.            | `rotation: 90`             |
| flip           | Specifies the flip option for the text overlay. Supported values: `h`, `v`, `h_v`, `v_h`.                                                                                | `flip: "h"`                |
| lineHeight     | Specifies the line height for multi-line text. Accepts a numeric value or an arithmetic expression.                                                                      | `lineHeight: 20`           |

### Subtitle Overlay Transformations

| Option      | Description                                                                                               | Example                 |
| ----------- | --------------------------------------------------------------------------------------------------------- | ----------------------- |
| background  | Specifies the subtitle background color using a standard color name, RGB color code, or RGBA color code.  | `background: "blue"`    |
| fontSize    | Sets the font size of subtitle text.                                                                      | `fontSize: 16`          |
| fontFamily  | Sets the font family of subtitle text.                                                                    | `fontFamily: "Arial"`   |
| color       | Specifies the font color of subtitle text using standard color name, RGB, or RGBA color code.             | `color: "FF0000"`       |
| typography  | Sets the typography style of subtitle text. Supported values: `b`, `i`, `b_i`.                            | `typography: "b"`       |
| fontOutline | Specifies the font outline for subtitles. Requires an outline width and color separated by an underscore. | `fontOutline: "2_blue"` |
| fontShadow  | Specifies the font shadow for subtitles. Requires shadow color and indent separated by an underscore.     | `fontShadow: "blue_2"`  |


---

# Source: /integration/android

---
title: Android
description: >-
  Real-time image & video resizing, automatic optimization, and file uploading in
  Android using ImageKit.io.
---

This quickstart guide shows you how to integrate ImageKit into an Android application. The code samples covered are available on Github: [https://github.com/imagekit-samples/quickstart/tree/master/android](https://github.com/imagekit-samples/quickstart/tree/master/android). You can view the [Android SDK source code](https://github.com/imagekit-developer/imagekit-android) on GitHub.

This guide walks you through the following topics: ‌

* [Clone and run the tutorial app](#clone-and-run-the-tutorial-app)
* [Setting up ImageKit Android SDK](#setup-imagekit-android-sdk)
* [Rendering images](#rendering-images-in-android-application)
* [Applying common image manipulations](#common-image-manipulation-in-android-application)
* [Client-side file uploading](#client-side-file-uploading)
* [Setting an upload policy](#setting-an-upload-policy)
* [How to preprocess your files before uploading](#how-to-preprocess-your-files-before-uploading)

## Clone and run the tutorial app

For this tutorial, we have used our sample Android app as shown below. If you have your own existing Android app, you can integrate the ImageKit Android SDK into it, the instructions for which are provided in the subsequent sections.


```bash
git clone https://github.com/imagekit-samples/quickstart.git
```

Navigate to the cloned repository and open the `android` folder within the cloned repository in Android Studio.Run Gradle sync to install the dependencies specified for the sample Android app. 

After the sync is done successfully, you can run the app by selecting your target device/emulator and clicking on the Run button in Studio.

You should see the following screen. This means the sample app has been set up correctly.

![;width=400](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/android/app-homescreen.jpg>)

## Setup ImageKit Android SDK

You can integrate and use the ImageKit Android SDK in your own app by following these steps in your app project:

#### Installing the SDK

To install the SDK, add the following to the root-level `build.gradle`:
```gradle
allprojects {
    repositories {
       ...
        maven { url "https://jitpack.io" }
    }
}
```

And in the module-level `build.gradle`, add:
```gradle 
implementation 'com.github.imagekit-developer.imagekit-android:imagekit-android:<VERSION>'
```

#### Initializing the SDK

Initialize our SDK preferably in the `Application` class or any `Activity` as needed, with the following code:


```kotlin
// Kotlin
import com.imagekit.android.ImageKit

ImageKit.init(
    context = applicationContext,
    publicKey = "your_public_api_key",
    urlEndpoint = "https://ik.imagekit.io/your_imagekit_id",
    transformationPosition = TransformationPosition.PATH,
    defaultUploadPolicy = UploadPolicy.Builder()
        .requireNetworkType(UploadPolicy.NetworkType.ANY)
        .setMaxRetries(3)
        .build()
)
```

```java
// Java
import com.imagekit.android.ImageKit;

ImageKit.Companion.init(
    getApplicationContext(),
    "your_public_api_key",
    "https://ik.imagekit.io/your_imagekit_id",
    TransformationPosition.PATH,
    UploadPolicy.Builder()
        .requireNetworkType(UploadPolicy.NetworkType.ANY)
        .setMaxRetries(3)
        .build()
);
```

* `urlEndpoint` is the required parameter. You can get the value of the URL endpoint from your ImageKit dashboard - [https://imagekit.io/dashboard/url-endpoints](https://imagekit.io/dashboard/url-endpoints).
* `publicKey` is an optional parameter and is only needed if you want to use the SDK for client-side file upload. You can get the public key from the developer section in your ImageKit dashboard - [https://imagekit.io/dashboard/developer/api-keys](https://imagekit.io/dashboard/developer/api-keys).

* `transformationPosition` is optional. The default value for this parameter is `TransformationPosition.PATH`. Acceptable values are `TransformationPosition.PATH` & `TransformationPosition.QUERY`.

* `defaultUploadPolicy` is optional and only needed if you want to use the SDK for client-side file upload. This sets the default constraints for all the upload requests.

## Rendering Images in Android application

Image URLs can be created from an image path or using the absolute image URL. You can learn more about it in [docs](https://github.com/imagekit-developer/imagekit-android?tab=readme-ov-file#url-construction).

To render an image using an absolute URL (full image URL), we can instantiate the `ImageKitUrlConstructor`.

```kotlin
// https://ik.imagekit.io/your_imagekit_id/medium_cafe_B1iTdD0C.jpg
ImageKit.getInstance()
    .url(
        src = "https://ik.imagekit.io/your_imagekit_id/medium_cafe_B1iTdD0C.jpg",
        transformationPosition = TransformationPosition.PATH
    )
    .create()
```

To create a URL from the image path, we can instantiate the `ImageKitURLConstructor` which takes the URL endpoint, image path, and transformation position as parameters to create the transformed url.


```kotlin
// https://ik.imagekit.io/your_imagekit_id/default-image.jpg
ImageKit.getInstance()
    .url(
        path = "default-image.jpg",
        transformationPosition = TransformationPosition.QUERY
    )
    .create()
```

{% callout style="info" %}
The transformation position (path or query) is only valid when creating a URL from the image path. Transformations are always added as query parameters if the URL is created from an absolute image path using src.
{% /callout %}

The Android SDK provides a [function](https://github.com/imagekit-developer/imagekit-Android#list-of-supported-transformations) for each transformation parameter, making the code simpler and readable. To add transformations, the functions can be chained with the `ImagekitUrlConstructor` instance.

```kotlin
val urlConstructor = ImageKit.getInstance()
    .url(
        path = "default-image.jpg",
        transformationPosition = TransformationPosition.QUERY
    )
    .height(400)
    .aspectRatio(3, 2)
```

Finally, once all the required transformations are defined, call the `create` function to get the final transformed URL

```kotlin
val url = urlConstructor.create()
// https://ik.imagekit.io/your_imagekit_id/default-image.jpg?tr=h-400,ar-3-2
```

It will look like the picture below. The buttons are present in the sample app to demonstrate the use of different transformations. 

![;width=400](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/android/fetch-images-h-400-ar-3-2.jpg>)

We can also use the [extensions](#extensions-for-third-party-libraries) for the `ImagekitUrlConstructor` to create the image URLs with the image request objects from image loading libraries like Glide, Coil, Picasso etc.

## Common image manipulation in Android application

This section covers the basics:‌

* ​Basic image resizing
* Crop Mode
* ​Aspect Ratio
* ​Chained transformation

ImageKit Android SDK provides a function  to each transformation parameter e.g. `height` for `h` and `width` for `w` parameter. It makes your code more readable. See the [full list of supported transformations](https://github.com/imagekit-developer/imagekit-android#list-of-supported-transformations) in Android SDK on Github.

The complete list of transformations supported and their usage in ImageKit can be found [here](/image-transformation). If a transformation is supported in ImageKit, but if a name for it cannot be found in the SDK, then use the `addCustomTransformation` function and pass the transformation code from ImageKit docs as the first parameter and value as the second parameter. For example - `.addCustomTransformation("w", "400").`

### Basic image resizing <a href="basic-image-resizing" id="basic-image-resizing"></a>

Let's resize the image to a height of 150px and a width of 150px.

```kotlin
val url = ImageKit.getInstance()
    .url(
        path = "default-image.jpg",
        transformationPosition = TransformationPosition.QUERY
    )
    .height(150)
    .width(150)
    .create()
```

Output:

![;width=400](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/android/fetch-images-h-150-w-150.jpg>)


### Crop mode

Let’s now see how different crop mode works. We will try the [`pad_resize`](/image-resize-and-crop#crop-resize-crop-strategy---cm-pad_resize) crop strategy. In this strategy, the output image's dimension (height and width) is the same as requested, no cropping occurs, and the aspect ratio is preserved. This is accomplished by adding padding around the output image to get it to match the exact dimension as requested. You can read more about this [here](/image-resize-and-crop#crop-crop-modes--focus).

```kotlin
val url = ImageKit.getInstance()
    .url(
        path = "default-image.jpg",
        transformationPosition = TransformationPosition.QUERY
    )
    .height(300)
    .width(200)
    .cropMode(CropMode.PAD_RESIZE)
    .background("F1F1F1")
    .create()
```

Output:

![;width=400](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/android/fetch-images-h-300-w-200-cm-pad_resize-bg-f1f1f1.jpg>)

### Aspect ratio

You can use the [ar parameter](/image-resize-and-crop#aspect-ratio---ar) to change the aspect ratio like this:

```kotlin
val url = ImageKit.getInstance()
    .url(
        path = "default-image.jpg",
        transformationPosition = TransformationPosition.QUERY
    )
    .height(600)
    .aspectRatio(3, 2)
    .create()
```

Output:

![;width=400](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/android/fetch-images-h-600-ar-3-2.jpg>)

### Chained transformation

[Chained transformations](/transformations#chained-transformations) provide a simple way to control the sequence in which transformations are applied.

Let’s try it out by resizing an image, then [rotating](/effects-and-enhancements#rotate---rt) it:

```kotlin
val url = ImageKit.getInstance()
    .url(
        path = "default-image.jpg",
        transformationPosition = TransformationPosition.QUERY
    )
    .height(400)
    .width(300)
    .chainTransformation()
    .aspectRatio(3, 2)
    .rotation(Rotation.VALUE_90)
    .create()
```

Output:

![;width=400](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/android/fetch-images-h-400-w-300-ar-3-2-rt-90.jpg>)

## Client-side file uploading

Let's learn how to upload an image to our media library.

Android SDK provides `ImageKitUploader`, which provides functions to allow files to be uploaded to the [ImageKit media library](/dam/overview/) directly from the client side.

To use upload functionality, we need to pass `publicKey` while [initializing the SDK](#setup-imagekit-android-sdk), and pass the client-generated JSON Web Token (JWT) in the upload method, which the ImageKit.io server uses to authenticate and check that the upload request parameters have not been tampered with after the generation of the token. Refer this [guide](/api-reference/upload-file/upload-file-v2#how-to-implement-secure-client-side-file-upload) to create the token.

```kotlin
ImageKit.init(
    publicKey: "your_public_api_key", //Replace this with the public API key from your ImageKit account
    urlEndpoint: "your_url_endpoint", //Replace this with the URL endpoint for your ImageKit account
    transformationPosition: TransformationPosition.PATH, 
)
```

For this, we would need a dummy backend app to authenticate our upload request. API authentication for upload always happens on the backend for security reasons.

The tutorial repository comes with a sample backend server that we can use.

### Setting up the backend app

For this quick start guide, we have provided the sample implementation of the authentication endpoint using [jsonwebtoken](https://www.npmjs.com/package/jsonwebtoken) and [Express](https://expressjs.com).

In a new terminal window, navigate to the `Server` folder inside the tutorial project and install its npm packages:

```bash
cd Server/
npm install
```

Let's modify `index.js` to implement `http://localhost:8080/auth`, which is our `authenticationEndpoint`.

```javascript
/* 
    This is our backend server.
    Replace your_url_endpoint, your_public_key, your_private_key 
    with actual values
*/
const express = require('express');
const jwt = require('jsonwebtoken');
const app = express();
const cors = require('cors');

app.use(cors());
app.use(express.json());

const publicKey = "your_public_key";
const privateKey = "your_private_key";

app.post("/auth", function (req, res) {
  const token = jwt.sign(
    req.body.uploadPayload,
    privateKey,
    {
      expiresIn: req.body.expire,
      header: {
        alg: "HS256",
        typ: "JWT",
        kid: publicKey,
      },
    })
  res.status(200);
  res.send({ token });
});

app.listen(8080, function () {
  console.log("Live at Port 8080");
});
```

Finally, run the backend app.

```bash
node index.js
```

You should see a log line saying that the app is _**“Live on port 8080”**_.

If you run the following command in the terminal

```shell
curl -L 'localhost:8080/auth' -H 'Content-Type: application/json' -d '{
    "uploadPayload":{
        "filename": "image.jpg",
        "folder": "/"
    },
    "expire": 60
}'
```

You should see a JSON response like this, which contains the JWT token. Actual values will vary.

```javascript
{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InRlc3QifQ.eyJmaWxlbmFtZSI6ImltYWdlLmpwZyIsImZvbGRlciI6Ii8iLCJpYXQiOjE3MTg2OTUwNzUsImV4cCI6MTcxODY5NTEzNX0.HN_0gHfI26drmFGHmIiZuLnz21nzz6VpTuRWUi4Ljno"
}
```

You can use [JWT Debugger](https://jwt.io/) to decode and verify that the token is correctly generated.

![](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/android/jwt.png>)

**Configure the auth endpoint in the frontend app**

Head over to `Constants.kt` and ensure the `AUTH_SERVER_BASE_URL` is set to `http://localhost:8080` and `AUTH_API_ENDPOINT` is set to `/auth`.


### Upload a file

To upload an image to the media library, the ImageKit Android SDK provides `ImageKitUploader` . For complete API reference for the image upload function, check out the [docs](https://github.com/imagekit-developer/imagekit-Android#file-upload) on the ImageKit Android Git Repository.

The `ImageKit.getInstance().uploader().upload` function can ingest files through `Bitmap`, `File` or URL of a remote image.

```kotlin
ImageKit.getInstance().uploader().upload(
    file = image,
    token = "UPLOAD_JWT" //Replace this with the JWT returned by your custom auth server
    fileName = "sample-image.jpg",
    useUniqueFilename = true,
    tags = ["demo"],
    folder = "/",
    isPrivateFile =  false,
    customCoordinates = "",
    responseFields = "",
    extensions = listOf(mapOf("name" to "google-auto-tagging", "minConfidence" to 80, "maxTags" to 10)),
    webhookUrl = "https://abc.xyz",
    overwriteFile = false,
    overwriteAITags = true,
    overwriteTags = true,
    overwriteCustomMetadata = true,
    customMetadata = mapOf("SKU" to "VS882HJ2JD", "price" to 599.99, "brand" to "H&M"),
    imageKitCallback = object: ImageKitCallback {
        override fun onSuccess(uploadResponse: UploadResponse) {
            // Handle Success Response
        }
        override fun onError(uploadError: UploadError) {
            // Handle Upload Error
        }
    }
)
```

After a successful upload, you should see the newly uploaded file in the [Media Library](http://dev.imagekit.io/dashboard#media-library) of your ImageKit dashboard.

If you don't see the file, check if there are any errors in the error log. Make sure that the private API key has been configured. The server app is running. And the uploaded file type is [supported](../../api-reference/upload-file-api/#allowed-file-types-for-uploading) by ImageKit.

## Setting an upload policy

The [UploadPolicy](https://github.com/imagekit-developer/imagekit-android/blob/master/README.md#uploadpolicy) class represents a set of conditions that need to be met for an upload request to be executed. This policy is useful in various cases, like constraining large uploads to be performed only when the specified network and battery conditions are satisfied, and to control the retry mechanism for failed upload requests.

`UploadPolicy.Builder` class is responsible for building the `UploadPolicy` instances. You can set a default upload policy for all uploads while instantiating the SDK, e. g.:

```kotlin
ImageKit.init(
    context = applicationContext,
    publicKey = "your_public_api_key",
    urlEndpoint = "https://ik.imagekit.io/your_imagekit_id",
    transformationPosition = TransformationPosition.PATH,
    defaultUploadPolicy = UploadPolicy.Builder()
        .requireNetworkType(UploadPolicy.NetworkType.ANY)
        .setMaxRetries(3)
        .build()
)
```

And you can pass a custom upload policy in the `upload()` method to override the default policy for a particular upload, e. g.:

```kotlin
ImageKit.getInstance().uploader().upload(
    file = image,
    fileName = "sample-image.jpg",
    useUniqueFilename = true,
    policy = UploadPolicy.Builder()
        .requireNetworkType(UploadPolicy.NetworkType.UNMETERED)
        .setMaxRetries(4)
        .build(),
    imageKitCallback = object: ImageKitCallback {
        override fun onSuccess(uploadResponse: UploadResponse) {
            // Handle Success Response
        }
        override fun onError(uploadError: UploadError) {
            // Handle Upload Error
        }
    }
)
```

## How to preprocess your files before uploading

The `ImageKitUploader` can also perform the preprocessing of the image/video to modify them before uploading, by passing an instance of [ImageUploadPreprocessor](https://github.com/imagekit-developer/imagekit-android/blob/master/README.md#image-preprocessing)/[VideoUploadPreprocessor](https://github.com/imagekit-developer/imagekit-android/blob/master/README.md#video-preprocessing). These preprocessors can be useful for certain use cases, e.g:

- Modifying the media size and/or quality, to perhaps optimize the use of ImageKit storage.
- Applying certain media transformations from within the app, like when using an image editing feature of the app.

Currently, following transformations can be applied by upload preprocessors:

- Images:
    - Limiting width & height
    - Rotation
    - Crop
    - Format selection
- Videos:
    - Limiting width & height
    - Frame rate
    - A/V bitrate
    - Keyframes interval

Sample Usage
```kotlin
ImageKit.getInstance().uploader().upload(
    file = image,
    fileName = "sample-image.jpg",
    useUniqueFilename = true,
    tags = ["demo"],
    preprocessor = ImageUploadPreprocessor.Builder()
        .limit(512, 512)
        .rotate(90f)
        .build(),
    imageKitCallback = object: ImageKitCallback {
        override fun onSuccess(uploadResponse: UploadResponse) {
            // Handle Success Response
        }
        override fun onError(uploadError: UploadError) {
            // Handle Upload Error
        }
    }
)
```

## Extensions for third-party libraries

ImageKit Android SDK also provides library extensions for integrations with the following image loading libraries for Android:

- [Glide](https://github.com/imagekit-developer/imagekit-android/blob/master/README.md#glide)
- [Picasso](https://github.com/imagekit-developer/imagekit-android/blob/master/README.md#picasso)
- [Coil](https://github.com/imagekit-developer/imagekit-android/blob/master/README.md#coil)
- [Fresco](https://github.com/imagekit-developer/imagekit-android/blob/master/README.md#fresco)


---

# Source: /integration/ios

---
title: iOS
description: >-
  Real-time image & video resizing, automatic optimization, and file uploading in
  iOS using ImageKit.io.
---

This quickstart guide shows you how to integrate ImageKit into an iOS application. The code samples covered are available on Github: [https://github.com/imagekit-samples/quickstart/tree/master/ios](https://github.com/imagekit-samples/quickstart/tree/master/ios).

This guide walks you through the following topics: ‌

* [Clone and run the tutorial app](#clone-and-run-the-tutorial-app)
* [Setting up ImageKit iOS SDK](#setup-imagekit-ios-sdk)
* [Rendering images](#rendering-images-in-ios-application)
* [Applying common image manipulations](#common-image-manipulation-in-ios-application)
* [Adding overlays to images](#adding-an-overlay-to-images-in-ios-application)
* [Client-side file uploading](#client-side-file-uploading)
* [Setting an upload policy](#setting-an-upload-policy)
* [How to preprocess your files before uploading](#how-to-preprocess-your-files-before-uploading)

## Clone and run the tutorial app

For this tutorial, it is recommended to use the sample iOS app, as shown below. If you already have an existing iOS app, it is also possible to use that, which will be explained in the continuation of the sample app.

```bash
git clone 
https://github.com/imagekit-samples/quickstart.git
```

Navigate to the cloned repository and install the dependencies that are needed to run the iOS app:

```bash
cd quickstart/ios/
pod install
```

{% callout style="warning" %}
If you do not have CocoaPods Installed on your Mac, you can learn about setting up the development environment here [https://guides.cocoapods.org/using/getting-started.html](https://guides.cocoapods.org/using/getting-started.html).
{% /callout %}

Once the dependencies have been installed, run the following command to open the Xcode Workspace:

```bash
open ImagekitDemo.xcodeworkspace
```

Select the emulator from the dropdown. Then run the app by clicking on the Run button or by pressing {% kbd %}⌘{% /kbd %} + {% kbd %}R{% /kbd %}.

![ImageKitDemo app in XCode](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/ios/xcode.png>)

You should see the following screen. This means the sample app has been set up correctly.

![ImageKitDemo app home screen;width=400](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/ios/sample.png>)

## Setup ImageKit iOS SDK

We will be installing [ImageKit iOS SDK](https://github.com/imagekit-developer/imagekit-ios) using [CocoaPods](https://guides.cocoapods.org/using/getting-started.html).

#### Initialising CocoaPods in your iOS Project

If you are not using CocoaPods in your project, you might need to add it to your project by either running `pod init` or adding PodFile ([see example](https://guides.cocoapods.org/using/using-cocoapods.html)) in the root directory of your project.

#### Installing the SDK

To Install the SDK, add the following to the PodFile.

```bash
# Required to enable the use of Dynamic Libraries
use_frameworks!

target 'target_name' do 
    ...
    # Add to your project target
    pod 'ImageKitIO', '~> 3.0.0'
    ...
end
```

#### Initializing the SDK

Open the `AppDelegate.swift` file. This is where we will initialize our SDK with the following parameters.

* `urlEndpoint` is the required parameter. You can get the value of the URL endpoint from your ImageKit dashboard - [https://imagekit.io/dashboard/url-endpoints](https://imagekit.io/dashboard/url-endpoints).
* `publicKey` is an optional parameter and is only needed if you want to use the SDK for client-side file upload. You can get the public key from the developer section in your ImageKit dashboard - [https://imagekit.io/dashboard/developer/api-keys](https://imagekit.io/dashboard/developer/api-keys).

```swift
ImageKit.init(
    publicKey: "your_public_api_key", 
    urlEndpoint: "https://ik.imagekit.io/your_imagekit_id", 
    transformationPosition: TransformationPosition.PATH
)
```

## Rendering Images in iOS application

Image URLs can be created from an image path or using the absolute image URL. You can learn more about it in [docs](https://github.com/imagekit-developer/imagekit-ios?tab=readme-ov-file#url-construction).

To render an image using an absolute URL (full image URL), we can instantiate the `ImageKitURLConstructor`

```swift
let urlConstructor = ImageKit.shared.url(
    src: "https://ik.imagekit.io/demo/default-image.jpg"
)
```

To create a URL from the image path, we can instantiate the `ImageKitURLConstructor`, which takes the URL endpoint, image path, and transformation position as parameters to create the transformed url.

```swift
let urlConstructor = ImageKit.shared.url(
    urlEndpoint: "https://ik.imagekit.io/demo",
    path: "default-image.jpg",
    transformationPosition: TransformationPosition.QUERY
)
```

{% callout style="info" %}
The transformation position (path or query) is only valid when creating a URL from the image path. Transformations are always added as query parameters if the URL is created from an absolute image path using src.
{% /callout %}

The iOS SDK provides a [function](https://github.com/imagekit-developer/imagekit-ios#list-of-supported-transformations) for each transformation parameter, making the code simpler and readable. To add transformations, the functions can be chained with `urlConstructor`.

```swift
urlConstructor = urlConstructor.height(height: 400)
urlConstructor = urlConstructor.aspectRatio(width: 3, height: 2)
```

Finally, once all the required transformations are defined, call the `create` function to get the final transformed URL

```swift
let url = urlConstructor.create()
// https://ik.imagekit.io/your_imagekit_id/default-image.jpg?tr=h-400,ar-3-2
```

It will look like the picture below. The buttons are present in the sample app to demonstrate the use of different transformations. 


![;width=400](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/ios/sample-url-1.png>)

## Common image manipulation in iOS application

This section covers the basics:‌

* ​Basic image resizing
* Crop Mode
* ​Aspect Ratio
* ​Chained transformation

ImageKit iOS SDK provides a function for each transformation parameter, e.g., `height` for `h` and `width` for the `w` parameter. It makes your code more readable. See the [full list of supported transformations](https://github.com/imagekit-developer/imagekit-ios#list-of-supported-transformations) in iOS SDK on Github.

The complete list of transformations supported and their usage in ImageKit can be found [here](/image-transformation). If a transformation is supported in ImageKit, but a name for it cannot be found in the SDK, then use the `addCustomTransformation` function and pass the transformation code from ImageKit docs as the first parameter and value as the second parameter. For example - `.addCustomTransformation("w", "400").`

### Basic image resizing

Let's resize the image to a height of 150px and a width of 150px.

```swift
urlConstructor = urlConstructor.height(height: 150)
urlConstructor = urlConstructor.width(width: 400)
let url = urlConstructor.create()
```

Output:

![;width=400](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/ios/sample-url-2.png>)

### Crop mode

Let’s now see how different crop modes work. We will try the [`pad_resize`](/image-resize-and-crop#crop-resize-crop-strategy---cm-pad_resize) crop strategy. In this strategy, the output image's dimension (height and width) is the same as requested, no cropping occurs, and the aspect ratio is preserved. This is accomplished by adding padding around the output image to get it to match the exact dimension as requested. You can read more about this [here](/image-resize-and-crop#crop-crop-modes--focus).

```swift
urlConstructor = urlConstructor.width(width: 300)
urlConstructor = urlConstructor.height(height: 200)
urlConstructor = urlConstructor.cropMode(cropMode: CropMode.PAD_RESIZE)
let url = urlConstructor.create()
```

Output:

![;width=400](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/ios/sample-url-3.png>)

### Aspect ratio

You can use the [ar parameter](/image-resize-and-crop#aspect-ratio---ar) to change the aspect ratio like this:

```swift
urlConstructor = urlConstructor.height(height: 400)
urlConstructor = urlConstructor.aspectRatio(width: 3, height: 2)
let url = urlConstructor.create()
```

Output:

![;width=400](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/ios/sample-url-1.png>)

### Chained transformation

[Chained transformations](/transformations#chained-transformations) provide a simple way to control the sequence in which transformations are applied.

Let’s try it out by resizing an image, then [rotating](/effects-and-enhancements#rotate---rt) it:

```swift
urlConstructor = urlConstructor.height(height: 400)
urlConstructor = urlConstructor.width(width: 300)
urlConstructor = urlConstructor.chainTransformation()
urlConstructor = urlConstructor.rotation(rotation: Rotation.VALUE_90)
let url = urlConstructor.create()
```

Output:

![;width=400](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/ios/sample-url-4.png>)

## Adding an overlay to images in iOS application

ImageKit.io allows you to add [text](/add-overlays-on-images#add-text-over-image) and [image](/add-overlays-on-images#add-images-over-image) dynamically using layers.

### Text overlay

Text overlay can be used to superimpose text on an image. Try it like so:

```swift
urlConstructor = urlConstructor.width(width: "400")
urlConstructor = urlConstructor.raw(params: "l-text,i-Hand%20with%20a%20green%20plant,co-264120,fs-30,lx-10,ly-20,l-end")
let url = urlConstructor.create()
```

Output:

![;width=400](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/ios/sample-url-5.png>)

### Image overlay

Image overlay can be used like this:

```swift
urlConstructor = urlConstructor.raw(params: "l-image,i-logo-white_SJwqB4Nfe.png,lx-10,ly-20,l-end")
let url = urlConstructor.create()
```

Output:

![;width=400](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/ios/sample-url-6.png>)

## Client-side file uploading

Let's learn how to upload an image to our media library.

iOS SDK provides `ImageKitUploader`, which provides functions to allow files to be uploaded to the [ImageKit media library](/dam/overview/) directly from the client side.

To use upload functionality, we need to pass `publicKey` while [initializing the SDK](#setup-imagekit-ios-sdk). 
Replace `your_url_endpoint` and `your_public_key` with actual values.

```bash
ImageKit.init(
    publicKey: "your_public_api_key", 
    urlEndpoint: "your_url_endpoint", 
    transformationPosition: TransformationPosition.PATH
)
```


For this, we would need a dummy backend app to authenticate our upload request. API authentication for upload always happens on the backend for security reasons.

The tutorial repository comes with a sample backend server that we can use.

### Setting up the backend app

For this quick start guide, we have provided the sample implementation of the authentication endpoint using [jsonwebtoken](https://www.npmjs.com/package/jsonwebtoken) and [Express](https://expressjs.com). Refer this [guide](/api-reference/upload-file/upload-file-v2#how-to-implement-secure-client-side-file-upload) to create the token.

In a new terminal window, navigate to the `Server` folder inside the tutorial project and install its npm packages:

```bash
cd Server/
npm install
```

Let's modify `index.js` to implement `http://localhost:8080/auth`, which is our `authenticationEndpoint`.

```javascript
/* 
    This is our backend server.
    Replace your_url_endpoint, your_public_key, your_private_key 
    with actual values
*/
const express = require('express');
const jwt = require('jsonwebtoken');
const app = express();
const cors = require('cors');

app.use(cors());
app.use(express.json());

const publicKey = "your_public_key";
const privateKey = "your_private_key";

app.post("/auth", function (req, res) {
  const token = jwt.sign(
    req.body.uploadPayload,
    privateKey,
    {
      expiresIn: req.body.expire,
      header: {
        alg: "HS256",
        typ: "JWT",
        kid: publicKey,
      },
    })
  res.status(200);
  res.send({ token });
});

app.listen(8080, function () {
  console.log("Live at Port 8080");
});
```

Finally, run the backend app.

```bash
node index.js
```

You should see a log line saying that the app is _**“Live on port 8080”**_.

If you run the following command in the terminal

```shell
curl -L 'localhost:8080/auth' -H 'Content-Type: application/json' -d '{
    "uploadPayload":{
        "filename": "image.jpg",
        "folder": "/"
    },
    "expire": 60
}'
```

You should see a JSON response like this, which contains the JWT token. Actual values will vary.

```javascript
{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InRlc3QifQ.eyJmaWxlbmFtZSI6ImltYWdlLmpwZyIsImZvbGRlciI6Ii8iLCJpYXQiOjE3MTg2OTUwNzUsImV4cCI6MTcxODY5NTEzNX0.HN_0gHfI26drmFGHmIiZuLnz21nzz6VpTuRWUi4Ljno"
}
```

You can use [JWT Debugger](https://jwt.io/) to decode and verify that the token is correctly generated.

![](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/ios/jwt.png>)

**Configure the auth endpoint in the frontend app**

Head over to `Constants.swift` and ensure the `AUTH_SERVER_API_ENDPOINT` is set to `http://localhost:8080/auth`

![](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/ios/xcode-constants.png>)

### Upload a file

To upload an image to the media library, the ImageKit iOS SDK provides `ImageKitUploader` . For complete API reference for the image upload function, check out the [docs](https://github.com/imagekit-developer/imagekit-ios#file-upload) on the ImageKit iOS Git Repository.

The `ImageKit.shared.uploader().upload` function can ingest files through `UIImage`, `NSData` or `Url of a remote image`

```bash
ImageKit.shared.uploader().upload(
  file: image,
  token: "your_jwt_token",
  fileName: "sample-image.jpg",
  useUniqueFilename: true,
  tags: ["demo"],
  folder: "/",
  isPrivateFile: false,
  customCoordinates: "",
  responseFields: "",
  overwriteFile: false,
  overwriteAITags: false,
  overwriteTags: false,
  overwriteCustomMetadata: false,
  // Custom metadata must be defined in the Media Library before using it in the upload API
  // customMetadata: "{\"device_name\":\"iPhone 15\",\"location\":\"New York\"}",
  progress: { progress in
  	// Handle Progress
  },
  policy: UploadPolicy,
  preProcessor: UploadPreprocessor,
  completion: { result in 
  	 switch result{
            case .success(let uploadAPIResponse):
                // Handle Success Response
            case .failure(let error as UploadAPIError):
                // Handle Upload Error
            case .failure(let error):
                // Handle Other Errors
      }
  }
)
```

After a successful upload, you should see the newly uploaded file in the [Media Library](http://imagekit.io/dashboard#media-library) of your ImageKit dashboard.

If you don't see the file, 
- Check if there are any errors in the error log. 
- Make sure that the private API key has been configured. 
- The server app is running.

## Setting an upload policy

The [UploadPolicy](https://github.com/imagekit-developer/imagekit-ios/blob/master/README.md#uploadpolicy) class represents a set of conditions that need to be met for an upload request to be executed. This policy is useful in various cases, like constraining large uploads to be performed only when the specified network and battery conditions are satisfied and controlling the retry mechanism for failed upload requests.

`UploadPolicy.Builder` class is responsible for building the `UploadPolicy` instances.

```swift
/*
 * Upload policy to upload files only 
 *  - when the network is unmetered
 *  - the device doesn't require charging
 *  - retry 4 times with exponential backoff starting at 500ms
*/

let uploadPolicy = UploadPolicy.Builder()
  .requireNetworkType(.UNMETERED)
  .requiresBatteryCharging(false)
  .maxRetries(4)
  .backoffCriteria(backoffMillis: 500, backoffPolicy: .EXPONENTIAL)
  .build()
```

## How to preprocess your files before uploading

The ImageKit iOS SDK provides a way to preprocess files before uploading them to the media library. 

The `ImageKitUploader` can perform the preprocessing of the image/video to modify them before uploading by passing an instance of `UploadPreprocessor`. For complete API reference for the upload preprocessor, check out the [docs](https://github.com/imagekit-developer/imagekit-ios?tab=readme-ov-file#upload-preprocessing)

These preprocessors can be useful for certain use cases, e.g:

- Modifying the media size and/or quality to optimize the use of ImageKit storage.
- Apply certain media transformations from within the app, like when using an image editing feature.

The SDK features two built-in preprocessors:

- [`ImageUploadPreprocessor`](https://github.com/imagekit-developer/imagekit-ios/blob/master/README.md#image-preprocessing): This preprocessor is used to apply transformations to images before uploading them to the media library. The transformations that can be applied are:
    - Limiting width & height
    - Rotation
    - Crop
    - Format selection

```swift
let preprocessor = ImageUploadPreprocessor.Builder()
   .limit(width: 400, height: 300)
   .rotate(degrees: 45)
   .format(format: .JPEG)
   .build()
```

- [`VideoUploadPreprocessor`](https://github.com/imagekit-developer/imagekit-ios/blob/master/README.md#image-preprocessing): This preprocessor is used to apply transformations to videos before uploading them to the media library. The transformations that can be applied are:
    - Limiting width & height
    - Frame rate
    - A/V bitrate
    - Keyframes interval

```swift
let preprocessor = VideoUploadPreprocessor.Builder()
   .limit(width: 800, height: 600)
   .frameRate(frameRateValue: 60)
   .keyFramesInterval(interval: 6)
   .targetVideoBitrateKbps(targetVideoBitrateKbps: 480)
   .targetAudioBitrateKbps(targetAudioBitrateKbps: 320)
   .build(),
```


---

# Source: /integration/react-native

---
title: React Native
description: >-
  Real-time image & video resizing, automatic optimization, and file uploading in React
  Native using ImageKit.io.
---

This is a quick start guide to show how to integrate ImageKit in a React Native application using the [ImageKit Javascript SDK](https://github.com/imagekit-developer/imagekit-javascript). The [code samples](https://github.com/imagekit-samples/quickstart/tree/master/react-native) covered here are hosted on Github.

This guide walks you through the following topics:

* [Setting up React Native app](#setting-up-react-native-app)
* [Setting up ImageKit JavaScript SDK](#setting-up-imagekit-javascript-sdk)
* [Rendering Images](#rendering-images)
* [Applying common image manipulations](#common-image-manipulation)
* [Adding overlays](#adding-overlays)
* [Client-side file uploading](#client-side-file-uploading)
* [Rendering videos](#rendering-videos)

{% callout style="info" %}
If you are new to React Native app development, you can learn about setting up the development environment and creating a new project here [https://reactnative.dev/docs/environment-setup](https://reactnative.dev/docs/environment-setup).
{% /callout %}

## Setting up React Native app

For this tutorial, it is recommended to use the sample React Native app as shown below. If you already have an existing React Native app, it is also possible to use that, although you would need to modify the terminal commands and configurations in this tutorial as applicable.

Let's use the `react-native-cli` package to build a new project:

```bash
npx react-native@latest init imagekitReactNative
```

Navigate to the project directory:

```bash
cd imagekitReactNative/
```

Start the metro server.

```bash
npx react-native start
```

And now to run the app in the iOS simulator (you should have Xcode installed)

```bash
npm run ios
```

Or to run the app in the android simulator (you should have android studio installed)

```bash
npm run android
```

You should see the following screen. This means the sample app has been set up correctly.

![React Native Initial Screen;width=400](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/react-native-initial.PNG)


### Let's configure the components required for the application.

Execute the provided command to install the packages required for the application.

```bash
npm install @react-navigation/native @react-navigation/stack react-native-gesture-handler react-native-safe-area-context react-native-screens
```

{% callout style="info" %}
In the sample app, we are using our own custom `Button` component created using React Native's components to ensure consistency.
{% /callout %}

{% linetabs %}
{% linetab title="app/components/Button/index.js" %} 

```js
import React from 'react';
import {Text, TouchableOpacity} from 'react-native';
import getStyleSheet from './styles';

function Button(props) {
  let styleSheet = getStyleSheet(props.cssProps || {});
  return (
    <TouchableOpacity onPress={props.onPress} style={styleSheet.button}>
      <Text style={styleSheet.text}>{props.children}</Text>
    </TouchableOpacity>
  );
}

export default Button;
```

{% /linetab %}
{% linetab title="app/components/Button/styles.js" %}

```js
import {StyleSheet} from 'react-native';

function getStyleSheet(cssProps) {
  return StyleSheet.create({
    button: {
      height: 40,
      width: cssProps.width || 100,
      backgroundColor: 'dodgerblue',
      justifyContent: 'center',
      alignItems: 'center',
    },
    text: {
      color: cssProps.textColor || 'white',
      fontSize: 15,
      marginLeft: 10,
      marginRight: 10,
    },
  });
}

export default getStyleSheet;
```

{% /linetab %}
{% /linetabs %}

Create `index.js` and `styles.js` files within the `app/screens/Main` directory. These files will render & style buttons facilitating navigation to different screens, which will be developed in the subsequent sections. This configuration serves as our home screen.

{% linetabs %}
{% linetab title="app/screens/Main/index.js" %} 

```js
import React from 'react';
import {View, Text} from 'react-native';
import Button from '../../components/Button/';
import getStyleSheet from './styles';

function Main({navigation}) {
  let styleSheet = getStyleSheet({});

  return (
    <>
      <View style={styleSheet.headContainer}>
        <Text style={styleSheet.text}>Imagekit Demo</Text>
      </View>
      <View style={styleSheet.btnContainer}>
        <View style={styleSheet.btnView}>
          <Button
            cssProps={styleSheet.buttonCssProps}
            onPress={() => navigation.navigate('Upload File')}>
            Upload File
          </Button>
        </View>
        <View style={styleSheet.btnView}>
          <Button
            cssProps={styleSheet.buttonCssProps}
            onPress={() => navigation.navigate('Fetch Images')}>
            Fetch Images
          </Button>
        </View>
        <View style={styleSheet.btnView}>
          <Button
            cssProps={styleSheet.buttonCssProps}
            onPress={() => navigation.navigate('Fetch Videos')}>
            Fetch Videos
          </Button>
        </View>
      </View>
    </>
  );
}

export default Main;
```

{% /linetab %}
{% linetab title="app/screens/Main/styles.js" %}

```js
import {StyleSheet} from 'react-native';

function getStyleSheet() {
  return StyleSheet.create({
    headContainer: {
      flex: 1,
      alignItems: 'center',
      justifyContent: 'center',
    },
    btnContainer: {
      flex: 4,
      alignItems: 'center',
      justifyContent: 'flex-start',
    },
    btnView: {
      marginTop: 10,
      marginBottom: 10,
    },
    buttonCssProps: {
      width: 300,
    },
    text: {
      color: 'black',
      fontSize: 30,
      marginLeft: 10,
      marginRight: 10,
    },
  });
}

export default getStyleSheet;
```

{% /linetab %}
{% /linetabs %}


Create the `AppComponent.js` file within the `app` directory which will contain the screens. Add the home screen.
Open the `App.tsx` file and add the provided code to render the `AppComponent`.

{% linetabs %}

{% linetab title="app/AppComponent.js" %}

```js
import React from 'react';
import {createStackNavigator} from '@react-navigation/stack';
import Main from './screens/Main';

const Stack = createStackNavigator();

function AppComponent() {
  return (
    <Stack.Navigator>
      <Stack.Screen name="Home" component={Main} />
    </Stack.Navigator>
  );
}
export default AppComponent;
```

{% /linetab %}
{% linetab title="App.tsx" %}

```js
import 'react-native-gesture-handler';
import 'react-native-url-polyfill/auto';
import React from 'react';
import {SafeAreaView} from 'react-native';
import {NavigationContainer} from '@react-navigation/native';
import AppComponent from './app/AppComponent';

function App() {
  return (
    <SafeAreaView style={{flex: 1}}>
      <NavigationContainer>
        <AppComponent />
      </NavigationContainer>
    </SafeAreaView>
  );
}

export default App;
```

{% /linetab %}
{% /linetabs %}

It will look as shown below.

![React Native Home Screen;width=400](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/react-native-home.PNG)

## Setting up ImageKit JavaScript SDK

We will be using [ImageKit JavaScript SDK](https://github.com/imagekit-developer/imagekit-javascript). So let's install it.

```bash
npm install imagekit-javascript
```

{% callout style="warning" %}
`imagekit-javascript` SDK uses [URL API](https://developer.mozilla.org/en-US/docs/Web/API/URL) to parse the URL internally. In React 16 and above, this API was [removed](https://github.com/facebook/react-native/issues/16434), so if you are using React 16 or above, you will have to implement a small [patch](https://github.com/facebook/react-native/issues/16434#issuecomment-557956079) with these steps.

1. Install the package with `npm install react-native-url-polyfill`
2. Import the package in your app's entry point i.e. App.js like this `import 'react-native-url-polyfill/auto'`
{% /callout %}

#### Initializing the SDK

Create `app/lib/imagekit.js` file, this is where we will initialize our SDK and create helper functions that will be used in the app.

* `urlEndpoint` is the required parameter. You can get the value of URL endpoint from your ImageKit dashboard - [https://imagekit.io/dashboard/url-endpoints](https://imagekit.io/dashboard/url-endpoints).
* `publicKey` and `authenticationEndpoint` parameters are optional and only needed if you want to use the SDK for client-side file upload. You can get these parameters from the developer section in your ImageKit dashboard - [https://imagekit.io/dashboard/developer/api-keys](https://imagekit.io/dashboard/developer/api-keys).

Also initialize the SDK with parameters set in the config file `app/config/imagekit.js`

{% linetabs %}
{% linetab title="app/config/imagekit.js" %} 

```js
module.exports.urlEndpoint = ''; //insert your own url end point here
module.exports.publicKey = ''; //insert your own public key here
module.exports.authenticationEndpoint = ''; //your auth api path
```

{% /linetab %}
{% linetab title="app/lib/imagekit.js" %}

```javascript
import ImageKit from 'imagekit-javascript';
import {
  urlEndpoint,
  publicKey,
  authenticationEndpoint,
} from '../config/imagekit';

const imagekitConfigOptions = {urlEndpoint};
if (publicKey) imagekitConfigOptions.publicKey = publicKey;
if (authenticationEndpoint)
  imagekitConfigOptions.authenticationEndpoint = authenticationEndpoint;

const imagekit = new ImageKit(imagekitConfigOptions);
```

{% /linetab %}
{% /linetabs %}

## Rendering Images

Image URL can be created from an image path or using the absolute image URL. You can learn more about it in [docs](https://github.com/imagekit-developer/imagekit-javascript#url-generation).

To create a URL from the image source (full image URL), we can create a function like this, which takes the image source and a transformation array and returns the transformed image URL.


```javascript
module.exports.getImagekitUrlFromSrc = function (imageSrc, transformationArray) {
  const ikOptions = {
    src: imageSrc,
    transformation: transformationArray,
  };
  const imageURL = imagekit.url(ikOptions);

  return imageURL;
};
```


To create a URL from the image path, we can create a helper function like this below.


```javascript
module.exports.getImagekitUrlFromPath = function (
  imagePath,
  transformationArray,
  transformationPostion,
) {
  const ikOptions = {
    urlEndpoint,
    path: imagePath,
    transformation: transformationArray,
  };
  if (transformationPostion)
    ikOptions.transformationPostion = transformationPostion;

  const imageURL = imagekit.url(ikOptions);

  return imageURL;
};
```


{% callout style="info" %}
The transformation position (path or query) is only valid when creating a URL from the image path. Transformations are always added as query parameters if the URL is created from an absolute image path using **src**.
{% /callout %}

Now, let's create `app/screens/Fetch/index.js` to fetch an image. Also, update `app/AppComponent.js` to include the fetch image screen.

{% linetabs %}
{% linetab title="app/AppComponent.js" %}

```js
import React from 'react';
import {createStackNavigator} from '@react-navigation/stack';

import Main from './screens/Main';
import Fetch from './screens/Fetch';

const Stack = createStackNavigator();

function AppComponent() {
  return (
    <Stack.Navigator>
      <Stack.Screen name="Home" component={Main} />
      <Stack.Screen name="Fetch Images" component={Fetch} />
    </Stack.Navigator>
  );
}

export default AppComponent;
```

{% /linetab %}
{% linetab title="app/screens/Fetch/index.js" %}

```javascript
import React, {useState, useEffect} from 'react';
import {View, Text, Image} from 'react-native';

import Button from '../../components/Button/';
import getStyleSheet from './styles';

import {
  getImagekitUrlFromSrc,
  getImagekitUrlFromPath,
} from '../../lib/imagekit';
import {urlEndpoint} from '../../config/imagekit';

function Fetch() {
  let styleSheet = getStyleSheet({});

  const imagePath = '/default.jpg';
  let imageSrc = urlEndpoint + imagePath;

  const [imageUrl, setImageUrl] = useState();
  const [currentTr, setCurrentTr] = useState();
  const [imageDimesions, setImageDimensions] = useState();

  useEffect(() => {
    currentTr == 'Transformation 1'
      ? setImageDimensions({height: 150, width: 150})
      : setImageDimensions({height: 300, width: 300});
    showTransformedImage(currentTr);
  }, [currentTr]);

  function showTransformedImage(transformationType) {
    let transformationArray = [];
    let transformedImageUrl;

    switch (transformationType) {
      case 'Transformation 1': //basic image resizing
        transformationArray = [
          {
            height: 150,
            width: 150,
          },
        ];
        transformedImageUrl = getImagekitUrlFromSrc(
          imageSrc,
          transformationArray,
        );
        break;

      case 'Transformation 2': //crop mode and url from source
        imageSrc = 'https://ik.imagekit.io/demo/img/plant.jpeg';
        transformationArray = [
          {
            height: 300,
            width: 300,
            cropMode: 'pad_resize',
            background: '435EDA',
          },
        ];
        transformedImageUrl = getImagekitUrlFromSrc(
          imageSrc,
          transformationArray,
        );
        break;

      case 'Transformation 3': //aspect ratio and url from path and transformations as query param
        transformationArray = [
          {
            height: 400,
            aspectRatio: '3-2',
          },
        ];
        transformedImageUrl = getImagekitUrlFromPath(
          imagePath,
          transformationArray,
          'query',
        );
        break;

      case 'Transformation 4': //overlay image with x,y and its height
        transformationArray = [
          {
            raw: 'l-image,i-plant.jpeg,h-100,b-10_CDDC39,l-end',
          },
        ];
        transformedImageUrl = getImagekitUrlFromPath(
          imagePath,
          transformationArray,
        );
        break;

      case 'Transformation 5': //overlay text example
        transformationArray = [
          {
            raw: 'l-text,i-Imagekit,co-0651D5,fs-50,l-end',
          },
        ];
        transformedImageUrl = getImagekitUrlFromSrc(
          imageSrc,
          transformationArray,
        );
        break;

      case 'Transformation 6': //chained transformation
        transformationArray = [
          {
            height: 300,
            width: 300,
          },
          {
            rotation: '90',
          },
        ];
        transformedImageUrl = getImagekitUrlFromSrc(
          imageSrc,
          transformationArray,
        );
        break;

      default:
        transformedImageUrl = getImagekitUrlFromSrc(imageSrc, []);
        break;
    }

    setImageUrl(transformedImageUrl);
  }

  return (
    <>
      <View style={styleSheet.btnContainer}>
        <View style={styleSheet.btnView}>
          <Button
            cssProps={styleSheet.buttonCssProps}
            onPress={() => setCurrentTr('Transformation 1')}>
            Transformation 1
          </Button>
          <Button
            cssProps={styleSheet.buttonCssProps}
            onPress={() => setCurrentTr('Transformation 2')}>
            Transformation 2
          </Button>
        </View>
        <View style={styleSheet.btnView}>
          <Button
            cssProps={styleSheet.buttonCssProps}
            onPress={() => setCurrentTr('Transformation 3')}>
            Transformation 3
          </Button>
          <Button
            cssProps={styleSheet.buttonCssProps}
            onPress={() => setCurrentTr('Transformation 4')}>
            Transformation 4
          </Button>
        </View>
        <View style={styleSheet.btnView}>
          <Button
            cssProps={styleSheet.buttonCssProps}
            onPress={() => setCurrentTr('Transformation 5')}>
            Transformation 5
          </Button>
          <Button
            cssProps={styleSheet.buttonCssProps}
            onPress={() => setCurrentTr('Transformation 6')}>
            Transformation 6
          </Button>
        </View>
      </View>

      <View style={styleSheet.imgContainer}>
        {imageUrl && (
          <>
            <Image
              source={{uri: imageUrl}}
              style={{
                width: imageDimesions.width,
                height: imageDimesions.height,
              }}
            />
            <View style={styleSheet.captionView}>
              {currentTr ? (
                <Text style={styleSheet.text}>{currentTr}</Text>
              ) : (
                <Text style={styleSheet.text}>
                  Image with no Transformation
                </Text>
              )}
            </View>
            <View style={styleSheet.captionView}>
              <Text style={styleSheet.text}>Rendered URL - {imageUrl}</Text>
            </View>
          </>
        )}
      </View>
    </>
  );
}

export default Fetch;
```

{% /linetab %}
{% /linetabs %}

It will look as shown below. In the sample app, the buttons are present to demonstrate the use of different transformations. You can see the full list of supported transformations [here](https://github.com/imagekit-developer/imagekit-javascript#list-of-supported-transformations).

![React Native without transformation;width=400](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/react-nativet0.PNG)

## Common Image Manipulation

This section covers the basics:‌

* ​[Basic Image Resizing](#basic-image-resizing)
* [Crop Mode](#crop-mode)
* ​[Aspect Ratio](#aspect-ratio)
* ​[Chained transformation](#chained-transformation)

ImageKit JavaScript SDK gives a name to each transformation parameter e.g. `height` for `h` and `width` for `w` parameter. It makes your code more readable. If the property does not match any of the available options, it is added as it is. See the [full list of supported transformations](https://github.com/imagekit-developer/imagekit-javascript?tab=readme-ov-file#list-of-supported-transformations) in Javascript SDK on Github.

{% callout style="info" %}
You can also use `h` and `w` parameter instead of `height` and `width`.
{% /callout %}

### Basic Image Resizing

Let's resize the image to a height of 150 and a width of 150.

Note: You'll need to specify height and width in the Image component of react-native accordingly as we are fetching the image from a remote URL.


```javascript
function showTransformedImage() {
  let transformedImageUrl = getImagekitUrlFromSrc(imageSrc, [
    {
      height: 150,
      width: 150,
    },
  ]);
  setImageUrl(transformedImageUrl);
}
```


Output:

![React Native Basic Image Resizing;width=400](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/react-nativet1.PNG)

### Crop Mode

Let’s now see how crop mode works. We will try the [`pad_resize`](/image-resize-and-crop#pad-resize-crop-strategy---cm-pad_resize) crop strategy.

In this strategy, the output image's dimension (height and width) is the same as requested, no cropping occurs, and the aspect ratio is preserved. This is accomplished by adding padding around the output image to get it to match the exact dimension as requested.


```javascript
function showTransformedImage() {
  let transformedImageUrl = getImagekitUrlFromSrc(imageSrc, [
    {
      height: 200,
      width: 300,
      cropMode: 'pad_resize',
      background: 'F3F3F3',
    },
  ]);
  setImageUrl(transformedImageUrl);
}
```


Output:

![React Native crop mode;width=400](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/react-nativet2.PNG)

### Aspect Ratio

You can use the [ar parameter](/image-resize-and-crop#aspect-ratio---ar) to change the aspect ratio like this


```javascript
function showTransformedImage() {
  let transformedImageUrl = getImagekitUrlFromSrc(imageSrc, [
    {
      height: 400,
      aspectRatio: '3-2',
    },
  ]);
  setImageUrl(transformedImageUrl);
}
```


Output:

![React Native aspect ratio;width=400](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/react-nativet4.PNG)

### Chained Transformation

[Chained transformations](/transformations#chained-transformations) provide a simple way to control the sequence in which transformations are applied.

Let’s try it out by resizing an image, then rotating it:


```javascript
function showTransformedImage() {
  let transformedImageUrl = getImagekitUrlFromSrc(imageSrc, [
    {
      height: 300,
      width: 300,
    },
    {
      rotation: '90',
    },
  ]);
  setImageUrl(transformedImageUrl);
}
```


Output:

![React Native chained Transformation;width=400](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/react-nativet6.PNG)

## Adding overlays

ImageKit.io enables you to apply overlays to [images](/add-overlays-on-images) and [videos](/add-overlays-on-videos) using the raw parameter with the concept of [layers](/transformations#overlay-using-layers). The raw parameter facilitates incorporating transformations directly in the URL. A layer is a distinct type of transformation that allows you to define an asset to serve as an overlay, along with its positioning and additional transformations.

### Text Overlay

Text overlay can be used to place text on an image. Here's how:


```javascript
function showTransformedImage() {
  let transformedImageUrl = getImagekitUrlFromSrc(imageSrc, [
    {
      raw: 'l-text,i-Imagekit,co-0651D5,fs-50,l-end',
    },
  ]);
  setImageUrl(transformedImageUrl);
}
```


Output:

![React Native Text Overlay;width=400](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/react-nativet5.PNG)

### Image Overlay

Image overlay can be used like this:


```javascript
function showTransformedImage() {
  let transformedImageUrl = getImagekitUrlFromSrc(imageSrc, [
    {
      raw: 'l-image,i-plant.jpeg,h-100,b-10_CDDC39,l-end',
    },
  ]);
  setImageUrl(transformedImageUrl);
}
```


Output:

![React Native Image Overlay;width=400](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/react-nativet3.PNG)

## Client-side file uploading

Let's learn how to upload an image to our media library.

For this, we would need a dummy backend app to authenticate our upload request. API authentication for upload always happens on the backend for security reasons.

In the following section, we will create a backend server that we can use.

### Setting up the backend app

For this quickstart guide, we will create a sample Node.js server which will provide an authentication endpoint at `http://localhost:8080/auth`.

Let's create a file `index.js` inside `server` folder in the project root.

```bash
mkdir server
touch server/index.js
```

Install the basic packages needed to create a dummy server for ImageKit backend authentication:

```js
npm install express uuid cors
```

We will use the [ImageKit Node.js SDK](https://github.com/imagekit-developer/imagekit-nodejs) to implement `http://localhost:8080/auth`.

The backend SDK requires your API public key, private key, and URL endpoint. You can obtain them from [Developer Options](https://imagekit.io/dashboard/developer/api-keys) and [URL endpoint](https://imagekit.io/dashboard/url-endpoints) pages respectively.

This is how `server/index.js` file should look now.

{% tabs %}
{% tab title="Node.js" %}

```javascript
const express = require('express');
const router = express.Router();
const cors = require('cors');
const app = express();
app.use(cors());

const uuid = require('uuid');
const crypto = require('crypto');

const privateKey = ''; //insert your own private key here
router.get('/auth', function (req, res) {
  const token = req.query.token || uuid.v4();
  const expire = req.query.expire || parseInt(Date.now() / 1000) + 2400;
  const privateAPIKey = `${privateKey}`;
  const signature = crypto
    .createHmac('sha1', privateAPIKey)
    .update(token + expire)
    .digest('hex');
  res.status(200);
  res.send({
    token,
    expire,
    signature,
  });
});

app.use('/', router);

app.listen(8080, function () {
  console.log('Live at Port 8080');
});
```

{% /tab %}
{% /tabs %}

Obtain your [API private key](/api-keys#private-key) from the developer section from the ImageKit dashboard, and paste it in the server `index.js` file.

Let's run the backend server.

```
cd server
node index.js
```

You should see a log saying that the app is _**'Live at port 8080'**_.

If you GET `http://localhost:8080/auth`, you should see a JSON response like this. Actual values will vary.

```javascript
{
    token: "5dd0e211-8d67-452e-9acd-954c0bd53a1f",
    expire: 1601047259,
    signature: "dcb8e72e2b6e98186ec56c62c9e62886f40eaa96"
}
```

#### Configure the auth endpoint in the frontend app

Head over to `app/config/imagekit.js` and replace the `authenticationEndpoint` with `http://localhost:8080/auth`

### Upload an image

{% callout style="info" %}
Try using `react-native v0.73.0` which is the latest version at the time of writing this article, as some of the previous versions have a known [issue](https://github.com/facebook/react-native/issues/29021) in uploading files. If you are using a previous version and can't upgrade, you'll have to implement a [workaround](https://github.com/facebook/react-native/issues/29021#issuecomment-678829869).
{% /callout %}

For this, let's create couple of functions in `app/lib/imagekit.js` file and update `app/AppComponent.js` to include the upload screen.

{% linetabs %}
{% linetab title="app/lib/imagekit.js" %}

```javascript
const authenticator = async () => {
  try {
    // You can pass headers as well and later validate the request source in the backend, or you can use headers for any other use case.
    const response = await fetch(authenticationEndpoint);
    if (!response.ok) {
      const errorText = await response.text();
      throw new Error(
        `Request failed with status ${response.status}: ${errorText}`,
      );
    }
    const data = await response.json();
    const {signature, expire, token} = data;
    return {signature, expire, token};
  } catch (error) {
    throw new Error(`Authentication request failed: ${error.message}`);
  }
};

module.exports.uploadFile = async function (file) {
  const res = await authenticator();
  return new Promise((resolve, reject) => {
    imagekit.upload(
      {
        file,
        fileName: file.name, //you can change this and generate your own name if required
        tags: ['sample-tag-1', 'sample-tag-2'], //change this or remove it if you want
        ...res,
      },
      function (err, result) {
        if (err) reject(err);
        resolve(result);
      },
    );
  });
};
```

{% /linetab %}

{% linetab title="app/AppComponent.js" %}

```js
import React from 'react';
import {createStackNavigator} from '@react-navigation/stack';

import Main from './screens/Main';
import Fetch from './screens/Fetch';
import Upload from './screens/Upload';
import Videos from './screens/Videos';

const Stack = createStackNavigator();

function AppComponent() {
  return (
    <Stack.Navigator>
      <Stack.Screen name="Home" component={Main} />
      <Stack.Screen name="Fetch Images" component={Fetch} />
      <Stack.Screen name="Upload File" component={Upload} />
    </Stack.Navigator>
  );
}

export default AppComponent;
```

{% /linetab %}
{% /linetabs %}

We are going to use `react-native-document-picker` to select files.

```bash
npm install react-native-document-picker
```

This is how we implement file upload in `app/screens/Upload/index.js`

{% linetabs %}

{% linetab title="app/screens/Upload/index.js" %}

```javascript
import React, {useState} from 'react';
import {View} from 'react-native';
import DocumentPicker from 'react-native-document-picker';

import Button from '../../components/Button/';
import Text from '../../components/Text/';
import getStyleSheet from './styles';

import {uploadFile} from '../../lib/imagekit';

function Upload() {
  let styleSheet = getStyleSheet({});

  const [uploadFileUrl, setUploadFileUrl] = useState();

  async function openFileSelector() {
    try {
      const res = await DocumentPicker.pick({
        type: [DocumentPicker.types.allFiles],
      });

      uploadFileToImagekit(res);
    } catch (err) {
      if (DocumentPicker.isCancel(err)) {
        // User cancelled the picker, exit any dialogs or menus and move on
      } else {
        throw err;
      }
    }
  }

  async function uploadFileToImagekit(fileData) {
    try {
      const uploadedFile = await uploadFile(fileData);
      setUploadFileUrl(uploadedFile.url);
    } catch (err) {
      //handle error in uploading file
    }
  }

  return (
    <>
      <View style={styleSheet.container}>
        <Button
          cssProps={styleSheet.buttonCssProps}
          onPress={() => openFileSelector()}>
          Upload File
        </Button>
        <View style={styleSheet.captionView}>
          {uploadFileUrl && <Text>Uploaded File - {uploadFileUrl}</Text>}
        </View>
      </View>
    </>
  );
}

export default Upload;
```

{% /linetab %}
{% linetab title="app/screens/Upload/styles.js" %}

```js
import {StyleSheet} from 'react-native';

function getStyleSheet(cssProps) {
  return StyleSheet.create({
    container: {
      flex: 1,
      alignItems: 'center',
      justifyContent: 'center',
    },
    buttonCssProps: {
      width: 150,
    },
    captionView: {
      marginTop: 10,
    },
    text: {
      color: 'black',
      fontSize: 15,
      marginLeft: 10,
      marginRight: 10,
    },
  });
}

export default getStyleSheet;
```

{% /linetab %}
{% /linetabs %}


Let’s upload an image by selecting a file using the file input. 

The uploader uploads whenever the file input changes. You can verify that the file was successfully uploaded by checking the browser console. It should print the file URL.

After a successful upload, you should see the newly uploaded file in the [Media Library](https://imagekit.io/dashboard/media-library) of your ImageKit dashboard.

## Rendering videos

Rendering videos works similarly to rendering images.

We're going to use the [`react-native-video`](https://www.npmjs.com/package/react-native-video) package to play video files, but you can use any other video player.

```bash
npm install react-native-video
```

Update the `app/screens/Videos/index.js` and `app/AppComponent.js` file to fetch video.

{% linetabs %}
{% linetab title="app/screens/Videos/index.js" %}

```javascript
import React from 'react';
import {View, ScrollView, Text} from 'react-native';
import getStyleSheet from './styles';
import {getImagekitUrlFromSrc} from '../../lib/imagekit';
import {urlEndpoint} from '../../config/imagekit';
import Video from 'react-native-video';

function Videos() {
  let styleSheet = getStyleSheet({});

  const videoPath = '/sample-video.mp4';
  let videoSrc = urlEndpoint + videoPath;

  function showTransformedVideo(transformationType) {
    let transformationArray = [];
    let transformedVideoUrl;

    switch (transformationType) {
      case 'Transformation 1': //basic video resizing
        transformationArray = [
          {
            height: 200,
            width: 200,
          },
        ];
        transformedVideoUrl = getImagekitUrlFromSrc(
          videoSrc,
          transformationArray,
        );
        break;

      case 'Transformation 2': //crop mode and url from source
        videoSrc = 'https://ik.imagekit.io/demo/img/sample-video.mp4';
        transformationArray = [
          {
            b: '5_red',
            q: 95,
          },
        ];
        transformedVideoUrl = getImagekitUrlFromSrc(
          videoSrc,
          transformationArray,
        );
        break;

      default:
        transformedVideoUrl = getImagekitUrlFromSrc(videoSrc, []);
        break;
    }

    return transformedVideoUrl;
  }

  return (
    <ScrollView>
      <View style={styleSheet.imgContainer}>
        <>
          <View style={styleSheet.captionView}>
            <Text style={styleSheet.text}>{'Transformation 1'}</Text>
          </View>
          <View style={styleSheet.captionView}>
            <Text style={styleSheet.text}>
              Rendered URL - {showTransformedVideo('Transformation 1')}
            </Text>
          </View>
          <Video
            source={{uri: showTransformedVideo('Transformation 1')}}
            style={{
              width: 200,
              height: 200,
            }}
            controls={true}
          />
        </>
      </View>
      <View style={styleSheet.imgContainer}>
        <>
          <View style={styleSheet.captionView}>
            <Text style={styleSheet.text}>{'Transformation 2'}</Text>
          </View>
          <View style={styleSheet.captionView}>
            <Text style={styleSheet.text}>
              Rendered URL - {showTransformedVideo('Transformation 2')}
            </Text>
          </View>
          <Video
            source={{uri: showTransformedVideo('Transformation 2')}}
            style={{
              width: 300,
              height: 300,
            }}
            controls={true}
          />
        </>
      </View>
    </ScrollView>
  );
}

export default Videos;
```

{% /linetab %}
{% linetab title="app/screens/Videos/styles.js" %}

```js
import {StyleSheet} from 'react-native';

function getStyleSheet() {
  return StyleSheet.create({
    btnContainer: {
      flex: 1,
      alignItems: 'stretch',
      justifyContent: 'center',
    },
    imgContainer: {
      flex: 3,
      alignItems: 'center',
      justifyContent: 'flex-start',
      marginBottom: 10,
    },
    btnView: {
      flexDirection: 'row',
      justifyContent: 'space-evenly',
      alignItems: 'center',
      marginTop: 10,
      marginBottom: 10,
    },
    buttonCssProps: {
      width: 150,
    },
    captionView: {
      margin: 5,
    },
    text: {
      color: 'black',
      fontSize: 15,
      marginLeft: 10,
      marginRight: 10,
    },
  });
}

export default getStyleSheet;
```

{% /linetab %}
{% linetab title="app/AppComponent.js" %}

```js
import React from 'react';
import {createStackNavigator} from '@react-navigation/stack';

import Main from './screens/Main';
import Fetch from './screens/Fetch';
import Upload from './screens/Upload';
import Videos from './screens/Videos';

const Stack = createStackNavigator();

function AppComponent() {
  return (
    <Stack.Navigator>
      <Stack.Screen name="Home" component={Main} />
      <Stack.Screen name="Fetch Images" component={Fetch} />
      <Stack.Screen name="Upload File" component={Upload} />
      <Stack.Screen name="Fetch Videos" component={Videos} />
    </Stack.Navigator>
  );
}

export default AppComponent;
```

{% /linetab %}
{% /linetabs %}

It will look as shown below.

![React Native Videos;width=400](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/react-native-videos.PNG)


---

# Source: /integration/ruby

---
title: Ruby
description: >-
  ImageKit integration for Ruby and Ruby on Rails applications with support for image/video transformations, URL generation, and file uploads.
---

ImageKit provides comprehensive Ruby support through two packages designed for different use cases in the Ruby ecosystem:

## Ruby SDK

The [ImageKit Ruby SDK](https://github.com/imagekit-developer/imagekit-ruby) is a complete Ruby library for integrating ImageKit's media API. It provides:

- **URL generation** with transformations for images and videos
- **File upload** management through ImageKit's REST API
- **Signed URLs** for secure content delivery
- **Helper methods** for authentication and responsive images
- **Type safety** with comprehensive RBI (Sorbet) and RBS definitions

The SDK is built on Ruby's standard `net/http` library with connection pooling, supports Ruby 3.2.0+, and ships with complete YARD documentation.

**Installation:**

```ruby
gem "imagekitio"
```

**Documentation:**
- [Gemdocs](https://gemdocs.org/gems/imagekitio)
- [SDK GitHub repo](https://github.com/imagekit-developer/imagekit-ruby)

## Ruby on Rails Gem

The [ImageKit Rails gem](https://github.com/imagekit-developer/imagekit-rails) builds on top of the Ruby SDK to provide Rails-specific integrations:

- **View helpers** (`ik_image_tag`, `ik_video_tag`) for responsive images and videos
- **Active Storage service** for storing uploads in ImageKit
- **Automatic responsive images** with `srcset` generation
- **Seamless integration** with Rails asset pipeline and ERB templates

The Rails gem handles common Rails patterns like form uploads, model attachments, and view rendering with transformations.

**Installation:**

```ruby
gem "imagekitio"
gem "imagekitio-rails"
```

**Documentation:**
- [Rails Integration Guide](/integration/ruby/ruby-on-rails)
- [GitHub Repository](https://github.com/imagekit-developer/imagekit-rails)

## Use Cases

### Plain Ruby Applications

Use the Ruby SDK for:
- Non-Rails Ruby applications (Sinatra, Hanami, etc.)
- Background job processors
- Command-line tools and scripts
- Custom integrations where you need direct API access

**Example:**

```ruby
require 'imagekitio'

client = Imagekitio::Client.new(
  private_key: ENV['IMAGEKIT_PRIVATE_KEY']
)

# Upload a file
response = client.files.upload(
  file: Pathname('/path/to/image.jpg'),
  file_name: 'image.jpg'
)

# Generate URL with transformations
url = client.helper.build_url({
  src: '/default-image.jpg',
  url_endpoint: 'https://ik.imagekit.io/your_imagekit_id',
  transformation: [{ width: 400, height: 300, quality: 80 }]
})
```

### Ruby on Rails Applications

Use the Rails gem for:
- Full-stack Rails applications
- Active Storage integration
- View helpers for images and videos
- Form uploads with model attachments

**Example:**

```erb
<%# app/views/products/show.html.erb %>
<%= ik_image_tag(@product.featured_image, 
  transformation: [{ width: 800, height: 600, crop: 'at_max' }],
  sizes: '(max-width: 768px) 100vw, 800px',
  alt: @product.name
) %>
```

## Key Features

### URL Generation and Transformations

Both packages support ImageKit's complete transformation API:

- Image resizing, cropping, and format conversion
- Quality optimization and format auto-detection
- Effects (blur, grayscale, rotation, etc.)
- Text and image overlays
- Chained transformations
- AI-powered transformations (background removal, upscaling)

### File Management

Upload files to ImageKit through the Ruby SDK's file management API or through Rails Active Storage integration:

```ruby
# Direct upload with Ruby SDK
client.files.upload(file: File.read('image.jpg'), file_name: 'image.jpg')

# Rails Active Storage
user.avatar.attach(params[:avatar])
# Automatically stored in ImageKit
```

### Secure Delivery

Generate signed URLs for private content with expiration times:

```ruby
# Ruby SDK
url = client.helper.build_url({
  src: '/private-image.jpg',
  signed: true,
  expires_in: 3600
})

# Rails view helper
<%= ik_image_tag('/private-image.jpg', signed: true, expires_in: 3600) %>
```

## Additional Resources

- [ImageKit REST API Reference](/api-reference)
- [Image and video transformation](/transformations)
- [CarrierWave Integration](/integration/ruby/ruby-on-rails-with-carrierwave) - For legacy Rails applications using CarrierWave


---

# Source: /integration/ruby/ruby-on-rails

---
title: "Ruby on Rails Integration"
description: "Integrate ImageKit into Rails with view helpers and Active Storage for seamless image and video handling."
---

The [ImageKit Rails gem](https://github.com/imagekit-developer/imagekit-rails) provides seamless integration with Ruby on Rails applications. It includes view helpers for generating responsive image and video tags with transformations, Active Storage service for storing files in ImageKit, and automatic responsive image generation with `srcset`.

The gem works with all Active Storage features like `has_one_attached` and `has_many_attached`, and provides dedicated view helpers (`ik_image_tag` and `ik_video_tag`) that handle URL generation, transformations, and responsive images automatically.

For complete API documentation and source code, see the [ImageKit Rails gem on GitHub](https://github.com/imagekit-developer/imagekit-rails).

**Documentation:**
- [Gemdocs](https://gemdocs.org/gems/imagekitio-rails)
- [SDK GitHub repo](https://github.com/imagekit-developer/imagekit-rails)

## Installation

Add the ImageKit Rails gem to your `Gemfile`:

```ruby
gem 'imagekitio-rails'
```

Run bundle install:

```bash
bundle install
```

Create `config/initializers/imagekit.rb` with your credentials from the [ImageKit dashboard](https://imagekit.io/dashboard/developer/api-keys):

```ruby
Imagekit::Rails.configure do |config|
  config.url_endpoint = ENV['IMAGEKIT_URL_ENDPOINT']   # https://ik.imagekit.io/your_imagekit_id
  config.public_key = ENV['IMAGEKIT_PUBLIC_KEY']
  config.private_key = ENV['IMAGEKIT_PRIVATE_KEY']
  
  # Optional defaults
  # config.transformation_position = :query  # or :path
  # config.responsive = true                 # false to disable responsive images
end
```

## View helpers

The Rails gem provides `ik_image_tag` and `ik_video_tag` helpers that work like Rails' built-in `image_tag` and `video_tag` but with ImageKit transformations and responsive image support.

### Basic image tag

Use `ik_image_tag` in your views to display images:

```html
<!-- Basic image -->
<%= ik_image_tag("/photo.jpg", alt: "My Photo") %>

<!-- With transformations -->
<%= ik_image_tag("/photo.jpg", transformation: [{ width: 400, height: 300 }], alt: "Resized Photo") %>

<!-- With standard HTML attributes -->
<%= ik_image_tag("/photo.jpg", class: "rounded shadow", alt: "Styled Photo") %>
```

### Image transformations

Apply transformations using the `transformation` parameter:

```html
<!-- Resize and crop -->
<%= ik_image_tag("/photo.jpg", transformation: [{ 
  width: 400, 
  height: 300, 
  crop: "at_max"
}]) %>

<!-- Border and radius -->
<%= ik_image_tag("/photo.jpg", transformation: [{ 
  radius: 20,
  border: "3_FF0000"
}]) %>
```

### Chained transformations

Apply multiple transformations in sequence:

```html
<%= ik_image_tag("/photo.jpg", transformation: [
  { width: 400, height: 300, crop: "at_max" },
  { rotation: 90 },
  { blur: 5, grayscale: true }
]) %>
```

### Responsive images

Responsive images with `srcset` are enabled by default. The helper automatically generates multiple image sizes:

```html
<!-- Automatic responsive images -->
<%= ik_image_tag("/photo.jpg", width: 800, sizes: "(max-width: 600px) 100vw, 800px") %>

<!-- Disable responsive images for specific cases -->
<%= ik_image_tag("/photo.jpg", responsive: false) %>

<!-- Advanced responsive setup with transformations -->
<%= ik_image_tag(@product.featured_image, 
  width: 800,
  sizes: "(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 800px",
  transformation: [{ quality: 85, format: "auto" }],
  alt: @product.name
) %>
```

### Lazy loading

Images are lazy-loaded by default:

```html
<!-- Default lazy loading -->
<%= ik_image_tag("/photo.jpg") %>

<!-- Eager loading for above-the-fold images -->
<%= ik_image_tag("/hero.jpg", loading: "eager") %>
```

### Video tags

Use `ik_video_tag` for video content:

```html
<!-- Basic video -->
<%= ik_video_tag("/video.mp4", controls: true) %>

<!-- With transformations -->
<%= ik_video_tag("/video.mp4", 
  transformation: [{ width: 640, height: 480 }],
  controls: true,
  autoplay: true,
  muted: true
) %>
```

## Overlays

Add text or image overlays to your images:

### Text overlay

```html
<%= ik_image_tag("/background.jpg", transformation: [{
  overlay: {
    type: "text",
    text: "Hello World",
    transformation: [{ 
      fontSize: 50, 
      fontColor: "FFFFFF",
      fontFamily: "Arial",
      typography: "b"
    }]
  }
}]) %>
```

### Image overlay

```html
<%= ik_image_tag("/background.jpg", transformation: [{
  overlay: {
    type: "image",
    input: "logo.png",
    transformation: [{ width: 100, height: 100 }],
    position: { x: 10, y: 10 }
  }
}]) %>
```

### Watermark example

```html
<%= ik_image_tag("/product.jpg", transformation: [{
  overlay: {
    type: "image",
    input: "watermark.png",
    transformation: [{ width: 150, opacity: 70 }],
    position: { focus: "bottom_right" }
  }
}]) %>
```

## AI transformations

Use ImageKit's AI-powered transformations:

```html
<!-- Background removal -->
<%= ik_image_tag("/photo.jpg", transformation: [{ aiRemoveBackground: true }]) %>

<!-- Upscaling -->
<%= ik_image_tag("/small-photo.jpg", transformation: [{ aiUpscale: true }]) %>

<!-- AI drop shadow -->
<%= ik_image_tag("/logo.png", transformation: [{ aiDropShadow: true }]) %>
```

## Signed URLs

Generate signed URLs for secure content delivery:

```html
<!-- Image with signature that expires in 1 hour -->
<%= ik_image_tag("/private/photo.jpg", signed: true, expires_in: 3600) %>

<!-- Video with signature -->
<%= ik_video_tag("/private/video.mp4", signed: true, expires_in: 3600, controls: true) %>
```

## Active Storage integration

ImageKit integrates seamlessly with Rails Active Storage, allowing you to store attachments in ImageKit while maintaining Active Storage's familiar API.

### Prerequisites

If you're setting up Active Storage for the first time in your Rails application, you'll need to install it first. Skip this step if Active Storage is already configured in your application.

```bash
rails active_storage:install
rails db:migrate
```

This will create the necessary database tables for Active Storage to track your file attachments.

### Configuration

Add ImageKit as a storage service in `config/storage.yml`:

```bash
imagekit:
  service: ImageKit
```

### Override credentials per environment

By default, the Active Storage service uses credentials from your global configuration (`config/initializers/imagekit.rb`). You can optionally override these credentials in `storage.yml` to use different ImageKit accounts for different environments:

```yaml
# Use global configuration (most common)
imagekit:
  service: ImageKit

# Override with environment-specific credentials
imagekit_production:
  service: ImageKit
  private_key: <%= ENV['IMAGEKIT_PRODUCTION_PRIVATE_KEY'] %>
  public_key: <%= ENV['IMAGEKIT_PRODUCTION_PUBLIC_KEY'] %>
  url_endpoint: <%= ENV['IMAGEKIT_PRODUCTION_URL_ENDPOINT'] %>

imagekit_staging:
  service: ImageKit
  private_key: <%= ENV['IMAGEKIT_STAGING_PRIVATE_KEY'] %>
  public_key: <%= ENV['IMAGEKIT_STAGING_PUBLIC_KEY'] %>
  url_endpoint: <%= ENV['IMAGEKIT_STAGING_URL_ENDPOINT'] %>
```

Then reference the specific service in your environment config:

```ruby
# config/environments/production.rb
config.active_storage.service = :imagekit_production

# config/environments/staging.rb
config.active_storage.service = :imagekit_staging
```

**Note:** If credentials are provided in `storage.yml`, they take precedence over the global configuration. If not provided, the service falls back to the global configuration.

Set ImageKit as your storage service:

```ruby
# config/environments/production.rb
config.active_storage.service = :imagekit

# config/environments/development.rb
config.active_storage.service = :local  # Keep local storage for development
```

### File attachments

Use Active Storage's attachment methods in your models:

```ruby
# app/models/user.rb
class User < ApplicationRecord
  has_one_attached :avatar
  has_many_attached :photos
end
```

```ruby
# app/models/product.rb
class Product < ApplicationRecord
  has_one_attached :featured_image
  has_many_attached :gallery_images
end
```

### Upload files

Create forms to upload files:

```html
<!-- app/views/users/edit.html.erb -->
<%= form_with model: @user do |form| %>
  <div>
    <%= form.label :avatar, "Profile Picture" %>
    <%= form.file_field :avatar %>
  </div>
  <%= form.submit "Update Profile" %>
<% end %>
```

Handle uploads in controllers:

```ruby
# app/controllers/users_controller.rb
class UsersController < ApplicationController
  def update
    @user = current_user
    if @user.update(user_params)
      redirect_to @user, notice: "Profile updated!"
    else
      render :edit
    end
  end
  
  private
  
  def user_params
    params.require(:user).permit(:name, :avatar)
  end
end
```

### Display attachments

Use `ik_image_tag` with Active Storage attachments:

```html
<!-- User avatar with transformations -->
<%= ik_image_tag(@user.avatar, transformation: [
  { width: 200, height: 200, crop: "at_max" },
  { radius: "max" }
], alt: @user.name) %>

<!-- Product images -->
<% @product.gallery_images.each do |image| %>
  <%= ik_image_tag(image, transformation: [
    { width: 400, height: 400, crop: "at_max" },
    { quality: 85 }
  ]) %>
<% end %>
```

### Getting URLs programmatically

For views, always use `ik_image_tag` (covered above). However, if you need raw URLs for non-view contexts like APIs, background jobs, mailers, or JSON responses, access the service directly:

```ruby
# Get URL for an attachment
url = @user.avatar.service.url(@user.avatar.blob.key)
# => "https://ik.imagekit.io/your_id/abc123xyz"

# With transformations
url = @user.avatar.service.url(
  @user.avatar.blob.key,
  transformation: [{ width: 200, height: 200 }]
)
# => "https://ik.imagekit.io/your_id/abc123xyz?tr=w-200,h-200"
```

**Example: In a JSON API response**

```ruby
# app/controllers/api/users_controller.rb
def show
  render json: {
    user: {
      name: @user.name,
      avatar_url: @user.avatar.service.url(
        @user.avatar.blob.key,
        transformation: [{ width: 150, height: 150, crop: "thumb" }]
      )
    }
  }
end
```

**Example: In a mailer**

```ruby
# app/mailers/user_mailer.rb
class UserMailer < ApplicationMailer
  def welcome_email(user)
    @avatar_url = user.avatar.service.url(
      user.avatar.blob.key,
      transformation: [{ width: 100, height: 100 }]
    )
    mail(to: user.email, subject: "Welcome!")
  end
end
```

### Check if file is attached

```html
<% if @user.avatar.attached? %>
  <%= ik_image_tag(@user.avatar, transformation: [{ width: 200, height: 200 }]) %>
<% else %>
  <%= ik_image_tag("/placeholder.jpg", transformation: [{ width: 200, height: 200 }]) %>
<% end %>
```

### Delete attachments

```ruby
# In your controller
@user.avatar.purge       # Delete immediately
@user.avatar.purge_later # Delete via background job (recommended)
```

### Direct uploads

Active Storage's DirectUpload feature (client-side uploads) is not supported with ImageKit because ImageKit uses PUT requests while Active Storage uses multipart/form-data POST requests. Files must be uploaded through your Rails server.

## Organizing files in folders

ImageKit stores files using their Active Storage keys as complete file paths. Each attachment automatically gets organized based on its model, attribute, and ID.

For example, a user's avatar is stored at a path like `/active_storage/attachments/123/avatar-filename.jpg` where the key becomes the complete file path in ImageKit.

This organization happens automatically and doesn't require any configuration. If you need custom folder organization, you can customize the Active Storage key generation in your Rails application.

## Migrating from Active Storage variants

If you're migrating from local/S3 storage and currently using Active Storage's `.variant()` method, you should convert them to ImageKit transformations for better performance.

### Why avoid variants with ImageKit?

While variants technically work with ImageKit, they're extremely inefficient:
1. Downloads the original file from ImageKit to your server
2. Processes it on your server (using ImageMagick/libvips)
3. Re-uploads the processed version back to ImageKit

This wastes bandwidth, server resources, and time. ImageKit's transformations happen instantly on ImageKit's servers without any round-trips.

### Migration examples

Convert your existing variant calls to `ik_image_tag` with transformations:

```html
<!-- Before: Using variants (slow with ImageKit) -->
<%= image_tag @photo.variant(resize_to_fill: [400, 300]) %>
<%= image_tag @photo.variant(resize_to_limit: [800, 600]) %>
<%= image_tag @avatar.variant(resize_and_pad: [200, 200, background: [255, 255, 255]]) %>

<!-- After: Using ImageKit transformations (instant, no server processing) -->
<%= ik_image_tag(@photo, transformation: [{ width: 400, height: 300, crop: "fill" }]) %>
<%= ik_image_tag(@photo, transformation: [{ width: 800, height: 600 }]) %>
<%= ik_image_tag(@avatar, transformation: [{ 
  width: 200, 
  height: 200, 
  crop: "pad_resize",
  background: "FFFFFF"
}]) %>
```

### Common variant conversions

| Active Storage Variant | ImageKit Transformation |
|------------------------|-------------------------|
| `resize_to_fill: [w, h]` | `{ width: w, height: h, crop: "fill" }` |
| `resize_to_limit: [w, h]` | `{ width: w, height: h }` |
| `resize_to_fit: [w, h]` | `{ width: w, height: h, crop: "at_max" }` |
| `resize_and_pad: [w, h, background: color]` | `{ width: w, height: h, crop: "pad_resize", background: "RRGGBB" }` |

### Important notes

- **Don't use** `.variant()` with ImageKit attachments
- **Always use** `ik_image_tag` instead of `image_tag` for ImageKit attachments
- ImageKit transformations are applied on-the-fly at the CDN edge
- No server processing or storage needed for transformed images

## What's next

- Explore all [transformation options](/transformations).
- Check the [ImageKit Rails gem source code](https://github.com/imagekit-developer/imagekit-rails) for advanced customization.
- For non-Rails projects, see the [Ruby SDK documentation](/integration/ruby).


---

# Source: /integration/ruby/ruby-on-rails-with-carrierwave

---
title: Ruby on Rails with carrierwave
description: >-
 File uploading in Ruby on Rails application with carrierwave gem using ImageKit.io.
---

{% callout style="info" %}
**Important info**  
We have a dedicated [Rails gem](https://github.com/imagekit-developer/imagekit-rails) now. Carrierwave integration will be added in a future release. In the meantime, please use [version 3.1.0](https://github.com/imagekit-developer/imagekit-ruby/releases/tag/3.1.0) of the existing Ruby gem that supports Carrierwave.
{% /callout %}

This is a quick start guide to show you how to integrate ImageKit in the Ruby on rails application with carrierwave gem. The code samples covered here are hosted on [Github](https://github.com/imagekit-samples/quickstart/tree/master/ruby/sample-app-with-carrierwave).

This guide walks you through the following topics:

* [Setting up ImageKit Ruby SDK](#setting-up-imagekit-ruby-on-rails-sdk)
* [Upload images](#uploading-images-in-ruby-on-rails-application)

## Setting up ImageKit Ruby on Rails SDK

For this tutorial, we will create a fresh rails application and work with it. If you already have an existing Rails app, it is also possible to use that, although you would need to modify the terminal commands and configurations in this tutorial as applicable.

Let's create a new rails application. Create a new directory and enter the command:

```bash
rails new sample-app-with-carrierwave
```

Now, navigate to the newly created directory, and run the app:


```bash
rails server
```

In your web browser, navigate to [`http://localhost:3000/`](http://localhost:3000)

You should see a generic welcome message (_Yay! You're on Rails!_).

![Welcome message for a fresh Ruby on Rails application](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/image (16).png>)

Next, to use ImageKit functionality in our app, we will create a new controller with the following command:

```bash
rails generate controller Welcome
```

This will generate a few scaffolding files for you. Go to `config/routes.rb` and add the following lines:

```ruby
get 'welcome/index'
root 'welcome#index'
```

Here, we are doing two things:

1. One, creating a route at the path _welcome/index, _to direct requests coming on that path to go to the index action of the Welcome controller, which we will add soon.
2. Second, we are declaring the root path to be directed to _welcome/index. _This means that all requests on `http://localhost:3000/` will go to `http://localhost:3000/welcome/index`

## Installing the SDK

First, add this line to your Gemfile to add the 'imagekitio' gem as a dependency.

```
gem 'imagekitio'
```

Next, run the bundle install command to install the imagekitio gem from the RubyGems repository.

```bash
bundle install
```

#### Initializing the SDK

Before the SDK can be used, let's learn about and configure the requisite authentication parameters that need to be provided to the SDK.

Create a file `config/initializers/imagekitio.rb`, open it and add your public and private API keys, as well as the URL Endpoint as follows: (You can find these keys in the Developer section of your ImageKit Dashboard)

```ruby
ImageKitIo.configure do |config|
  if Rails.env.development?
    config.public_key = 'your_public_key'
    config.private_key = 'your_private_key'
    config.url_endpoint = 'your_url_endpoint' # https://ik.imagekit.io/your_imagekit_id
  end
  config.service = :carrierwave
  # config.constants.MISSING_PRIVATE_KEY = 'custom error message'
end

```

Restart the application

```bash
rails server
```

The home screen will display an error message stating that the index action could not be found for the WelcomeController. Let's fix that.
Open up the project in your text editor of choice, and navigate to `app/controllers/welcome_controller.rb`. Edit it to make it look like the following:

```ruby
class WelcomeController < ApplicationController
  def index
  end
end
```

and create `app/views/welcome/index.html.erb` file and edit file with text `Hello world`. Now refresh the browser it renders the `Hello world`.

## Uploading images in Ruby on Rails application

There are two different methods of uploading a file to your ImageKit Media Library:

1. Direct image upload**.**
2. Attaching the image to a model using CarrierWave**.**

### Direct image upload

First, add the following code to `app/views/welcome/index.html.erb`:

```ruby
<h3>File Upload</h3>
<%= form_with(url: {action: :upload}, multipart: true) do %>
    <%= file_field_tag 'picture' %>
    <%= submit_tag "Upload" %>
<% end %>

<br>

<% flash.each do |name, msg| %>
    <%= content_tag :div, msg, class: "alert alert-info" %>
<% end %>
```

This creates a simple form with a file upload field and a submit button. The form submits the file to the path `/welcome/upload`. We need to add this path to our routes. Go to `config/routes.rb`, and add the following line:

```bash
post 'welcome/upload'
```

Now, we have the route and the HTML markup set up to submit a file for uploading. Let's introduce the controller action 'welcome#upload' to receive the file and upload it to the Media Library. Go to `app/controllers/welcome_controller.rb`, and add the following method:

```ruby
def upload
    uploaded_file = params[:picture]
    @imagekitio = ImageKitIo.client
    output = @imagekitio.upload_file(
        file: uploaded_file,
        file_name: "new_file.jpg",
        response_fields: 'tags',
        tags: ["hello"]
    )
    if output[:error]
        redirect_to "/", notice: "There was some problem uploading your image"
    else
        redirect_to "/", notice: "Your image has been uploaded successfully with the name of #{output[:response]["name"]}"
    end
end
```

Here, we first extract the file from the _:picture_ property of the _params_ object, and then upload the file to our Media Library by the name of _new\_file.jpg,_ using the `upload_file()` API. We also attach an example tag '_hello_' to the image.

Now, refresh the home page, and you should see the upload field.

![Upload field](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/image (13).png>)

Select an image/file from your local computer, and click on the _Upload_ button. A success message shall flash below the file field.

_Your image has been uploaded successfully with the name \<NAME\_OF\_FILE>_

Now, after upload, if you go to the [Media Library](https://imagekit.io/dashboard#media-library) section of your ImageKit dashboard, you should see the newly uploaded image.

If you get an authentication error during upload, verify that the API keys are configured correctly.

**Fetching uploaded file**

Fetch the uploaded image and display it in the UI by adding this line to your `app/views/welcome/index.html.erb`.

```markup
<%= image_tag "https://ik.imagekit.io/<YOUR_IMAGEKIT_ID>/<FILE_NAME>" %>
```

The app should render your uploaded image correctly.

### Attaching the image to a model (using CarrierWave)
You can attach an image as an attribute of one of your models, making it convenient to write a model-oriented code. This method uses the CarrierWave gem, which is a dependency of the imagekitio gem.

Open `Gemfile` and add carrierwave gem

```ruby
gem 'carrierwave', '~> 2.0'
```

run `bundle install`

Next, we'll create an entity called an uploader.

```bash
rails g uploader <Uploading_attribute_name>
# For example if you want to create uploader for Picture attribute then use
rails g uploader Picture
# Generated uploader's path will be app/uploaders/picture_uploader.rb
```

Now, go to the generated uploader file - `app/uploaders/<name>_uploader.eb`, and enter the following code. The _options_ configuration is optional.

```ruby
class PictureUploader < CarrierWave::Uploader::Base
  include ImageKitIo::CarrierWave

  def options
    options = 
    {
        response_fields: 'isPrivateFile, tags',
        tags: ["Rails SDK uploads"],
        use_unique_file_name: false,
        folder: "your_directory/"
    }
  end

  # If you want to set upload dir then you can use following method or you can also use options method.
  # This method shuld return string
  def store_dir
      "your_directory/"
  end

end
```

Now, we generate a model and give it a picture attribute, which will be an image. If you already have a model in your project, you can simply add the attribute to the existing model.

```bash
rails generate model Post
```

Now go to the model file - `app/models/post.rb`, and add the following lines:

```bash
class Post < ApplicationRecord
    attr_accessor :picture
    mount_uploader :picture, PictureUploader
end
```

You are free to change the name of the attribute from :picture to something else.

Perform the database migrations. This will add two columns - title, picture to the Posts table of our database.

```bash
rails g migration AddPictureToPosts picture:string
rails g migration AddTitleToPosts title:string
rails db:migrate
```

Now, create another controller named after the model. For example, we'll create a controller called Post.

```bash
rails generate controller Posts
```

Now, go to `app/controllers/posts_controller.rb`, and add the following methods:

```ruby
class PostsController < ApplicationController
    def index
        @posts = Post.all
    end
    def show
        @post = Post.find params[:id]
    end

    def new
        @post = Post.new
    end

    def create
        @post = Post.new post_params
        if @post.save
            redirect_to @post
        else
            render 'new'
        end
    end

    def post_params
        params.require(:post).permit(:title, :picture)
    end
end
```

Here, we create standard methods to show all posts, show a single post, and create a new post. These methods will have to be accompanied by some HTML markup as well. So go to `app/views/posts/`, and add the following files

index.html.erb

```markup
<%= @posts.each do |post| %>
    <div class="post">
        <div class="image">
            <%= image_tag post.picture.url %>
        </div>
        <div class="content">
            <%= link_to "#{post.title}", post_path(post), class: "header" %>
        </div>
    </div>
<% end %>
<%= link_to 'Back', posts_path %>
```

new.html.erb

```markup
<%= form_with model: @post do |form| %>

    <%= label_tag(:title, "Enter title of post") %>
    <%= form.text_field :title %>
    
    <%= label_tag(:picture, "Upload a picture") %>
    <%= form.file_field :picture %>
    
    <%= submit_tag "Submit" %>
<% end %>

<%= link_to 'Back', posts_path %>
```

show.html.erb

```markup
<div class="post">
    <div class="image">
        <%= image_tag @post.picture.url %>
    </div>
    <div class="content">
        <%= link_to "#{@post.title}", post_path(@post), class: "header" %>
    </div>
</div>
<%= link_to 'Back', posts_path %>
```

And finally let's add the routes
`config/routes.rb`

```ruby
resources :posts
```

Now, restart the server and go to http://localhost:3000/posts/new. You should see two form fields, for _title_, and _picture_. Enter a text value for the title field, and upload an image/file for the picture field, and click on Submit. This should redirect you to http://localhost:3000/posts/1, displaying the title and the image.

This sums up how you can upload images to your Media Library using the SDK. The second method is more suited for RESTful applications with CRUD operations where the image is an attribute of a resource.

## Authentication parameter generation

You can use the SDK to generate [authentication](/api-reference/upload-file/upload-file#authorization-for-client-side-file-upload) parameters that are required if you want to implement client-side upload functionality using javascript or some [front-end framework](/quick-start-guides#front-end).

```ruby
# app/controllers/welcome_controller.rb

def auth_params
  @imagekitio = ImageKitIo.client
  @auth_params = @imagekitio.get_authentication_parameters()
end
```

```ruby
# config/routes.rb

get 'welcome/auth_params'
```

```ruby
# app/views/welcome/auth_params.html.erb

<div>
    <%= @auth_params %>
</div>
```

The `get_authentication_parameters(token = nil, expire = nil)`  takes two optional arguments, `token`, and `expire`. `token` defaults to a random string if not provided. `expire` defaults to infinite.

You should see an output like this:

```ruby
{    
    :token=>"6b4d79e5-eb36-4de0-8ef5-534c88e45ebf",
    :expire=>1600957501,
    :signature=>"4c19c4066a140921eddaff7aaa3625df2bf8182a"
}
```


---

# Source: /integration/python

---
title: Python ImageKit SDK
description: >-
  Quick start guide for ImageKit Python SDK - upload files, generate URLs, and integrate ImageKit into your Python applications.
---

The [ImageKit Python SDK](https://github.com/imagekit-developer/imagekit-python) provides a complete Python library for integrating ImageKit into your applications. Built with modern Python standards and full type safety via Pydantic models.

## What the SDK Does

- **URL generation** with image/video transformations
- **File uploads** to ImageKit's media library
- **File management** - list, search, update, delete files
- **Signed URLs** for private content delivery
- **Client-side upload authentication** tokens
- **Webhook verification** for event handling
- **Full type safety** with Pydantic models
- **Sync & async** support with httpx (Python 3.9+)

## Installation

```bash
pip install imagekitio
```

For better async performance with high concurrency:

```bash
pip install imagekitio[aiohttp]
```

## Quick Start

Get your API credentials from the [ImageKit Dashboard](https://imagekit.io/dashboard/developer/api-keys):

```python
import os
from imagekitio import ImageKit

imagekit = ImageKit(
    private_key=os.environ.get("IMAGEKIT_PRIVATE_KEY")
)

# Store URL endpoint for reuse
URL_ENDPOINT = os.environ.get("IMAGEKIT_URL_ENDPOINT")
```

## Common Examples

### Upload a File

```python
from pathlib import Path

# Upload from file
response = imagekit.files.upload(
    file=Path("product.jpg"),
    file_name="product.jpg",
    folder="/products",
    tags=["product", "featured"]
)
print(f"File ID: {response.file_id}")
print(f"URL: {response.url}")

# Upload from bytes (web forms)
image_data = request.files['image'].read()
response = imagekit.files.upload(
    file=image_data,
    file_name="upload.jpg"
)

# Stream large files
with open("video.mp4", "rb") as f:
    response = imagekit.files.upload(file=f, file_name="video.mp4")
```

### Generate Image URLs

For more examples of all transformation types, see the [URL generation guide](https://github.com/imagekit-developer/imagekit-python?tab=readme-ov-file#url-generation) on GitHub.

```python
# Basic transformation
url = imagekit.helper.build_url(
    url_endpoint=URL_ENDPOINT,
    src="/product.jpg",
    transformation=[{
        "width": 800,
        "height": 600,
        "format": "webp"
    }]
)
```

### Signed URLs

```python
# Expires in 1 hour
url = imagekit.helper.build_url(
    url_endpoint=URL_ENDPOINT,
    src="/private/doc.pdf",
    signed=True,
    expires_in=3600
)
```

### Image Overlays

```python
# Add watermark
url = imagekit.helper.build_url(
    url_endpoint=URL_ENDPOINT,
    src="/photo.jpg",
    transformation=[{
        "overlay": {
            "type": "image",
            "input": "/logo.png",
            "position": {"focus": "bottom_right"},
            "transformation": [{"width": 100, "opacity": 70}]
        }
    }]
)

# Text overlay
url = imagekit.helper.build_url(
    url_endpoint=URL_ENDPOINT,
    src="/product.jpg",
    transformation=[{
        "overlay": {
            "type": "text",
            "text": "SALE",
            "position": {"focus": "top_left"},
            "transformation": [{
                "font_size": 48,
                "font_color": "FF0000"
            }]
        }
    }]
)
```

### Client-Side Upload Auth

For browser-based uploads, generate auth tokens:

```python
@app.route('/api/imagekit-auth')
def get_auth():
    return jsonify(imagekit.helper.get_authentication_parameters())
```

### Webhook Verification

```python
@app.route('/webhooks/imagekit', methods=['POST'])
def handle_webhook():
    try:
        event = imagekit.webhooks.unwrap(
            payload=request.get_data(as_text=True),
            headers=dict(request.headers),
            key=os.environ.get("IMAGEKIT_WEBHOOK_SECRET")
        )
        print(f"Event: {event.type}")
        return {"status": "success"}
    except Exception:
        return {"error": "Invalid signature"}, 401
```

## Complete API Reference

Every endpoint in the [ImageKit REST API Reference](/api-reference) includes Python code snippets. To find all available methods and types in the SDK, refer to the [api.md](https://github.com/imagekit-developer/imagekit-python/blob/master/api.md) file.

## Learn More

- **[Image Transformations](/image-transformation)** - All transformation parameters
- **[Video Transformations](/video-transformation)** - Video-specific transformations  
- **[Overlays](/add-overlays-on-images)** - Advanced overlay options
- **[Webhooks](/webhooks)** - Event types and webhook setup

## Support

- **Issues:** [GitHub Issues](https://github.com/imagekit-developer/imagekit-python/issues)
- **Email:** [support@imagekit.io](mailto:support@imagekit.io)


---

# Source: /integration/java

---
title: Java ImageKit SDK
description: >-
  Quick start guide for ImageKit Java SDK - upload files, generate URLs, and integrate ImageKit into your Java applications.
---

The [ImageKit Java SDK](https://github.com/imagekit-developer/imagekit-java) provides a complete Java library for integrating ImageKit into your applications. Built with modern Java patterns and full type safety using immutable builders.

## What the SDK Does

- **URL generation** with image/video transformations
- **File uploads** to ImageKit's media library
- **File management** - list, search, update, delete files
- **Signed URLs** for private content delivery
- **Client-side upload authentication** tokens
- **Webhook verification** for event handling
- **Full type safety** with builder patterns
- **Sync & async** support with OkHttp
- **Immutable classes** for thread safety

## Installation

### Gradle

```gradle
implementation("io.imagekit:image-kit-java:3.0.0")
```

### Maven

```xml
<dependency>
  <groupId>io.imagekit</groupId>
  <artifactId>image-kit-java</artifactId>
  <version>3.0.0</version>
</dependency>
```

## Requirements

This library requires Java 8 or later.

## Quick Start

Get your API credentials from the [ImageKit Dashboard](https://imagekit.io/dashboard/developer/api-keys):

```java
import io.imagekit.client.ImageKitClient;
import io.imagekit.client.okhttp.ImageKitOkHttpClient;

// From environment variables or system properties
ImageKitClient client = ImageKitOkHttpClient.fromEnv();

// Or configure manually
ImageKitClient client = ImageKitOkHttpClient.builder()
    .privateKey(System.getenv("IMAGEKIT_PRIVATE_KEY"))
    .publicKey(System.getenv("IMAGEKIT_PUBLIC_KEY"))
    .webhookSecret(System.getenv("IMAGEKIT_WEBHOOK_SECRET"))
    .build();
```

**Environment variables:**
- `IMAGEKIT_PRIVATE_KEY` - Your private API key
- `IMAGEKIT_WEBHOOK_SECRET` - Your webhook secret (optional)

## Common Examples

### Upload a File

```java
import io.imagekit.models.files.FileUploadParams;
import io.imagekit.models.files.FileUploadResponse;
import java.nio.file.Paths;

// Upload from file path
FileUploadParams params = FileUploadParams.builder()
    .file(Paths.get("/path/to/product.jpg"))
    .fileName("product.jpg")
    .folder("/products")
    .addTag("product")
    .addTag("featured")
    .build();

FileUploadResponse response = client.files().upload(params);
System.out.println("File ID: " + response.fileId());
System.out.println("URL: " + response.url());

// Upload from byte array
byte[] imageData = request.getInputStream().readAllBytes();
FileUploadParams params = FileUploadParams.builder()
    .file(imageData)
    .fileName("upload.jpg")
    .build();
FileUploadResponse response = client.files().upload(params);

// Upload from InputStream
try (InputStream stream = new FileInputStream("/path/to/video.mp4")) {
    FileUploadParams params = FileUploadParams.builder()
        .file(stream)
        .fileName("video.mp4")
        .build();
    FileUploadResponse response = client.files().upload(params);
}
```

### Generate Image URLs

```java
import io.imagekit.models.SrcOptions;
import io.imagekit.models.Transformation;

// Basic transformation
String url = client.helper().buildUrl(
    SrcOptions.builder()
        .urlEndpoint("https://ik.imagekit.io/your_imagekit_id")
        .src("/product.jpg")
        .addTransformation(
            Transformation.builder()
                .width(800.0)
                .height(600.0)
                .format(Transformation.Format.WEBP)
                .build()
        )
        .build()
);
```

### Signed URLs

```java
// Expires in 1 hour
String url = client.helper().buildUrl(
    SrcOptions.builder()
        .urlEndpoint("https://ik.imagekit.io/your_imagekit_id")
        .src("/private/doc.pdf")
        .signed(true)
        .expiresIn(3600.0)
        .build()
);
```

### Image Overlays

```java
import io.imagekit.models.ImageOverlay;
import io.imagekit.models.Overlay;
import io.imagekit.models.OverlayPosition;

// Add watermark
String url = client.helper().buildUrl(
    SrcOptions.builder()
        .urlEndpoint("https://ik.imagekit.io/your_imagekit_id")
        .src("/photo.jpg")
        .addTransformation(
            Transformation.builder()
                .overlay(Overlay.ofImage(
                    ImageOverlay.builder()
                        .input("/logo.png")
                        .position(OverlayPosition.builder()
                            .focus(OverlayPosition.Focus.BOTTOM_RIGHT)
                            .build())
                        .addTransformation(
                            Transformation.builder()
                                .width(100.0)
                                .opacity(70.0)
                                .build()
                        )
                        .build()
                ))
                .build()
        )
        .build()
);
```

### Text Overlays

```java
import io.imagekit.models.Overlay;
import io.imagekit.models.OverlayPosition;
import io.imagekit.models.TextOverlay;
import io.imagekit.models.TextOverlayTransformation;

String url = client.helper().buildUrl(
    SrcOptions.builder()
        .urlEndpoint("https://ik.imagekit.io/your_imagekit_id")
        .src("/product.jpg")
        .addTransformation(
            Transformation.builder()
                .overlay(Overlay.ofText(
                    TextOverlay.builder()
                        .text("SALE")
                        .position(OverlayPosition.builder()
                            .focus(OverlayPosition.Focus.TOP_LEFT)
                            .build())
                        .addTransformation(
                            TextOverlayTransformation.builder()
                                .fontSize(48.0)
                                .fontColor("FF0000")
                                .build()
                        )
                        .build()
                ))
                .build()
        )
        .build()
);
```

### Client-Side Upload Auth

For browser-based uploads, generate auth tokens:

```java
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.util.Map;

@WebServlet("/api/imagekit-auth")
public class AuthServlet extends HttpServlet {
    protected void doGet(HttpServletRequest request, HttpServletResponse response) {
        Map<String, Object> authParams = client.helper()
            .getAuthenticationParameters(null, null);
        
        response.setContentType("application/json");
        response.getWriter().write(new Gson().toJson(authParams));
    }
}
```

### Webhook Verification

```java
import io.imagekit.models.webhooks.UnwrapWebhookParams;
import io.imagekit.models.webhooks.UnwrapWebhookEvent;
import io.imagekit.core.http.Headers;

@PostMapping("/webhooks/imagekit")
public ResponseEntity<String> handleWebhook(@RequestBody String payload, 
                                            @RequestHeader HttpHeaders headers) {
    try {
        Headers webhookHeaders = Headers.builder()
            .putAll(Map.of(
                "webhook-id", headers.getFirst("webhook-id"),
                "webhook-timestamp", headers.getFirst("webhook-timestamp"),
                "webhook-signature", headers.getFirst("webhook-signature")
            ))
            .build();
        
        UnwrapWebhookEvent event = client.webhooks().unwrap(
            UnwrapWebhookParams.builder()
                .payload(payload)
                .headers(webhookHeaders)
                .build()
        );
        
        // Handle different event types
        if (event.isVideoTransformationReady()) {
            var videoEvent = event.asVideoTransformationReady();
            System.out.println("Video ready: " + videoEvent.data().transformation().output().url());
        }
        
        return ResponseEntity.ok("success");
    } catch (Exception e) {
        return ResponseEntity.status(401).body("Invalid signature");
    }
}
```

## Advanced Features

### Asynchronous Execution

```java
import io.imagekit.client.ImageKitClientAsync;
import io.imagekit.client.okhttp.ImageKitOkHttpClientAsync;
import java.util.concurrent.CompletableFuture;

// Create async client
ImageKitClientAsync asyncClient = ImageKitOkHttpClientAsync.fromEnv();

// Or convert sync client to async
CompletableFuture<FileUploadResponse> future = client.async()
    .files()
    .upload(params);

future.thenAccept(response -> {
    System.out.println("Uploaded: " + response.url());
});
```

### File Management

```java
import io.imagekit.models.assets.AssetListParams;
import io.imagekit.models.assets.AssetListResponse;
import java.util.List;

// List files
List<AssetListResponse> assets = client.assets().list(
    AssetListParams.builder()
        .skip(0L)
        .limit(100L)
        .build()
);

// Search with query
List<AssetListResponse> results = client.assets().list(
    AssetListParams.builder()
        .searchQuery("tags IN ['sale', 'summer']")
        .build()
);

// Get file details
import io.imagekit.models.files.FileGetParams;
var file = client.files().get(FileGetParams.builder()
    .fileId("file_id_here")
    .build());

// Delete file
import io.imagekit.models.files.FileDeleteParams;
client.files().delete(FileDeleteParams.builder()
    .fileId("file_id_here")
    .build());
```

### Error Handling

```java
import io.imagekit.errors.ImageKitException;

try {
    FileUploadResponse response = client.files().upload(params);
} catch (ImageKitException e) {
    System.err.println("Upload failed: " + e.getMessage());
    // Handle specific error codes
    if (e.statusCode() == 401) {
        System.err.println("Authentication error");
    }
}
```

## Complete API Reference

Every endpoint in the [ImageKit REST API Reference](/api-reference) includes Java code snippets. For detailed documentation of all SDK methods and models, visit:

- **[GitHub Repository](https://github.com/imagekit-developer/imagekit-java)** - Source code and examples
- **[Javadoc](https://javadoc.io/doc/io.imagekit/image-kit-java/latest)** - Complete API documentation

## Learn More

- **[Image Transformations](/image-transformation)** - All transformation parameters
- **[Video Transformations](/video-transformation)** - Video-specific transformations
- **[Overlays](/add-overlays-on-images)** - Advanced overlay options
- **[Webhooks](/webhooks)** - Event types and webhook setup

## Support

- **Issues:** [GitHub Issues](https://github.com/imagekit-developer/imagekit-java/issues)
- **Email:** [support@imagekit.io](mailto:support@imagekit.io)


---

# Source: /integration/php

---
title: PHP
description: >-
  Real-time image & video resizing, automatic optimization, and file uploading in PHP
  using ImageKit.io.
---

[ImageKit's PHP SDK](https://github.com/imagekit-developer/imagekit-php) provides comprehensive yet straightforward asset upload, transformation, optimization, and delivery capabilities that you can implement seamlessly in your existing PHP application.

This quick start guide shows you how to integrate ImageKit into your PHP application. The code samples covered here are hosted on [Github](https://github.com/imagekit-developer/imagekit-php/tree/master/sample).

This guide walks you through the following topics:

* [Setting up ImageKit PHP SDK](#setting-up-imagekit-php-sdk)
* [Generating URL for rendering images](#generating-url-for-rendering-images)
* [Signed URL & Image Transformations](#applying-chained-transformations-common-image-manipulations--signed-url)
* [Adding overlays](#5.-adding-overlays)
* [Server-side file uploading](#server-side-file-upload)
* [ImageKit Media API](#media-management)
* [Utility Functions](#utility-functions)

## Setting up ImageKit PHP SDK

#### Prerequisites

To use ImageKit PHP SDK, you must be using PHP version 5.6.0 or later with [JSON PHP Extension](https://www.php.net/manual/en/book.json.php) and [cURL PHP Extension](https://www.php.net/manual/en/book.curl.php) enabled.

#### Create a new Project

Let's create a dummy project called **sample** using composer in a folder.

```bash
composer init --name imagekit/sample --type project
```

It will prompt a few options. Select defaults by pressing enter.

#### Install imagekit/imagekit using Composer

```bash
composer require imagekit/imagekit
```

## Quick Examples

#### Create an ImageKit Instance

```php
// Import autoloader from vendor
// If PSR-4 is not configured in composer.json file for your project
require_once __DIR__ . '/vendor/autoload.php';

use ImageKit\ImageKit;  
  
// For demonstration purposes, the documentation would use https://ik.imagekit.io/demo as urlEndpoint
$imageKit = new ImageKit(
    "publicKey",
    "privateKey",
    "urlEndpoint"
);
```
* `publicKey` and `privateKey` parameters are required as these would be used for all ImageKit API, server-side upload, and generating token for client-side file upload. You can get these parameters from the developer section in your ImageKit dashboard - [https://imagekit.io/dashboard/developer/api-keys](https://imagekit.io/dashboard/developer/api-keys).
* `urlEndpoint` is also a required parameter. You can get the value of URL endpoint from your ImageKit dashboard - [https://imagekit.io/dashboard/url-endpoints](https://imagekit.io/dashboard/url-endpoints).

#### URL Generation
```php
// For URL Generation
$imageURL = $imageKit->url(
    [
        'path' => '/default-image.jpg',
    ]
);
echo $imageURL;
// https://ik.imagekit.io/demo/default-image.jpg
```

#### File Upload
```php
// For File Upload
$uploadFile = $imageKit->uploadFile([
    'file' => 'file-url',
    'fileName' => 'new-file'
]);
```

#### Response Structure

Following is the response for [Server Side File Upload API](/api-reference/upload-file/upload-file)
```js
{
    "error": null,
    "result": {
        "fileId": "6286329dfef1b033aee60211",
        "name": "your_file_name_S-PgGysnR.jpg",
        "size": 94466,
        "versionInfo": {
            "id": "6286329dfef1b033aee60211",
            "name": "Version 1"
        },
        "filePath": "/your_file_name_S-PgGysnR.jpg",
        "url": "https://ik.imagekit.io/demo/your_file_name_S-PgGysnR.jpg",
        "fileType": "image",
        "height": 640,
        "width": 960,
        "thumbnailUrl": "https://ik.imagekit.io/demo/tr:n-ik_ml_thumbnail/your_file_name_S-PgGysnR.jpg",
        "tags": [],
        "AITags": null,
        "customMetadata": { },
        "extensionStatus": {}
    },
    "responseMetadata":{
        "headers":{
            "access-control-allow-origin": "*",
            "x-ik-requestid": "e98f2464-2a86-4934-a5ab-9a226df012c9",
            "content-type": "application/json; charset=utf-8",
            "content-length": "434",
            "etag": "W/"1b2-reNzjRCFNt45rEyD7yFY/dk+Ghg"",
            "date": "Thu, 16 Jun 2022 14:22:01 GMT",
            "x-request-id": "e98f2464-2a86-4934-a5ab-9a226df012c9"
        },
        "raw":{
            "fileId": "6286329dfef1b033aee60211",
            "name": "your_file_name_S-PgGysnR.jpg",
            "size": 94466,
            "versionInfo": {
                "id": "6286329dfef1b033aee60211",
                "name": "Version 1"
            },
            "filePath": "/your_file_name_S-PgGysnR.jpg",
            "url": "https://ik.imagekit.io/demo/your_file_name_S-PgGysnR.jpg",
            "fileType": "image",
            "height": 640,
            "width": 960,
            "thumbnailUrl": "https://ik.imagekit.io/demo/tr:n-ik_ml_thumbnail/your_file_name_S-PgGysnR.jpg",
            "tags": [],
            "AITags": null,
            "customMetadata": { },
            "extensionStatus": {}
        },
        "statusCode":200
    }
}
```

## Generating URL for rendering images

ImageKit provides inbuilt media storage and integration with external origins. Refer to the [documentation](/integration/connect-external-storage) to learn more about URL endpoints and external storages supported by ImageKit.  

### Using Image path and image hostname or endpoint 
  
This method allows you to create a URL using the image's path and the ImageKit URL endpoint (urlEndpoint) you want to use to access the image.   
  
#### Example
```php  
$imageURL = $imageKit->url(
    [
        'path' => '/default-image.jpg', 
        'transformation' => [
            [
                'height' => '300', 
                'width' => '400'
            ]
        ]
    ]
);
```  

#### Response

```  
https://ik.imagekit.io/demo/tr:h-300,w-400/default-image.jpg 
```  


### Using full image URL
This method allows you to add transformation parameters to an absolute ImageKit-powered URL. This method should be used if you have the absolute URL stored in your database.

#### Example
```php  
$imageURL = $imageKit->url([
    'src' => 'https://example.com/default-image.jpg',
    'transformation' => [
        [
            'height' => '300',
            'width' => '400'
        ]
    ]
]);
```  

#### Response
```
https://example.com/tr:h-300,w-400/default-image.jpg  
```  

The `$imageKit->url()` method accepts the following parameters.

| Option                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| :--------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| urlEndpoint            | Optional. The base URL is to be appended before the path of the image. If not specified, the URL Endpoint specified at the time of SDK initialization is used. For example, https://ik.imagekit.io/your_imagekit_id/endpoint/                                                                                                                                                                                                                                                                                                                                                           |
| path                   | Conditional. This is the path on which the image exists. For example, `/path/to/image.jpg`. Either the `path` or `src` parameter needs to be specified for URL generation.                                                                                                                                                                                                                                                                                                                                                                                                              |
| src                    | Conditional. This is the complete URL of an image already mapped to ImageKit. For example, `https://ik.imagekit.io/your_imagekit_id/endpoint/path/to/image.jpg`. Either the `path` or `src` parameter needs to be specified for URL generation.                                                                                                                                                                                                                                                                                                                                         |
| transformation         | Optional. An array of objects specifying the transformation to be applied in the URL. The transformation name and the value should be specified as a key-value pair in the object. Different steps of a [chained transformation](/transformations#chained-transformations) can be specified as different objects of the array. The complete [List of supported transformations](#list-of-supported-transformations) in the SDK and some examples of using them are given later. If you use a transformation name that is not specified in the SDK, it gets applied as it is in the URL. |
| transformationPosition | Optional. The default value is `path` which places the transformation string as a path parameter in the URL. It can also be specified as `query`, which adds the transformation string as the query parameter `tr` in the URL. If you use the `src` parameter to create the URL, the transformation string is always added as a query parameter.                                                                                                                                                                                                                                        |
| queryParameters        | Optional. These are the other query parameters that you want to add to the final URL. These can be any query parameters and are not necessarily related to ImageKit. Especially useful if you want to add some versioning parameters to your URLs.                                                                                                                                                                                                                                                                                                                                      |
| signed                 | Optional. Boolean. The default value is `false`. If set to `true`, the SDK generates a signed image URL adding the image signature to the image URL.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| expireSeconds          | Optional. Integer. It is used along with the `signed` parameter. It specifies the time in seconds from now when the signed URL will expire. If specified, the URL contains the expiry timestamp in the URL, and the image signature is modified accordingly.                                                                                                                                                                                                                                                                                                                            |
                                             

### Applying Chained Transformations, Common Image Manipulations & Signed URL

This section covers the basics:

* [Chained Transformations as a query parameter](#chained-transformations-as-a-query-parameter)
* [Image Enhancement & Color Manipulation](#image-enhancement-and-color-manipulation)
* [Resizing images](#resizing-images)
* [Quality manipulation](#quality-manipulation)
* [Adding overlays](#adding-overlays)
* [Signed URL](#signed-url)


The PHP SDK gives a name to each transformation parameter e.g. `height` for `h` and `width` for `w` parameter. It makes your code more readable. See the [full list of supported transformations](#list-of-supported-transformations).

👉 If the property does not match any of the available options, it is added as it is.\ e.g
```PHP
[
    'effectGray' => 'e-grayscale'
]
// and
[
    'e-grayscale' => ''
]
// works the same
```
👉 Note that you can also use the `h` and `w` parameters instead of `height` and `width`. 

For more examples check the [demo application](https://github.com/imagekit-developer/imagekit-php/tree/master/sample).

### Chained Transformations as a query parameter

#### Example
```php  
$imageURL = $imageKit->url([
    'path' => '/default-image.jpg',
    'urlEndpoint' => 'https://ik.imagekit.io/demo/', 
    'transformation' => [
        [
            'height' => '300',
            'width' => '400'
        ],
        [
            'rotation' => 90
        ],
    ], 
    'transformationPosition' => 'query'
]);
```  
#### Response

```  
https://ik.imagekit.io/demo/default-image.jpg?tr=h-300,w-400:rt-90
```

![](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/image (68).png>)

### Image enhancement and color manipulation

Some transformations like [Contrast stretch](/effects-and-enhancements#contrast-stretch---e-contrast), [Sharpen](/effects-and-enhancements#sharpen---e-sharpen) and [Unsharp mask](/effects-and-enhancements#unsharp-mask---e-usm) can be added to the URL with or without any other value. To use such transforms without specifying a value, specify the value as "-" in the transformation object. Otherwise, specify the value that you want to be added to this transformation.

#### Example
```php  
$imageURL = $imageKit->url([
    'src' => 'https://ik.imagekit.io/demo/default-image.jpg', 
    'transformation' => 
    [
        [
            'format' => 'jpg', 
            'progressive' => true,
            'effectSharpen' => '-', 
            'effectContrast' => '1'
        ]
    ]
]);
```  
#### Response

```  
https://ik.imagekit.io/demo/tr:f-jpg,pr-true,e-sharpen,e-contrast-1/default-image.jpg 
```

![](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/image (69).png>)

### Resizing images

Let's resize the image to a width of 400 and a height of 300.
Check detailed instructions on [Resize, Crop, and Other Common Transformations](/image-resize-and-crop).

#### Example
```php
$imageURL = $imageKit->url(array(
    'path' => '/default-image.jpg',
    'transformation' => [
        [
            'height' => '300',
            'width' => '400',
        ]
    ]
));

```

#### Response

```
https://ik.imagekit.io/demo/tr:w-400,h-300/default-image.jpg
```

![400x300 image](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/image (66).png>)

### Quality manipulation
You can use the [Quality Parameter](/image-optimization#quality---q) to change quality like this.

#### Example
```php
$imageURL = $imageKit->url(array(
    'path' => '/default-image.jpg',
    'transformation' => [
        [
            'quality' => '40',
        ]
    ]
));
```

#### Response
```
https://ik.imagekit.io/demo/tr:q-40/default-image.jpg
```

![](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/image (67).png>)


### Adding overlays

ImageKit.io enables you to apply overlays to [images](/add-overlays-on-images) and [videos](/add-overlays-on-videos) using the raw parameter with the concept of [layers](/transformations#overlay-using-layers). The raw parameter facilitates incorporating transformations directly in the URL. A layer is a distinct type of transformation that allows you to define an asset to serve as an overlay, along with its positioning and additional transformations.

#### Text as overlays

You can add any text string over a base video or image using a text layer (l-text).

For example:

```php
$imageURL = $imageKit->url(array(
    'path' => '/default-image.jpg',
    'urlEndpoint' => 'https://ik.imagekit.io/your_imagekit_id',
    'transformation' => [
        [
            'height' => '300',
            'width' => '400',
            'raw': "l-text,i-Imagekit,fs-50,l-end"
        ]
    ]
));

```
#### Sample Result URL
```
https://ik.imagekit.io/your_imagekit_id/tr:h-300,w-400,l-text,i-Imagekit,fs-50,l-end/default-image.jpg
```

**Output Image:**

![Overlay text over image](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/text-overlay-image.png?tr=w-1600>)

#### Image as overlays

You can add an image over a base video or image using an image layer (l-image).

For example:

```php
$imageURL = $imageKit->url(array(
    'path' => '/default-image.jpg',
    'urlEndpoint' => 'https://ik.imagekit.io/your_imagekit_id',
    'transformation' => [
        [
            'height' => '300',
            'width' => '400',
            'raw': "l-image,i-default-image.jpg,w-100,b-10_CDDC39,l-end"
        ]
    ]
));
```
#### Sample Result URL
```
https://ik.imagekit.io/your_imagekit_id/tr:h-300,w-400,l-image,i-default-image.jpg,w-100,b-10_CDDC39,l-end/default-image.jpg
```

**Output Image:**

![Overlay image over another image](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/image-overlay-image.png?tr=w-1600>)

#### Solid color blocks as overlays

You can add solid color blocks over a base video or image using an image layer (l-image).

For example:

```php
$imageURL = $imageKit->url(array(
    'path' => '/default-image.jpg',
    'urlEndpoint' => 'https://ik.imagekit.io/your_imagekit_id',
    'transformation' => [
        [
            'height' => '300',
            'width' => '400',
            'raw': "l-image,i-ik_canvas,bg-FF0000,w-300,h-100,l-end"
        ]
    ]
));
```

#### Sample Result URL

```
https://ik.imagekit.io/your_imagekit_id/tr:h-300,w-400,l-image,i-ik_canvas,bg-FF0000,w-300,h-100,l-end/default-image.jpg
```

**Output Image:**

![Overlay solid color over image](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/solid-color-overlay-image.png?tr=w-1600>)

### Signed URL

Signed URL that expires in 300 seconds with the default URL endpoint and other query parameters.
For a detailed explanation of the Signed URL refer to this [Official Doc](/media-delivery-basic-security#how-to-generate-signed-urls).

#### Example
```php  
$imageURL = $imageKit->url([
    "path" => "/default-image.jpg",
    "queryParameters" => 
    [
        "v" => "123"
    ],
    "transformation" => [
        [
            "height" => "300",
            "width" => "400"
        ]
    ],
    "signed" => true,
    "expireSeconds" => 300,
]);
```  
#### Response
```  
https://ik.imagekit.io/your_imagekit_id/tr:h-300,w-400/default-image.jpg?v=123&ik-t=1654183277&ik-s=f98618f264a9ccb3c017e7b7441e86d1bc9a7ebb
```  

You can manage [Security Settings](/media-delivery-basic-security#restrict-unsigned-urls) from the dashboard to prevent unsigned URLs usage. In that case, if the URL doesn't have a signature `ik-s` parameter or the signature is invalid, ImageKit will return a forbidden error instead of an actual image.

### List of supported transformations

The complete list of transformations supported and their usage in ImageKit can be found [here](/image-transformation). The SDK gives a name to each transformation parameter, making the code simpler and readable. If a transformation is supported in ImageKit, but a name for it cannot be found in the table below, use the transformation code from ImageKit docs as the name when using it in the `url` function.

| Supported Transformation Name | Translates to parameter           |
| ----------------------------- | --------------------------------- |
| height                        | h                                 |
| width                         | w                                 |
| aspectRatio                   | ar                                |
| quality                       | q                                 |
| crop                          | c                                 |
| cropMode                      | cm                                |
| x                             | x                                 |
| y                             | y                                 |
| focus                         | fo                                |
| format                        | f                                 |
| radius                        | r                                 |
| background                    | bg                                |
| border                        | b                                 |
| rotation                      | rt                                |
| blur                          | bl                                |
| named                         | n                                 |
| progressive                   | pr                                |
| lossless                      | lo                                |
| trim                          | t                                 |
| metadata                      | md                                |
| colorProfile                  | cp                                |
| defaultImage                  | di                                |
| dpr                           | dpr                               |
| effectSharpen                 | e-sharpen                         |
| effectUSM                     | e-usm                             |
| effectContrast                | e-contrast                        |
| effectGray                    | e-grayscale                       |
| effectShadow                  | e-shadow                          |
| effectGradient                | e-gradient                        |
| original                      | orig                              |
| raw                           | `replaced by the parameter value` |


## Server-side File Upload

The SDK provides a simple interface using the `$imageKit->uploadFile()` or `$imageKit->uploadFile()` method to upload files to the [ImageKit Media Library](https://imagekit.io/dashboard/media-library). [Check all the supported parameters and details](/api-reference/upload-file/upload-file).

#### Example
```php
$uploadFile = $imageKit->uploadFile([
    'file' => 'your_file',              //  required, "binary","base64" or "file url"
    'fileName' => 'your_file_name.jpg', //  required
]);
```
#### Response
```js
{
    "error": null,
    "result": {
        "fileId": "6286329dfef1b033aee60211",
        "name": "your_file_name_S-PgGysnR.jpg",
        "size": 94466,
        "versionInfo": {
            "id": "6286329dfef1b033aee60211",
            "name": "Version 1"
        },
        "filePath": "/your_file_name_S-PgGysnR.jpg",
        "url": "https://ik.imagekit.io/demo/your_file_name_S-PgGysnR.jpg",
        "fileType": "image",
        "height": 640,
        "width": 960,
        "thumbnailUrl": "https://ik.imagekit.io/demo/tr:n-ik_ml_thumbnail/your_file_name_S-PgGysnR.jpg",
        "tags": [],
        "AITags": null,
        "customMetadata": { },
        "extensionStatus": {}
    },
    "responseMetadata":{
        "headers":{
            "access-control-allow-origin": "*",
            "x-ik-requestid": "e98f2464-2a86-4934-a5ab-9a226df012c9",
            "content-type": "application/json; charset=utf-8",
            "content-length": "434",
            "etag": "W/"1b2-reNzjRCFNt45rEyD7yFY/dk+Ghg"",
            "date": "Thu, 16 Jun 2022 14:22:01 GMT",
            "x-request-id": "e98f2464-2a86-4934-a5ab-9a226df012c9"
        },
        "raw":{
            "fileId": "6286329dfef1b033aee60211",
            "name": "your_file_name_S-PgGysnR.jpg",
            "size": 94466,
            "versionInfo": {
                "id": "6286329dfef1b033aee60211",
                "name": "Version 1"
            },
            "filePath": "/your_file_name_S-PgGysnR.jpg",
            "url": "https://ik.imagekit.io/demo/your_file_name_S-PgGysnR.jpg",
            "fileType": "image",
            "height": 640,
            "width": 960,
            "thumbnailUrl": "https://ik.imagekit.io/demo/tr:n-ik_ml_thumbnail/your_file_name_S-PgGysnR.jpg",
            "tags": [],
            "AITags": null,
            "customMetadata": { },
            "extensionStatus": {}
        },
        "statusCode":200
    }
}
```
#### Optional Parameters

Please refer to [Server Side File Upload - Request Structure](/api-reference/upload-file/upload-file) for detailed explanation about mandatory and optional parameters.

```php
// Attempt File Upload
$uploadFile = $imageKit->uploadFile([
    'file' => 'your_file',                  //  required, "binary","base64" or "file url"
    'fileName' => 'your_file_name.jpg',     //  required
    // Optional Parameters
    "useUniqueFileName" => true,            // true|false
    "tags" => implode(",",["abd", "def"]),  // max: 500 chars
    "folder" => "/sample-folder",           
    "isPrivateFile" => false,               // true|false
    "customCoordinates" => implode(",", ["10", "10", "100", "100"]),    // max: 500 chars
    "responseFields" => implode(",", ["tags", "customMetadata"]),
    "extensions" => [       
        [
            "name" => "remove-bg",
            "options" => [
                "add_shadow" => true
            ]
        ]
    ],
    "webhookUrl" => "https://example.com/webhook",
    "overwriteFile" => true,        // in case of false useUniqueFileName should be true
    "overwriteAITags" => true,      // set to false in order to preserve overwriteAITags
    "overwriteTags" => true,
    "overwriteCustomMetadata" => true,
    // "customMetadata" => [
    //         "SKU" => "VS882HJ2JD",
    //         "price" => 599.99,
    // ]
    'transformation' => [ 
        'pre' => 'l-text,i-Imagekit,fs-50,l-end', 
        'post' => [
            [ 
                'type' => 'transformation', 
                'value' => 'h-100' 
            ]
        ]
    ],
]);
```  


## Media management

The SDK provides easy-to-use methods for all [APIs](/api-reference). Learn more from the [SDK documentation](https://github.com/imagekit-developer/imagekit-php).

## Utility Functions

We have included the following commonly used utility functions in this SDK.

### Authentication parameter generation

If you want to implement client-side file upload, you will need a `token`, `expiry` timestamp, and a valid `signature` for that upload. The SDK provides a simple method that you can use in your code to generate these authentication parameters for you.

{% callout style="alert" %}
The Private API Key should never be exposed in any client-side code. Instead, you must always generate these authentication parameters on the server side.
{% /callout %}

```
$imageKit->getAuthenticationParameters($token = "", $expire = 0);
```

It will return

```js
{
    "token": "5d1c4a22-54f2-40bb-9e8c-99daaeeb7307",
    "expire": 1654207193,
    "signature": "a03a88b814570a3d92919c16a1b8bd4491f053c3"
}
```  

Both the `token` and `expire` parameters are optional. If not specified, the SDK internally generates a random token and a valid expiry timestamp. The value of the `token` and `expire` used to generate the signature is always returned in the response, whether it is provided as an input to this method or not.

### Distance calculation between two pHash values

Perceptual hashing allows you to construct a hash value that uniquely identifies an input image based on the contents of an image. [ImageKit.io metadata API](/api-reference/file-metadata/get-uploaded-file-metadata) returns the pHash value of an image in the response. You can use this value to find a duplicate (or similar) image by calculating the distance between the pHash value of the two images.

This SDK exposes the `pHashDistance` function to calculate the distance between two pHash values. It accepts two pHash hexadecimal strings and returns a numeric value indicative of the level of difference between the two images.

```php
$imageKit->pHashDistance($firstHash ,$secondHash);
```

#### Distance calculation examples

```php
$imageKit->pHashDistance('f06830ca9f1e3e90', 'f06830ca9f1e3e90');
// output: 0 (same image)

$imageKit->pHashDistance('2d5ad3936d2e015b', '2d6ed293db36a4fb');
// output: 17 (similar images)

$imageKit->pHashDistance('a4a65595ac94518b', '7838873e791f8400');
// output: 37 (dissimilar images)
```


---

# Source: /integration/magento

---
title: ImageKit Magento Extension 
description: >-
  ImageKit provides an extension for Magento 2 to help you showcase products
  using high-quality images that load fast. The extension also provides Digital
  Assets Management.
---

Product images are the first thing shoppers want when they visit your store and a pixel-perfect first impression is crucial to driving conversions. Building your own, scalable, online store with thousands of high-quality, fast-loading, and responsive images is a breeze with ImageKit.

ImageKit provides an extension for Magento 2 that automatically updates all the image URLs in your entire store so that optimized images are fetched from ImageKit instead of your web server, ensuring better speed and search rankings. Additionally, you can dynamically create correctly-sized, responsive, and personalized product & marketing assets tailored to your campaigns and storefront - all within seconds and from a single master image. The extension also integrates ImageKit Media Library to help you leverage the complete suite of Digital Assets Management features. You can view the [source code](https://github.com/imagekit-developer/imagekit-magento) on GitHub.

## Getting started

Before you install the extension, make sure you have an ImageKit account.

[Sign up](https://imagekit.io/registration/) for a free plan, starting with generous usage limits and when your requirements grow, you can easily upgrade to a plan that best fits your needs. More pricing information is available [here](https://imagekit.io/plans).

### Installing the extension

You can download and install the extension from the [Magento marketplace](https://marketplace.magento.com/imagekit-imagekit-magento.html) or install it via composer by running the following commands under your Magento 2 root dir.

```
composer require imagekit/imagekit-magento
php bin/magento maintenance:enable
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy
php bin/magento maintenance:disable
php bin/magento cache:flush
```

### Configuring the extension

Once the extension is downloaded and installed, follow these steps:

1. In the Magento Admin Panel, select Stores ➡️ Configuration.
2. On the Configuration page, open the ImageKit section in the left-hand sidebar and select Settings.
3. In the ImageKit Setup section of this page:
   1. Set your ImageKit URL endpoint (or CNAME). Copy the endpoint as found in the [ImageKit URL Endpoint Section](https://imagekit.io/dashboard/url-endpoints).
   2. Set `Enable ImageKit` to Yes.
   3. Further instructions to configure origin would be given in the ImageKit origin section
   4. Once you have configured the origin in ImageKit Dashboard, set 'Configuration Complete' to Yes.
   5. Click the Save Config button at the top of the page.
4. Go to System ➡️ Cache Management and refresh your configuration and page caches. From this point onwards, if the origin is configured, any new media assets you upload will be delivered via ImageKit.

![Url Endpoints in ImageKit Dashboard](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/url-endpoint-magento.png?updatedAt=1715667292178)

![Origin Configuration Steps as shown on Extension Settings Page](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/magento-config-origin.png?updatedAt=1715667292480)

{% callout style="warning" %}
The Configure Origin can be omitted if you only want to use assets imported from the ImageKit media library to be delivered via ImageKit. If not configured, the rest of the assets will be delivered using your Magento web server.
{% /callout %}

## ImageKit Magento Extension features

With ImageKit, you can add and deliver images. The ImageKit Dashboard has multiple options to change the behavior of the ImageKit extension when serving images. These are:

* **Custom domain name** - Ability to use the [custom domain name](/docs/core-delivery-features#using-custom-domain-name) to deliver media assets e.g. http://images.yourdomain.com.
* **Automatic Image Format Optimization** - Automatically deliver images converted to modern image formats based on viewing device and browser
* **Image Quality** - Adjust the quality of generated images to balance between visual quality and file size minimization
* **Image Transforms** - Leverage ImageKit Media Library to create or modify assets depending on requirements. Learn more [here](/image-transformation).
* **ImageKit Media Library** - ImageKit Extension integrates the ImageKit Media Library right into the CMS

## ImageKit powered media delivery

Once the Origin is properly configured and the Configuration Complete option is set to Yes, you will find that all the images on your website would be automatically delivered through [ImageKit.io](https://imagekit.io)

![](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/image (74).png>)

## ImageKit Media Library integration

{% callout style="info" %}
For quick and easy access to the DAM, use the [ImageKit desktop app](/dam/app) on Windows and macOS instead of building custom integrations. This app handles simple tasks such as uploading, browsing, searching files, and dragging and dropping into your application, allowing you to streamline your workflow efficiently.
{% /callout %}

[ImageKit.io](http://imagekit.io) provides highly available storage called the Media Library to all its users. It comes with a simple user interface to upload, tag, search and manage files, and folders.

Enjoy a fully featured ImageKit Media Library directly in Magento. Use the ImageKit Media Library UI to:‌

* Upload new images
* Search, update, rename, tag, and delete files
* Organize files in folders
* Tag files based on content
* Modify creatives with a powerful and user-friendly image editor

See the [ImageKit Media Library documentation](/dam/overview) for more information‌

Look out for the “**Add from ImageKit**” button to launch the Media Library.

You can access it in the following places:‌

* **Managing your catalog** - Add category and product images to your catalog directly from the ImageKit Media Library.

![](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/magento-manage-catalog.avif?updatedAt=1715667292682)

* **Managing your site content** - Add media from ImageKit to all pages on your Magento site using the Media Library

![](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/magento-maange-site-content.avif?updatedAt=1715667292776)

## Using ImageKit Media Library to manage catalog images

You can import images from ImageKit Media Library directly to product pages.

### Adding product images from ImageKit Media Library

While creating a product, you will find the **Import From ImageKit** button in the **Images and Videos** section.

![](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/Screenshot 2021-09-30 at 1.07.55 PM.png?tr=w-1600>)

Use the ImageKit Media Library to find the image you wish to add and click on **Insert** on the top right corner.

![](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/Screenshot 2021-09-30 at 1.10.54 PM.png?tr=w-1600>)

{% callout style="info" %}
You can also select multiple images of a product at once.
{% /callout %}

![Photo by Monstera from Pexels](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/image (72).png>)

On the product page, you will find that all the product images would be delivered from [ImageKit.io](http://imagekit.io) with the optimal transformations applied‌.

![](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/image (73).png?tr=w-1600>)

### Adding Images to product description from ImageKit Media Library

You can also add images from ImageKit Media Library to the product description using the **Add from ImageKit button** in the **Select Images** modal.

![](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/Screenshot 2021-09-30 at 1.20.32 PM.png?tr=w-1600>)

## Using Magento page builder to import images

Use the Media section of the Page Builder panel, you can add images, banners, or sliders from ImageKit to any layout container on the [Page Builder stage](https://docs.magento.com/user-guide/cms/page-builder-workspace.html#stage). After adding a Media Block to the page builder stage, you’ll have the option to select the images from ImageKit.

![](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/image (75).png?tr=w-1600>)

For instance, to add an image from ImageKit, drag and drop an image block into the page builder stage, then click **Select from Gallery**. You can open the ImageKit Media Library to manage and insert your ImageKit images by clicking **Add from ImageKit** button.

![](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/Screenshot 2021-09-30 at 1.43.47 PM.png?tr=w-1600>)

## Using ImageKit.io to deliver non-image static assets like JS or CSS

You can also use ImageKit.io to deliver non-image type static assets like JS, CSS, or font files. Navigate to Stores ➡️ Configurations ➡️ Web:

For **Base URL for Static View Files**, set`your_imagekit_url_endpoint_with_origin_configured/static/`  or `your_imagekit_url_endpoint_with_origin_configured/pub/static/`  depending on your setup.

![](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/image (76).png?tr=w-1600>)


---

# Source: /integration/wordpress

---
title: ImageKit WordPress Plugin
description: Integrate ImageKit with your WordPress website using the official plugin for automatic image & video optimization, CDN delivery, and asset management.
---

Integrate ImageKit into your WordPress website using our [official WordPress plugin](https://wordpress.org/plugins/imagekit/). The plugin automatically optimizes and delivers your images, videos, and static assets through ImageKit's CDN, improving your site's performance without requiring code changes.

With the Enhanced Media Library integration, you can browse, search, and insert assets from your ImageKit Media Library directly within WordPress - in both the classic media modal and the Gutenberg block editor. This eliminates the need to switch between WordPress and ImageKit when working with your media assets.

The plugin [source code](https://github.com/imagekit-developer/imagekit-wordpress) is available on GitHub.

## Plugin capabilities
{% table %}
- **Feature** {% width="50%" %}
- **Available** {% width="50%" %}
---
- Image optimization and delivery
- **Yes** \
  Automatic format conversion (WebP, AVIF), quality optimization, and metadata removal. All images delivered through ImageKit CDN without modifying originals.
---
- Video optimization and delivery
- **Yes** \
  Automatic video optimization for faster playback. Apply global transformations like resize, crop, and format conversion using [ImageKit URL-based transformations](https://imagekit.io/docs/video-transformation).
---
- Static asset delivery
- **Yes** \
  Deliver theme, plugin, and WordPress core CSS & JS files via ImageKit CDN with granular per-category toggles.
---
- Responsive images
- **Yes** \
  Automatically generate responsive image breakpoints with configurable settings for optimal delivery across devices.
---
- Media offloading
- **Yes** \
  Upload new media library files to ImageKit with flexible storage options - keep originals locally, store low-resolution copies, or offload entirely.
---
- Enhanced Media Library integration
- **Yes** \
  Browse, search, and insert ImageKit assets directly from WordPress media modal and Gutenberg block editor.
---
- Lazy loading
- **WordPress native** \
  WordPress 5.5+ includes native lazy loading for images.
{% /table %}

## Integration steps

Here is what you need to do:

### Step 1: Install and activate the ImageKit plugin

Install and activate the [ImageKit WordPress plugin](https://wordpress.org/plugins/imagekit/) from the WordPress plugin directory. After activation, the plugin launches a **setup wizard** that walks you through configuring your credentials and delivery preferences.

![Setup wizard - Welcome](https://ik.imagekit.io/ikmedia/docs_images/wordpress/wizard-step1.png)

### Step 2: Setup credentials

Enter your ImageKit credentials from the [Developer section](https://imagekit.io/dashboard/developer/api-keys) of your ImageKit dashboard. You'll need to provide your **URL endpoint** (e.g., `https://ik.imagekit.io/your_imagekit_id`), **public key**, and **private key**.

The wizard also guides you through configuring your WordPress site as a [web server](/integration/web-server) origin in ImageKit, with your site URL as the base URL. If you have a different setup, such as an [Amazon S3 bucket](/integration/aws-s3), configure the appropriate origin in the [external storage section](https://imagekit.io/dashboard/external-storage) of your ImageKit dashboard.

![Setup wizard - Credentials](https://ik.imagekit.io/ikmedia/docs_images/wordpress/wizard-step2.png)

{% callout style="info" %}
The **URL endpoint** is required for asset delivery (URL rewriting). The **public key** and **private key** are additionally needed for media uploads, the Enhanced Media Library, and usage statistics.
{% /callout %}

You can verify that asset delivery is working by fetching an asset through your ImageKit [URL endpoint](/integration/connect-external-storage#url-endpoints). When you add the first origin in your account, it automatically becomes accessible through the [default URL endpoint](/integration/connect-external-storage#url-endpoints), that is `https://ik.imagekit.io/your_imagekit_id`. Otherwise, you will have to [configure an existing](/integration/connect-external-storage#origin-preference) URL endpoint or create a new one to fetch assets from this newly added origin.

If your old asset URL was `https://www.example.com/wp-content/uploads/image.jpg`, then the same asset should be accessible through your ImageKit URL endpoint:

`https://ik.imagekit.io/your_imagekit_id/wp-content/uploads/image.jpg`

### Step 3: Delivery toggles

Choose what you'd like to deliver through ImageKit. All options are enabled by default and can be changed later in the plugin settings. You can enable delivery for **Images** (optimized via ImageKit CDN with automatic format conversion), **Videos** (for faster playback), and **Assets** (theme, plugin, and WordPress core CSS & JS files).

![Setup wizard - Delivery toggles](https://ik.imagekit.io/ikmedia/docs_images/wordpress/wizard-step3.png)

{% callout style="success" %}
After completing the wizard, your WordPress media and assets will be delivered through ImageKit. You can further configure the plugin using the settings pages described below.
{% /callout %}

## Enhanced Media Library

Access your ImageKit Media Library directly from WordPress. This feature integrates seamlessly with both the classic media modal and the Gutenberg block editor.

![Gutenberg block editor integration](https://ik.imagekit.io/ikmedia/docs_images/wordpress/gutenberg-integration.png?tr=cm-extract,w-1342,h-500,fo-top)

To use the Enhanced Media Library:

1. Open the WordPress media modal (when adding an image to a post or page)
2. Click **Open Media Library** button to browse your ImageKit assets
3. Search, filter, and select assets from your ImageKit account
4. Insert selected assets directly into your content

![Import from ImageKit using media modal](https://ik.imagekit.io/ikmedia/docs_images/wordpress/media-library-integration.png)

This integration requires your **public key** and **private key** to be configured in the plugin settings.

## Plugin settings

After setup, navigate to **ImageKit** in the WordPress admin sidebar to access the plugin settings. The settings are organized across multiple pages:

### General settings

The General settings page shows your connection status, configured credentials, media library upload settings, and current usage summary.

![General settings](https://ik.imagekit.io/ikmedia/docs_images/wordpress/general-settings.png)

#### Connection status

Displays your current ImageKit connection state and configured credentials (URL endpoint, public key, private key). From here you can **Reconfigure** to re-run the setup wizard and update credentials, or **Disconnect** to remove the ImageKit connection.

#### Media library upload settings

Configure how new media library uploads are handled. The ImageKit folder path specifies the folder in your ImageKit account where WordPress assets are uploaded to (leave blank to use the root). The Storage option lets you choose where your assets are stored:

{% table %}
- **Mode** {% width="35%" %}
- **Description** {% width="65%" %}
---
- ImageKit and WordPress
- Stores assets in both locations. Enables local WordPress delivery if the plugin is disabled or uninstalled.
---
- ImageKit and WordPress (low resolution)
- Stores original assets in ImageKit and low-resolution versions in WordPress. Enables low-resolution local fallback delivery.
---
- ImageKit only
- Stores assets in ImageKit only. Requires additional steps to enable backwards compatibility if the plugin is removed.
---
- WordPress only
- Stores assets in WordPress only and disables uploading new assets to ImageKit.
{% /table %}

#### Current usage summary

The sidebar displays your current ImageKit account usage, including Media Library Storage, Original Cache Storage, Bandwidth, Video Processing Units, and Extensions Units. Click Go to ImageKit Dashboard for detailed analytics.

### Image settings

Control how images are delivered through ImageKit.

![Image settings](https://ik.imagekit.io/ikmedia/docs_images/wordpress/image-settings.png)

Toggle Image delivery to enable or disable delivering images from ImageKit (when disabled, images are served from WordPress). Global image transformations lets you apply a set of [ImageKit URL-based transformations](https://imagekit.io/docs/transformations) to all images using ImageKit transformation syntax, e.g., `q-80,f-webp` for 80% quality in WebP format.

### Video settings

Control how videos are delivered through ImageKit.

![Video settings](https://ik.imagekit.io/ikmedia/docs_images/wordpress/video-settings.png)

Toggle Video delivery to enable or disable delivering videos from ImageKit (when disabled, videos are served from WordPress). Global video transformations lets you apply a set of [ImageKit video transformations](https://imagekit.io/docs/video-transformation) to all videos using ImageKit transformation syntax, e.g., `h-400,w-400`.

### Asset settings

Control which static assets (CSS and JavaScript files) are delivered through ImageKit CDN.

![Asset settings](https://ik.imagekit.io/ikmedia/docs_images/wordpress/asset-settings.png)

The plugin provides six granular toggles organized by source: Theme CSS, Theme JS, Plugin CSS, Plugin JS, WordPress Core CSS, and WordPress Core JS. Each toggle controls whether that category of static files is delivered through ImageKit CDN.

#### Excluding specific assets

To exclude specific assets from being rewritten to ImageKit URLs, use the WordPress filter hooks `imagekit_exclude_url` (for media URLs) or `imagekit_exclude_asset_url` (for CSS/JS asset URLs).

Example:
```php
// Exclude a specific CSS file from ImageKit delivery.
add_filter( 'imagekit_exclude_asset_url', function( $exclude, $url, $handle, $type ) {
    if ( 'my-plugin-style' === $handle ) {
        return true;
    }
    return $exclude;
}, 10, 4 );
```

### Responsive images

Serve perfectly sized images to every device, reducing bandwidth usage and improving page load speeds. This feature automatically generates custom `srcset` breakpoints, allowing browsers to download only the image size they need - smaller images for mobile devices, larger ones for desktop.

![Responsive images](https://ik.imagekit.io/ikmedia/docs_images/wordpress/responsive-images.png)

Toggle Enable responsive image breakpoints to automatically generate responsive `srcset` breakpoints for your images. When enabled, you can customize:

- Breakpoint distance - Minimum pixel difference between breakpoints (default: 150px)
- Maximum images - Maximum number of breakpoint images to generate (default: 15)
- Minimum image width - Smallest breakpoint width (default: 32px)
- Maximum image width - Largest breakpoint width (default: 3840px)

## Troubleshooting

If you encounter issues, a detailed system report is available on the **Get Help** page in the plugin settings. The report includes your WordPress environment details, active theme, plugins, ImageKit plugin configuration, and PHP settings. You can copy or download the report to share with ImageKit support.

![System report](https://ik.imagekit.io/ikmedia/docs_images/wordpress/system-report.png)

## Best practices

1. Always back up your site before installing the plugin or making significant configuration changes.
2. Start with images and videos - enable these first for immediate performance gains.
3. Test asset delivery gradually - enable CSS and JS delivery one category at a time to ensure compatibility.
4. Monitor your usage - check the usage summary in General settings regularly to track bandwidth and storage.
5. Configure API keys - provide public and private keys to unlock all features including media uploads and Enhanced Media Library.


---

# Source: /integration/shopify

---
title: ImageKit Shopify Extension 
description: How does ImageKit Shopify Extension works.
---

Shopify is a e-commerce platform that has gained quite a lot of traction in the last few years given the great feature set, ease of use and nominal pricing that comes with starting an e-commerce store on Shopify.

{% callout style="info" %}
For quick and easy access to the DAM, use the [ImageKit desktop app](/dam/app) on Windows and macOS instead of building custom integrations. This app handles simple tasks such as uploading, browsing, searching files, and dragging and dropping into your application, allowing you to streamline your workflow efficiently.
{% /callout %}

Integrating ImageKit on Shopify store allows you to improve your image quality and delivery speed.

{% callout style="info" %}
The integration with Shopify involves making some changes to your website’s theme files.
{% /callout %}

Here are the steps to optimize images on your Shopify website.

## Step 1: Configure origin in ImageKit.io dashboard

Configure a [web server](/integration/web-server) origin based on where your images are stored. In Shopify, this is your CDN base URL i.e. `https://cdn.shopify.com`, `https://cdn2.shopify.com` or `https://cdn.shopifycloud.com`. You can check this under the network panel tab in Chrome like shown in the screenshot below:

![](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/adyhsz7y9lb8hxpbunr2.jpg)

## Step 2: Fetch image through ImageKit.io endpoint

Let's quickly fetch the image using ImageKit.io [URL endpoint](/integration/connect-external-storage#url-endpoints) and see if it's working.

When you add the first origin in your account, it automatically becomes accessible through the [default URL endpoint](/integration/connect-external-storage#url-endpoints), that is `https://ik.imagekit.io/your_imagekit_id`. Otherwise, you will have to [configure an existing](/integration/connect-external-storage#origin-preference) URL endpoint or create a new one to fetch images from this newly added origin.

If your old image URL was [`https://cdn.shopify.com/img/s/files/1/1510/6482/t/22/assets/logo-mobile.png`](https://cdn.shopify.com/img/s/files/1/1510/6482/t/22/assets/logo-mobile.png) , then the same image should be accessible through ImageKit.io URL endpoint, i.e., [`https://ik.imagekit.io/your_imagekit_id/img/s/files/1/1510/6482/t/22/assets/logo-mobile.png`](https://ik.imagekit.io/your_imagekit_id/img/s/files/1/1510/6482/t/22/assets/logo-mobile.png)

{% callout style="alert" %}
**Unable to fetch image?**

Contact [support@imagekit.io](mailto:support@imagekit.io) if you are not able to fetch the image as explained above. In such a situation, do not move to step 3 as this could break your website images.
{% /callout %}

## Step 3: Create settings_schema.json

If the above image did work correctly, we can now proceed to make the changes in our Shopify settings and theme files to switch the image delivery and optimization to ImageKit.

From your Shopify admin, click **Online Store** :arrow_right:**Themes**. Find the theme you want to edit, click the `...` button, and then click **Edit HTML/CSS**.

Under **Config**, click `settings_schema.json` and copy the code below as the last section of config file and hit save.

```javascript
{
    "name": "ImageKit",
    "settings": [
        {
            "type": "paragraph",
            "content": "Check out ImageKit's [ImageKit.io and Shopify integration](https://imagekit.io/docs/integration/shopify) to learn more about this."
        },
        {
            "type": "checkbox",
            "id": "enableImageKit",
            "label": "Enable Imagekit"
        },
        {
            "type": "text",
            "id": "imagekitUrl",
            "label": "ImageKit url endpoint",
            "info":"The URL endpoint you set within ImageKit. Example: `https://ik.imagekit.io/your_imagekit_id/`."
        },
        {
            "type": "text",
            "id": "imagekitShopifyCdnUrl",
            "label": "Shopify CDN domain",
            "default":"//cdn.shopify.com",
            "info":"Do not change this unless you have a proxy in place. Not sure? Leave it as is."
        }
    ]
}
```

## Step 4: Create imagekit.liquid file

Create a new file `imagekit.liquid` under Snippets directory. Copy the code below into that file, and save it.

{% example %}

``` {% process=false %}
{% capture IMAGEKIT %}
  {% if settings.enableImageKit %}
    {% for i in (1..1) %}
      {% unless src or settings.imagekitUrl != blank %}
        {{ src }}
        {% break %}
      {% endunless %}
      {% assign cdnUrls = settings.imagekitShopifyCdnUrl | split: ',' %}
    {% if cdnUrls.size  == 0 %}
    {{ src }}
        {% break %}
    {% endif %}
      {% assign cdnUrl = cdnUrls[0] %}
      {% for temp in cdnUrls %}
        {% if src contains temp %}
          {% assign cdnUrl = temp %}
          {% break %}
        {% endif %}
      {% endfor %}
    {% assign cdnUrl = cdnUrl | strip %}
    {% unless src contains cdnUrl %}
        {{ src }}
        {% break %}
      {% endunless %}
    {% assign imagekitUrl = settings.imagekitUrl | strip %}
      {% assign tempImagekitUrl = imagekitUrl %}
      {% assign lastChar = imagekitUrl | slice:-1 %}
      {% assign imagekitUrlLength = imagekitUrl | size %}
      {% assign newImagekitUrl = imagekitUrlLength | minus:1 %}
      {% if lastChar == "/" %}
        {% assign tempImagekitUrl = imagekitUrl | slice:0,newImagekitUrl %}
      {% endif %}
    {% assign newSrc = src | strip | replace:cdnUrl,tempImagekitUrl %}
    {{ newSrc | default:src }}
    {% endfor %}
  {% else %}
    {{ src }}
  {% endif %}
{% endcapture %}{{ IMAGEKIT | strip | replace:'  ' | strip_newlines }}
```

{% /example %}

## Step 5: Enable ImageKit.io

Navigate to **Online store** :arrow_right:**Themes** :arrow_right:**Customize theme**. In the sidebar, under general settings open ImageKit and enable it. Fill out the below two fields:

* Default URL endpoint - It should be `https://ik.imagekit.io/your_imagekit_id`
* Shopify CDN domain - Its value should be `//cdn2.shopify.com,//cdn.shopify.com`
* Hit the "Save" button.

## Step 6: Edit theme files

Now we get to editing your theme files. We first need to find out the files which are responsible for the output of image on your store and start editing them.

{% callout style="warning" %}
**Backup your theme files**

Before making changes in these files, it is recommended that you download and save them securely to be able to restore it later, in case of error.
{% /callout %}

Here are a couple of examples indicating the change that needs to be made in the theme files. You can follow similar steps to change all of your theme files.

### Example 1

{% example %}
``` {% process=false %}
Before
<img class="grid-view-item__image" src="{% product.featured_image.src | img_url: grid_image_width %}" alt="{{ product.featured_image.alt }}">

After
{% assign old_img_url = product.featured_image.src | img_url:grid_image_width %}
<img class="grid-view-item__image" src="{% include 'imagekit' src:old_img_url %}" alt="{{ product.featured_image.alt }}">
```
{% /example %}

### Example 2

{% example %}

``` {% process=false %}
Before:
<img src="{% featured_img_src | img_url: product_image_size %}" alt="{{ featured_img_alt }}" id="FeaturedImage-{{ section.id }}" class="product-featured-img{% if enable_zoom %} js-zoom-enabled{% endif %}">

After:
{% assign old_img_url = featured_img_src | img_url: product_image_size %}
<img src="{% include 'imagekit' src:old_img_url %}" alt="{{ featured_img_alt }}" id="FeaturedImage-{{ section.id }}" class="product-featured-img{% if enable_zoom %} js-zoom-enabled{% endif %}">
```

{% /example %}


### Example 3

If there is a tag inside image URL and you cannot simply assign it, use [capture](https://help.shopify.com/en/themes/liquid/tags/variable-tags#capture).

{% example %}
``` {% process=false %}
Before:
<img width="{{ image.width }}" height="{{ image.height }}" src="{{ image | img_url: '50x50' }}" class="lazyload attachment-shop_single size-shop_single sp-post-image" alt="{{image.alt}}" title="{{product.title}}" 
data-src="{{ img_url }}" 
data-large_image="{%-include 'gl_image_format',cache:true, src: image.src, size: product_image_photowipe -%}" data-large_image_width="{{ image.width }}" data-large_image_height="{{ image.height }}" 
data-widths="[180, 360, 540, 720, 900, 1080, 1296, 1512, 1728, 2048]" data-aspectratio="{{ image.aspect_ratio }}" data-sizes="auto">

After:
{% assign old_img_src = image | img_url: '50x50' %}
{% assign old_img_data_src = img_url %}

{% capture old_img_data_large_image %}
{%-include 'gl_image_format',cache:true, src: image.src, size: product_image_photowipe -%}
{% endcapture %}
<img width="{{ image.width }}" height="{{ image.height }}" src="{% include 'imagekit' src:old_img_src %}" class="lazyload attachment-shop_single size-shop_single sp-post-image" alt="{{image.alt}}" title="{{product.title}}" 
data-src="{% include 'imagekit' src:old_img_data_src %}" 
data-large_image="{% include 'imagekit' src:old_img_data_large_image %}" data-large_image_width="{{ image.width }}" data-large_image_height="{{ image.height }}" 
data-widths="[180, 360, 540, 720, 900, 1080, 1296, 1512, 1728, 2048]" data-aspectratio="{{ image.aspect_ratio }}" data-sizes="auto">
```
{% /example %}

## FAQ

### Can I disable ImageKit.io with a single click?

Yes you can enable and disable ImageKit.io on your Shopify store with a single click. Navigate to **Online store** > **Themes** > **Customize theme**. In the sidebar, under general settings open ImageKit.io and enable/disable it.

### Can ImageKit.io automatically detect the right image dimension and load it?

No ImageKit.io only changes the base URL of your images because there is no way the server would have knowledge of your website layout. However, just by loading images through ImageKit.io URL endpoint, your images are automatically optimized for format and quality.

### How do I make sure my integration is working?

Once you are done editing these files, save these files. Now refresh the webpage for your Shopify store and check the image URLs. They should now load from URLs beginning with `https://ik.imagekit.io/your_imagekit_id`. You can use the Chrome Developer Tools to check that all the images are being loaded via ImageKit.io and that all images are loading correctly. If you find that images on a particular page or section is still being served from Shopify, then find out the responsible theme file and edit it as well.


---

# Source: /integration/netlify

---
title: Netlify Integration with ImageKit.io
description: Power your Netlify site, delivering high-quality optimized images with the help of ImageKit.
---

Netlify is a powerful platform that provides a complete end-to-end solution for building highly performant and dynamic websites, e-commerce stores, and web applications.

This integration with ImageKit will facilitate the delivery of superior, high-quality images to users visiting your Netlify site. You can view the plugin [source code](https://github.com/imagekit-developer/imagekit-netlify) on GitHub.

## Prerequisites

Before starting, you must set up a URL endpoint pointing to a web proxy origin as described below.

- Add web proxy origin by following [these steps](./web-proxy.md).

- Add the above web proxy origin as the URL endpoint by following [these steps](./connect-external-storage#creating-a-new-url-endpoint).

After following the above steps, you will have the ImageKit URL endpoint.

```
https://ik.imagekit.io/{imagekit_id}/{origin_identifier}
```

## Setup ImageKit Netlify plugin

Currently you can integrate plugin with the help of [file-based installation](https://docs.netlify.com/integrations/build-plugins/#file-based-installation).

### 1. Add the plugin to your Netlify configuration file `netlify.toml`:

```toml
[[plugins]]
  package = "netlify-plugin-imagekit"
```

### 2. Add the ImageKit URL endpoint:

```toml
[[plugins]]
  package = "netlify-plugin-imagekit"

  [plugins.inputs]
  urlEndpoint = "https://ik.imagekit.io/{imagekit_id}/{origin_identifier}"
```

{% callout style="info" %}
**Note:** You can also set `IMAGEKIT_URL_ENDPOINT` env variable as an alternative to providing urlEndpoint in a plugin input.
The environment variable can be set in multiple ways through [Netlify UI, Netlify API, or Netlify CLI](https://docs.netlify.com/environment-variables/get-started/#create-variables-with-the-netlify-ui-cli-or-api). You can also pass environment variable through [Netlify configuration file](https://docs.netlify.com/environment-variables/get-started/#create-variables-with-a-netlify-configuration-file) `netlify.toml`.
{% /callout %}


### 3. Optionally adding `imagesPath`:

```toml
 [[plugins]]
  package = "netlify-plugin-imagekit"

  [plugins.inputs]
  urlEndpoint = "https://ik.imagekit.io/{imagekit_id}/{origin_identifier}"
  imagesPath = ["/my-image-path","my-image-path-two"] // default value is set to "images"
```

 It specifies the paths, relative to the [publish directory](https://docs.netlify.com/configure-builds/overview/#set-the-publish-directory), where images are stored and should be served through the ImageKit server. If images are stored in multiple directories, you can provide an array to `imagesPath`, and all such images will be redirected to ImageKit. If no value is provided, the default value is set to images.

 {% callout style="info" %}
 **Publish Directory:**
 When deploying a front-end project on Netlify, the deployment is done after running the build command, which generates a folder containing the build output. The name of this folder can vary depending on the framework being used. For example, the folder might be named `build` or `dist` in a `React` project. This folder's path must be specified as the publish directory in Netlify.

 Find a comprehensive list of build commands and publish directories for various frameworks on Netlify [here](https://docs.netlify.com/frameworks/).
{% /callout %}

### 4. Add dev dependency
 Lastly, add `netlify-plugin-imagekit` as a dev dependency in your front-end project as mentioned [here](https://docs.netlify.com/integrations/build-plugins/#add-dependency).

```
// using npm
npm install -D netlify-plugin-imagekit

// using yarn 
yarn add --dev netlify-plugin-imagekit
```
### 5. Deploy

To see the ImageKit Netlify plugin in action, trigger the build and observe all the image assets being delivered through the ImageKit server. To learn more about how to deploy a site from scratch, check out the [blog](https://www.netlify.com/blog/2016/09/29/a-step-by-step-guide-deploying-on-netlify/).

## How does it work?
After following the above steps, the ImageKit plugin will work out of the box. Internally, it uses the mechanism below to deliver highly optimized images.

### 1. Modify URLs in production-ready HTML files
This is useful in scenarios where proper HTML files are generated after the build process. For these frameworks, the plugin taps into the `onPostBuild` hook, using `jsdom` to create a node-based representation of the DOM for each output HTML file. It then walks through each node, and upon finding an img or picture tag, it replaces the `src` or `srcset` path with an ImageKit URL as shown below for a demo project.
{% linetabs %}

{% linetab title="Before build" %}

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Demo Project</title>
</head>
<body>
  <img src="/myImages/girl.webp" alt="girl">
  <img src="https://demo.com/premium_photo" width="500" alt="remote">
</body>
</html>
```
{% /linetab %}

{% linetab title="After build" %}

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Demo Project</title>
</head>
<body>
  <img src="https://ik.imagekit.io/{imagekit_id}/{origin_identifier}/tr:f-auto/https://netlify-demoo.netlify.app/myImages/girl.webp"
    alt="girl">
  <img
    src="https://ik.imagekit.io/{imagekit_id}/{origin_identifier}/tr:f-auto/https://demo.com/premium_photo"
    width="500" alt="remote">
</body>
</html>
```
{% /linetab %}

{% /linetabs %}

While this approach works well for many situations, especially during the initial page load, it fails when using a framework with client-side routing or features that alter the DOM or that does not generate HTML files on build, such as `React`. This necessitates the use of the mechanism described below.

### 2. Redirect assets through the ImageKit Server

In this approach, all asset paths relative to the publish directory as `imagesPath` is specified. Then, using the redirect feature of [Netlify Redirects and rewrites](https://docs.netlify.com/routing/redirects/), we redirect the existing image URLs from the Netlify server to the ImageKit server. The ImageKit server fetches the original image, optimizes it, and then serves it back to the end user.

As we can observe in the network tab, the first request to `https://react-webpack-netlify.netlify.app/images/cat.jpeg` is redirected, and consequently, the asset is fetched through the ImageKit server
`https://ik.imagekit.io/a1yisxurxo/proxy/tr:f-auto/https://react-webpack-netlify.netlify.app/imagekit-netlify-asset/images/cat.jpeg`.

![](<https://ik.imagekit.io/a1yisxurxo/redirectFeature?tr=t-true:b-10_grey>)

## Limitations

- When external or third-party URLs are used instead of static assets in frameworks like `React` that do not generate HTML files after the build process or mutate the DOM on the client side, these URLs will not be replaced by ImageKit URLs. To address this issue, you can use the ImageKit client-side SDK, [imagekit-react](https://github.com/imagekit-developer/imagekit-react?tab=readme-ov-file#quick-examples) to serve third-party URLs through the ImageKit server.

- Another limitation is that when base64 URLs are used for images, no separate request is made to the backend to fetch the images. As a result, these images cannot be replaced.

## Link

The link to official repository can be found [here](https://github.com/imagekit-developer/imagekit-netlify/).


---

# Source: /integration/strapi

---
title: Strapi Integration with ImageKit.io
description: Power your Strapi instance, delivering high-quality optimized images with the help of ImageKit.
---

Strapi is a leading open-source headless CMS for building custom websites and applications. Integrating Strapi with ImageKit offloads image storage and enables real-time image optimization and transformation, improving performance and user experience on your website.

This guide walks you through installing and configuring the ImageKit provider for Strapi's upload plugin. You can view the [source code](https://github.com/imagekit-developer/strapi-plugin-imagekit) on GitHub.

## Plugin Features

- **Media Library Integration**: Browse and manage your ImageKit media library directly in Strapi.
- **Bulk Import**: Import existing ImageKit assets into Strapi with a single click.
- **Optimized Delivery**: Serve optimized images and videos through ImageKit.
- **Upload**: Upload new files to ImageKit directly from the Strapi media library.
- **Signed URLs**: Deliver signed URLs for your media assets.

## Prerequisites

Before you begin, you need:
- A Strapi project (v5 or later)
- Node.js and npm/yarn installed
- Administrator access to your Strapi instance

You can refer to strapi's [official documentation](https://docs.strapi.io/cms/quick-start) to understand the prerequisites for running your strapi instance.

## Installation

To install the ImageKit plugin in your strapi instance, run the following command from your project's root directory:

**Using NPM:**
```bash
npm install strapi-plugin-imagekit --save
```

**Using Yarn:**
```bash
yarn add strapi-plugin-imagekit
```

Once installed, you must rebuild your Strapi instance by running the following command:

**Using NPM:**
```bash
npm run build
npm run develop
```

**Using Yarn:**
```bash
yarn build
yarn develop
```

After rebuilding, the **ImageKit** plugin will appear in the sidebar and Settings section. Complete the [essential configuration](#essential-imagekit-plugin-configuration) steps immediately after this, followed by the [Content Security Policy](#configure-security-middleware-csp) update for the ImageKit Media Library to work.

|                                                                                                                     |                                                                                              |
| ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| ![](https://ik.imagekit.io/ikmedia/docs_images/integration/strapi/sidebar_screenshot.png?tr=h-960,w-1898,fo-left) | ![](https://ik.imagekit.io/ikmedia/docs_images/integration/strapi/settings_screenshot.png) |


## Essential ImageKit Plugin Configuration

You can configure the ImageKit plugin from within the Strapi admin dashboard just like you would do for other plugins. This section contains the essential credentials to connect with your ImageKit account. You should update these settings immediately after installing the plugin. Other settings for media delivery and media uploads are covered in subsequent sections.

1. **Public Key**: Obtain your public key (prefixed with `public_`) from the [API Keys section](https://imagekit.io/dashboard/developer/api-keys) of your ImageKit dashboard.

2. **Private Key**: Copy your private key (prefixed with `private_`) from the same dashboard page.
   > **Note:** Keep your private key confidential as it grants full access to your ImageKit account

3. **URL Endpoint**: Get your endpoint URL (formatted as `https://ik.imagekit.io/your_imagekit_id`) from the same dashboard page.

![ImageKit API Keys Dashboard](https://ik.imagekit.io/ikmedia/docs_images/integration/strapi/api_keys_dashboard.png)

## Media Delivery Configuration

These settings help you deliver the existing assets in the Strapi Media Library via ImageKit. It doesn't move any asset to the ImageKit Media Library.

1. **Configure Web Folder Origin**: Add Strapi as a web folder origin in your ImageKit dashboard (ignore if already done). Follow the [Web Server Integration Documentation](/integration/web-server) for detailed steps.

2. **Enable Integration**: Toggle **Enable Plugin** to ON to activate ImageKit integration for media handling. When OFF, Strapi will use the default provider for uploads.
3. **Enable Transformations**: **Use Transform URLs** toggle when ON leverages ImageKit's real-time transformations, generating responsive URLs with automatic format detection and image optimization capabilities. When OFF, original images are served without transformations.
4. **Configure Secure Access** (recommended):
   - Enable **Use Signed URLs**.
   - Set an appropriate **Expiry** time (0 for URLs that never expire, or a duration in seconds).

## Media Upload Configuration

These settings copy any image uploaded to the Strapi Media Library to the ImageKit Media Library as well. 

1. **Enable Uploads**: Toggle this option ON to upload the files uploaded in Strapi to your ImageKit media library. When OFF, files will be uploaded to the default Strapi storage location. Enabling this option does not upload existing files in Strapi to ImageKit.

2. **Set Upload Properties**:
   - **Upload Folder**: Specify a base directory path in ImageKit for organizing your uploads.
   - **Tags**: Add comma-separated tags to categorize and filter media assets.
   - **Overwrite Tags**: Choose whether to replace existing tags or append new ones.

3. **Configure Security & Validation**:
   - **File Checks**: Define validation rules for uploads such as size limits or allowed file types. See [Upload API Checks](https://imagekit.io/docs/api-reference/upload-file/upload-file#upload-api-checks) for available options.
   - **Mark as Private**: Toggle ON to restrict public access to uploaded files.

## Advanced: Programmatic configuration

While the primary way to configure the ImageKit plugin is through the Strapi admin settings page, you can also provide default values in your Strapi project's `config/plugins.js` file. This is particularly useful for setting up initial configurations in development or deployment environments.

Settings defined in `config/plugins.js` serve as default values that are copied to the dashboard on the first run of your Strapi application. After this initial setup, any changes made through the admin UI will be stored in the database and will be used instead of the values in the configuration file.

Here's an example showing essential credentials pulled from environment variables, with other common settings hardcoded:

```js
module.exports = ({ env }) => ({
  imagekit: {
    enabled: true,
    config: {
      // Basic Configuration
      publicKey: env("IMAGEKIT_PUBLIC_KEY"),
      privateKey: env("IMAGEKIT_PRIVATE_KEY"),
      urlEndpoint: env("IMAGEKIT_URL_ENDPOINT"),

      // Delivery Configuration
      enabled: true,
      useTransformUrls: true,
      useSignedUrls: false,
      expiry: 3600, // URL expiry time in seconds when useSignedUrls is true

      // Upload Configuration
      uploadEnabled: true,

      // Upload Options
      uploadOptions: {
        folder: "/strapi-uploads/",
        tags: ["strapi", "media"],
        overwriteTags: false,
        checks: "", // Example: '"file.size" <= "5MB"'
        isPrivateFile: false,
      },
    },
  },
});
```

You can source more settings from environment variables if needed by parsing them accordingly (e.g., convert string 'true' to boolean true).

Remember to set these environment variables in your .env file:

```
IMAGEKIT_PUBLIC_KEY=public_xxxxxxxxxxxxxxxx
IMAGEKIT_PRIVATE_KEY=private_xxxxxxxxxxxxxxxx
IMAGEKIT_URL_ENDPOINT=https://ik.imagekit.io/your_imagekit_id
```

## Using ImageKit Assets in Strapi

To use any media asset in Strapi, it must first be brought into the Strapi Media Library. Therefore, to utilize the assets stored in the ImageKit Media Library within Strapi, we first need to import them into Strapi.

1. Head to the ImageKit Media Library from the menu on the left.
2. Find the files you want to bring to the Strapi Media Library, select them all, and click on the "Insert" button at the top of the ImageKit Media Library.
3. You should see a success message when the import is completed, and the files should then start showing up in the Strapi Media Library as well. These assets can then be inserted into any content in the CMS.

When importing assets in this manner, Strapi does not create a copy of them in its Media Library. So you won't find these assets in the `public/uploads` folder like the other assets you upload directly to the Strapi Media Library. Instead, Strapi refers to the ImageKit asset directly via its URL and uses that URL to load the asset. Any asset inserted in this manner will always be accessed via its ImageKit URL, rather than the Strapi Media URL. You can validate this by fetching content that uses an ImageKit asset inserted in this way and verifying that it is always referenced by its ImageKit URL.

## Configure Security Middleware (CSP)

To ensure your Strapi application can securely load assets and interact with ImageKit services, you need to update your Content Security Policy (CSP) settings. This is configured in the `strapi::security` middleware.

Modify your `config/middlewares.js` file as follows. This configuration allows your Strapi admin panel and frontend (if applicable) to load images, videos, and the embedded frame for the ImageKit Media Library, while maintaining a secure policy:

```js
// config/middlewares.js
module.exports = [
  {
    "name": "strapi::security",
    "config": {
      "contentSecurityPolicy": {
        "useDefaults": true,
        "directives": {
          "connect-src": ["'self'", "https:"],
          "img-src": [
            "'self'",
            "data:",
            "blob:",
            "market-assets.strapi.io",
            "ik.imagekit.io", // ImageKit domain for images, add your custom domain if you use one
          ],
          "media-src": [
            "'self'",
            "data:",
            "blob:",
            "market-assets.strapi.io",
            "ik.imagekit.io", // ImageKit domain for videos/audio, add your custom domain if you use one
          ],
          "frame-src": [
            "'self'",
            "data:",
            "blob:",
            "eml.imagekit.io", // For ImageKit UI components
          ],
          "upgradeInsecureRequests": null,
        },
      },
    },
  },
  // Keep your other middleware entries as it is
];
```

> **Important**: If you use a custom domain with ImageKit, add or update the relevant lines with your custom domain.


---

# Source: /integration/contentful

---
title: Contentful Integration with ImageKit.io
description: Seamlessly integrate ImageKit's powerful media management with your Contentful workflows.
---

{% video loop=true controls=false autoplay=true playsinline=true muted=true src="https://ik.imagekit.io/ikmedia/docs_images/integration/contentful/hero_video_demo.mov/ik-video.mp4?tr=ac-none,so-2" alt="ImageKit app for Contentful" /%}

Contentful is a leading headless CMS that enables teams to create, manage, and deliver content across multiple platforms. The ImageKit app for Contentful provides powerful image and video optimizations, transformations, and digital asset management directly within your Contentful CMS. It additionally provides ImageKit’s real-time AI-powered transformations, optimized delivery and streaming capabilities for all media assets, so that your users enjoy flawless visuals everywhere.

This guide walks you through installing and configuring the ImageKit app to your Contentful Space.

## App Features

- **Access ImageKit assets**: Access and insert the assets stored in ImageKit Media Library directly into your Contentful entries without leaving your CMS.
- **Speed up creative workflows**: Quickly find the right assets from your ImageKit Media Library using advanced search filters and AI-powered visual search within the Contentful CMS.
- **Rich Metadata & Previews**: Instantly view asset details including dimensions, file size, and previews within your Contentful entries before publishing.
- **Automatic media optimizations**: Deliver images and videos in the correct format and the smallest size every time with ImageKit's automatic format and quality optimizations for images and videos.
- **Real-time image and video transformations**: Apply more than 50 image and video transformations while delivering media assets for perfect visuals on every device.

## Installation

{% callout style="info" %}
Before installing, ensure you have **administrative access** to a Contentful space where you want this app to be installed. It is also recommended to have atleast one content type where you want to use the media field.
{% /callout %}


The easiest and recommended way to install this app is from the Contentful [official marketplace](https://www.contentful.com/marketplace/imagekit/). In your Contentful space, navigate to **Apps** → **Marketplace** and search for "ImageKit". Click **Install** and follow the setup wizard to configure the ImageKit app with your space.

## Configuration

You can choose to configure the app during the installation or come back to it later from **Apps** → **Installed apps** → **ImageKit** → **Configure**.

### Basic Setup

After installation, configure the app through Contentful's interface:

1. **Navigate to App Configuration**: Go to **Apps** → **Installed apps**. Find "ImageKit" and click **Configure**.

2. **Select the fields to use with ImageKit app**: In the Field Selector, choose which fields should use ImageKit. This app works only with the **JSON Object** field type provided by Contentful, so you can select one or more of your existing JSON Object fields across the different entries in your space.

![](https://ik.imagekit.io/ikmedia/docs_images/integration/contentful/field_selector_config.png?v=1)

### Advanced Configuration

{% callout style="warning" %}
Any configuration changes will only be applied to the assets you select afterwards. All previously selected assets will continue to be served with the older configuration, unless you remove and re-insert them from the ImageKit Media Library after the configuration update.
{% /callout %}

The app provides extensive configuration options to customize behavior according to your needs:

#### Media Delivery Settings

Configure how selected media assets are delivered to your applications:

{% table %}

- Setting {% width="50%" %}
- Description {% width="50%" %}

---

- Default Transformation String
- Transformation string applied to all selected assets for consistent delivery

  Default - None

  Example - `w-400,h-300,c-maintain_ratio`

---

- Media Quality
- Quality level for image delivery
  
  Default - Uses ImageKit Defaults
  
  Example - `80`, `70`

{% /table %}

#### Widget Settings

Control the media library widget's initial state and behavior:

{% table %}

- Setting {% width="50%" %}
- Description {% width="50%" %}

---

- Starting Folder Path
- Default folder path when the widget opens
  
  Default - `/`

  Example - `/marketing/banners/`

---

- Starting Collection ID
- The ID of the specific collection to open when the Media Library Widget is opened. Leave this blank if you do not want to open any collection, use `all` to open a list of all collections
  
  Default - None
  
  Example - `<collection_id>`, `all`

---

- File Type
- Restrict display to specific file types. Leave this blank to show all types of files which is the default behavior.
  
  Default - None
  
  Example - `images`, `videos`, `cssJs`, `others`

---

- Default Search Query
- The search query to be used when the Media Library Widget is opened. Leave this blank to open the widget with no search query which is the default behavior.
  
  Default - None
  
  Example - `name = "red-dress-summer.jpg"`

---

- Allow Multiple Selections
- Allow selecting multiple assets in a single operation
  
  Default - `true`
  
  Example - `false`

---

- Maximum Number of Files Per Selection
- Maximum number of assets that can be selected. Leave this blank to allow unlimited selections which is the default behavior.
  
  Default - Unlimited
  
  Example - `5`

{% /table %}

## Usage

To use ImageKit in your entries, you would first need to configure your content types with media fields that use the ImageKit app. Once done, these media fields will be enriched by bringing your ImageKit's Media Library within Contentful to provide the best possible authoring experience.

### Adding ImageKit Fields to Content Types

| Add field to Content Type | Select JSON Object type | Use ImageKit app |
|----------|----------|----------|
| ![](https://ik.imagekit.io/ikmedia/docs_images/integration/contentful/add_content_type_field.png)  | ![](https://ik.imagekit.io/ikmedia/docs_images/integration/contentful/select_json_object_type.png)  | ![](https://ik.imagekit.io/ikmedia/docs_images/integration/contentful/select_imagekit_app.png)  |


1. **Open Content Type**: Navigate to **Content model** → Select your content type. Then click on **Add field**.

2. **Select Field Type**: Choose **JSON Object** as the field type and set a descriptive field name (e.g., "Hero Image", "Gallery Images", "Product Media"). You can configure validation rules as needed.

3. **Configure Field**: In the **Appearance** tab, select the "ImageKit" app from the widget options. The field will now use the ImageKit media library widget for asset selection.

### Selecting Assets

| Select Assets | Click Insert | Assets added to entry |
|----------|----------|----------|
| ![](https://ik.imagekit.io/ikmedia/docs_images/integration/contentful/select_or_upload_an_asset.png)  | ![](https://ik.imagekit.io/ikmedia/docs_images/integration/contentful/click_insert.png?tr=w-2880,h-1556,cm-pad_resize,bg-494F56)  | ![](https://ik.imagekit.io/ikmedia/docs_images/integration/contentful/final_result.png)  |

1. **Open Entry Editor**: Navigate to **Content** → Select an entry and find your ImageKit field.

2. **Select Assets**: Click **"Select or upload an asset"** to open the ImageKit widget and browse your ImageKit Media Library using the integrated interface. You can use the search, filters, and folder navigation to find desired assets. Select one or more assets and click **Insert** to add them to your entry.

3. **Manage Selected Assets**: The ImageKit app provides a few options for you to manage the selected assets within your entry. You can drag and move the assets around to reorder them as needed, view detailed information about the asset, preview it in a new tab, remove an unwanted asset or view the asset in ImageKit Dashboard.

### Working with Asset Data directly

{% callout style="info" %}
In case you'd like to manually override the transformation parameters applied to a particular asset, you can do so by setting the Field Appearance to "Default" and editing the JSON directly.
{% /callout %}

The selected assets are stored as an array of JSON objects containing all necessary information. To understand the fields available and the object structure, take a look at [Get file details](../api-reference/digital-asset-management-dam/managing-assets/get-file-details).

Here's an example:

```js
[
    {
        "type": "file",
        "name": "sample ....jpg",
        "fileId": "681c2748432c476416f3e190",
        "isPublished": true,
        "url": "https://ik.imagekit.io/imagekitId/sample.jpg",
        "thumbnail": "https://ik.imagekit.io/imagekitId/sample.jpg&tr=n-ik_ml_thumbnail",
        "fileType": "image",
        "filePath": "/sample ....jpg",
        "height": 3712,
        "width": 5568,
        "size": 7324983,
        // ... other fields
    }
]
```


---

# Source: /integration/sanity

---
title: Sanity Integration with ImageKit.io
description: Seamlessly integrate ImageKit's powerful media management and optimization capabilities with your Sanity Studio workflows.
---

Sanity is a platform for structured content that powers remarkable digital experiences at scale. The ImageKit plugin for Sanity enables you to browse, manage, and deliver optimized media directly from your Sanity Studio, leveraging ImageKit's complete media storage, optimization, and transformation solution along with an image and video CDN.

This guide walks you through installing and configuring the ImageKit plugin in your Sanity Studio to enhance your workflows with powerful media management capabilities. You can view the [source code](https://github.com/imagekit-developer/sanity-plugin-imagekit) on GitHub.

## Plugin Features

- **Media Library Integration**: Browse and manage your ImageKit media library directly in Sanity Studio without leaving your content editor.
- **Asset Source Integration**: Integrates seamlessly with Sanity's image fields for a native editing experience.
- **Custom Schema Support**: Provides `imagekit.asset` schema type for storing comprehensive asset metadata.
- **Rich Asset Data**: Access complete asset metadata including dimensions, file size, custom metadata, and more.
- **Video Support**: Browse and select both images and video content from your ImageKit media library.
- **Asset Preview**: View thumbnails and detailed asset information before selection.
- **No Configuration Required**: Works out of the box without additional configuration.

## Installation

{% callout style="info" %}
Before installing, ensure you have a Sanity Studio project (**v3 or later**) and a local instance of the same running. You can refer to Sanity's [official documentation](https://www.sanity.io/docs) to understand the prerequisites for setting up your Sanity Studio instance.
{% /callout %}

To install the ImageKit plugin in your Sanity Studio instance, run one of the following commands from your project's root directory:

**Using npm:**
```bash
npm install sanity-plugin-imagekit
```

**Using yarn:**
```bash
yarn add sanity-plugin-imagekit
```

**Using pnpm:**
```bash
pnpm install sanity-plugin-imagekit
```

## Usage

The package exports two plugins that serve different use cases:

- **`imagekitAssetSourcePlugin`** - Use this when you want ImageKit to appear as an asset source for standard image fields in your Sanity Studio.
- **`imagekitSchemaPlugin`** - Use this if you intend to define a custom schema type that stores comprehensive asset metadata from ImageKit, allowing you to access detailed information about each asset in your content.

### ImageKit as an Asset Source

To use ImageKit as an asset source, import the plugin in your `sanity.config.ts` file:

```javascript
// sanity.config.ts
import { defineConfig } from 'sanity'
import { imagekitAssetSourcePlugin } from 'sanity-plugin-imagekit'

export default defineConfig({
  projectId: 'your-project-id',
  dataset: 'production',
  // ... other configuration
  plugins: [
    imagekitAssetSourcePlugin(),
  ],
})
```

Once configured, ImageKit will automatically appear as an asset source option in the dropdown when you add or select images in your Sanity Studio. For most use cases, you can simply use the standard Sanity image field:

```javascript
{
  type: "image",
  name: "heroImage",
  title: "Hero Image",
  // ImageKit will appear as an option in the asset source dropdown
}
```

![ImageKit asset source in Sanity](https://ik.imagekit.io/ikmedia/docs_images/integration/sanity/imagekit-asset-source-plugin.png?tr=w-1600)

### ImageKit as a Custom Schema Type

For more control, you can use the custom `imagekit.asset` schema type.

![ImageKit custom schema type](https://ik.imagekit.io/ikmedia/docs_images/integration/sanity/imagekit-schema-type-plugin.png?tr=w-1600)

To do this, first import the `imagekitSchemaPlugin` in your `sanity.config.ts`:

```javascript
import { imagekitSchemaPlugin } from 'sanity-plugin-imagekit'

// Add to plugins array
export default defineConfig({
  // ... other configuration
  plugins: [
    imagekitSchemaPlugin(),
  ],
})
```

Then use it in your schema definitions:

```javascript
{
  type: "imagekit.asset",
  name: "imagekitImage",
  title: "ImageKit Image",
  description: "Select an image from your ImageKit media library"
}
```

This custom type stores comprehensive asset metadata from ImageKit, allowing you to access detailed information about each asset in your content.

## Asset Data Structure

When you select an asset from ImageKit, it's stored with comprehensive metadata. Here's what the asset object looks like:

```javascript
{
  "_type": "imagekit.asset",
  "fileId": "unique_file_id",
  "name": "image_name.jpg",
  "url": "https://ik.imagekit.io/your_account/image.jpg",
  "width": 1920,
  "height": 1080,
  "fileType": "image",
  "size": 245760,
  "createdAt": "2024-01-01T00:00:00Z",
  "mime": "image/jpeg",
  // ... other fields
}
```

{% callout style="warning" %}
**Note:** Sanity Studio expects object keys to match the regex `/^\$?[a-zA-Z0-9_-]+$/`. Since ImageKit's Custom Metadata allows characters outside this set, the plugin automatically sanitizes keys by replacing non-supported characters with underscores (`_`).
{% /callout %}

## Working with Asset Data

### Using Asset URLs

The stored `url` field provides a direct link to your asset on the ImageKit CDN. You can use this URL directly in your frontend or even [apply ImageKit's real-time transformations](#asset-transformation):

```javascript
// Direct URL
const directUrl = asset.url;

// With transformation (example: resize to 300px width)
const transformedUrl = `${asset.url}?tr=w-300`;
```

### Querying Assets in Your Frontend

When querying your Sanity documents, the asset data is readily available:

```javascript
// Example GROQ query
const query = `*[_type == "article"][0] {
  heroImage {
    url,
    width,
    height
  }
}`;

// Result
{
  "heroImage": {
    "url": "https://ik.imagekit.io/your_account/image.jpg",
    "width": 1920,
    "height": 1080
  }
}
```

### Custom Metadata

ImageKit's custom metadata feature allows you to store additional information with your assets. This data is accessible through the plugin:

```javascript
{
  "customMetadata": {
    "alt": "Hero image for homepage",
    "photographer": "John Doe",
    "license": "CC0"
  }
}
```

All custom metadata fields are automatically included in the asset object and can be queried alongside standard asset properties.

## Advanced Topics

### Asset Transformation

ImageKit provides 50+ image and video transformations that can be applied in real-time via URL parameters on the asset url. Some common transformations include:

```javascript
// Resize and crop
const resizedUrl = `${asset.url}?tr=w-400,h-300,cm-pad_resize`;

// Format conversion and quality
const optimizedUrl = `${asset.url}?tr=f-webp,q-80`;

// Multiple transformations
const transformedUrl = `${asset.url}?tr=w-400,h-300,c-maintain_ratio:e-grayscale`;
```

Learn more about available transformations [here](/docs/transformations).

### Using Both Plugins Together

You can use both plugins in the same Sanity Studio project. This allows you to use ImageKit as an asset source for standard image fields while also having access to the custom schema type for fields that require comprehensive metadata:

```javascript
// sanity.config.ts
import { defineConfig } from 'sanity'
import { imagekitAssetSourcePlugin, imagekitSchemaPlugin } from 'sanity-plugin-imagekit'

export default defineConfig({
  projectId: 'your-project-id',
  dataset: 'production',
  plugins: [
    imagekitAssetSourcePlugin(),
    imagekitSchemaPlugin(),
  ],
})
```

This gives you the flexibility to choose the appropriate approach for each field in your content model.


---

# Source: /production-checklist

---
title: Production Checklist
description: Checklist to review before going live on production with ImageKit for delivering images and videos.
---

Before you go live on production, review this checklist. It is based on the best practices and techniques our customers use to get the most out of ImageKit.

A few of them are related to your ImageKit account settings, while others are related to how you integrate ImageKit with your website or app.

## Enable 2FA for your account

To secure your account, enable [two-factor authentication (2FA)](/user-management) for your ImageKit account. This adds an extra layer of security by requiring a second form of verification in addition to your password.

## Review optimization settings

By default, your ImageKit account is configured to deliver optimized images and videos while maintaining visual quality. However, you can customize these settings for [images](https://imagekit.io/dashboard/settings/images) and [videos](https://imagekit.io/dashboard/settings/videos) separately based on your requirements.

* Ensure format optimization is turned on. This feature automatically converts images and videos to next-gen formats like WebP or AVIF for images and VP9 or AV1 for videos to reduce file size and improve performance.
* Review compression settings. By default, images & videos are compressed to a level that maintains visual quality while reducing file size.

{% callout style="warning" %}
Do not set the image quality to over 90 or the video quality to over 70 in ImageKit's dashboard. It will increase the file size without any visual improvement. Instead, you should always start with a high-quality master image or video and leverage ImageKit's optimization and transformation capabilities during delivery.

For example, the largest resolution needed for desktop usage for images is typically around 1920px wide and under 5MB. Starting with high-resolution assets and letting ImageKit take care of the compression, helps you tweak compression settings in a single step without losing the original image quality because of multiple layers of compression. 
{% /callout %}

{% callout style="info" %}
Loading the right image and video resolution on different screens and placeholders is also essential for excellent visual quality, especially on retina or high-density displays. 
{% /callout %}

## Fix media performance issues

For publicly accessible pages, use the [ImageKit website performance analyzer](https://imagekit.io/website-analyzer/). For pages on your local machine, you can use [Lighthouse in Chrome DevTools](https://developer.chrome.com/docs/lighthouse/overview).

If you identify any media-related issues, ensure the following:

* All images and videos are loaded via ImageKit, with the compression settings configured as recommended above.
* To address "Properly size images" issues, use ImageKit's [URL-based transformation parameters](/transformations) to set height, width, aspect ratio, DPR, and crop modes to match your media requirements. Also, review our [responsive images guide](https://imagekit.io/responsive-images/).
* For "Defer off-screen images" issues, implement [lazy loading](https://imagekit.io/blog/lazy-loading-images-complete-guide/).
* For "Efficiently encode images" and "Serve images in next-gen formats," ensure format and compression settings are correctly configured as outlined above.
* For "Serve videos in modern formats," verify that video format and compression settings are properly configured as detailed above.
* To fix "Use video formats for animated content," convert animated [GIFs to videos](/docs/vector-and-animated-images#gif-to-video) using ImageKit.

## Set up performance monitoring and alerts

With paid plans, ImageKit can monitor specific pages on your website and provide weekly reports on image and video performance. You can configure these [performance monitoring alerts](https://imagekit.io/dashboard/performance-alerts) in the ImageKit dashboard. Learn more about the [performance center](/performance-center).


## Mobile app-specific optimizations

### Loading the right format
ImageKit uses the standard [content negotiation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation) approach to identify the image formats supported by a device or browser. This content negotiation technique depends on the request's `Accept` header value. We use `User-Agent` headers to determine the supported formats for videos. However, mobile apps do not always send these headers or the actual value for the headers can get overridden by libraries such as OkHttp. 

To load the right format on mobile, you can do the following: 
- You can force the output format using URL transformation parameters.
- On the enterprise plan, you can specify a list of user agents for which ImageKit should serve images in next-gen formats.

### Network-based optimization
You should load a lower-resolution image on mobile apps on slower network speeds. [Network Connection Class](https://github.com/facebookarchive/network-connection-class) is a library developed by Meta that helps identify connection quality by listening to network traffic and categorizing it. Check out how Swiggy adapts image delivery based on network conditions [here](https://bytes.swiggy.com/media-on-swiggys-mobile-apps-e97452fceb3f).

###  Combining DPR with resizing on mobile apps
Different image placeholders on your app will need images in different sizes. Mobile phones additionally have high-density or retina displays, so you need to load an image larger in dimensions on such displays. You would have seen this with @1x, @2x, xhdpi, xxhdpi, etc., on apps where you provide the same image in different dimensions.

Similarly, when loading images with ImageKit, you must add the appropriate DPR value and the resize parameters. This can be done using the dpr transformation parameter.

For example, if you need a 300px wide image, you can use the following URLs with varying dpr transform values on each display density.

1x - https://ik.imagekit.io/demo/default-image.jpg?tr=w-300,dpr-1 
2x - https://ik.imagekit.io/demo/default-image.jpg?tr=w-300,dpr-2

{% callout style="info" %}
Capping the DPR value to 2 can provide sufficiently high visual quality, even on higher display densities. This means using `dpr-2` on a 3x device might still work. Do give it a try.

When loading high-resolution images on high-density displays, you might be able to compress them more and still retain the same visual quality. For example, you can compress the 2x image to quality 60 and still get the same output visual quality. You can do this with the quality transformation parameter q.
{% /callout %}

## Adaptive Bitrate Streaming for videos
If your website or app loads videos over 30 seconds in length, it is recommended that you use [Adaptive Bitrate Streaming](/adaptive-bitrate-streaming) to adjust the video stream quality to the user’s network bandwidth. This is similar to the experience you get on YouTube, where, under poorer network conditions, you see a low-quality video that automatically improves as your network speed improves.

## Set maximum image dimension limits
We often miss out on using suitable transformation parameters in our image URLs. In such cases, if the original image is high-resolution, it will be delivered at that same resolution and consume a lot of bandwidth.

To avoid this, enable the "Device-based" > "Restrict image size based on user's device" setting in the ImageKit dashboard [here](https://imagekit.io/dashboard/settings/images). Specify the maximum resolution your layout needs on desktop and mobile devices if you don't specify anything in the URL. 2000x2000px is a good safe limit for desktop devices, and 1000x1000 is a good safe limit to set on mobile. ImageKit will use this as a size limit for your images only when the URL does not contain any height or width resizing parameters.

## Consider using Named transformations
Consider using [named transformations](/transformations#named-transformations) to simplify your URL structure and facilitate transformation management across your application. It can also help secure your URLs [as mentioned here](/media-delivery-basic-security#restrict-unnamed-transformations).

## Set up the custom domain name

On paid plans, you can deliver files from your domain name, such as `https://media.yourdomain.com/image.jpg`.

Learn more about custom domain name setup [here](/docs/core-delivery-features#using-custom-domain-name).

## Billing Alerts and monitor analytics
On paid plans, ImageKit offers certain inclusions in the base plan, with usage-based pricing after that. As your usage increases, so does your billing. 

To monitor your billing in case of high usage, you can [set a billing alert](/billing-and-subscription#billing-alerts). It is also advisable to [track your usage analytics](/usage-analytics) from the dashboard or [use the API](/api-reference/account-management-api/get-usage) to set alerts on your usage.

## Useful resources

Explore helpful tutorials and comprehensive guides.

{% quickstartLinksGrid %}

{% griditem %}
{% linkButton href="https://imagekit.io/guides/image-optimization/"  newtab=true text="Image optimization" /%}
{% /griditem %}

{% griditem %}
{% linkButton href="https://imagekit.io/responsive-images/" newtab=true text="Responsive images" /%}
{% /griditem %}

{% griditem %}
{% linkButton href="https://imagekit.io/blog/lazy-loading-images-complete-guide/" newtab=true text="Lazy loading" /%}
{% /griditem %}

{% griditem %}
{% linkButton href="https://imagekit.io/blog/" newtab=true text="Blogs" /%}
{% /griditem %}

{% /quickstartLinksGrid %}


---

# Source: /build-with-ai

---
title: Build with AI
description: Connect AI coding agents and assistants to ImageKit with skills, plugins, and MCP servers to manage media and build transformations using natural language.
---

{% callout style="warning" %}
**Public preview** \
ImageKit's MCP servers and agent skills are in public preview (beta). The underlying ImageKit APIs are stable and production-ready, but these AI tools are evolving and the interface may change. Test thoroughly and follow the [security recommendations](#security-recommendations).
{% /callout %}

Large language models were trained before the latest version of ImageKit, so on their own they often suggest outdated API signatures, invent transformation parameters, or pick the wrong approach. The tools on this page fix that. They give your AI assistant accurate, up-to-date knowledge of ImageKit and the ability to act on your account.

There are three ways to use AI with ImageKit:

{% table %}
* What you want to do
* Use this
* Best for
---
* Let an AI assistant work in your account, so it can upload, search, tag, organize, and purge media from natural language
* [MCP servers](#mcp-servers)
* Ops automation, content teams, and agentic workflows
---
* Help your AI assistant integrate ImageKit and build transformations correctly as you code
* [Agent skills](#install)
* Developers integrating ImageKit in an IDE such as Cursor, VS Code, Windsurf, Claude Code, or Codex
---
* Give any AI assistant the full ImageKit documentation in a single, plain-text file
* [Plain text docs](#plain-text-docs)
* Helping any AI assistant answer from the latest ImageKit docs, including ChatGPT and Claude
{% /table %}

If you are building in an IDE, the quickest way to get everything is to install the ImageKit skills. It adds the skills and connects both MCP servers in one step.

## Install

[ImageKit skills](https://github.com/imagekit-developer/skills) are a set of instructions that teach your AI coding agent how to use ImageKit correctly. Each skill gives the agent a verified playbook for a task, such as searching the docs, building a transformation, or uploading a file, and routes it to the right tool. The result is working code instead of plausible-looking guesses.

Every IDE installs the skills with the same command, `npx skills add imagekit-developer/skills --all`, which also connects both MCP servers. VS Code and Claude Code additionally offer a guided plugin or marketplace flow. Expand your tool below.

{% accordion %}

{% accordionitem title="VS Code Copilot" %}
**Plugin (guided)**

1. Open the Command Palette (`⇧⌘P`) and run **Install Plugin from Source**.
2. Enter `imagekit-developer/skills` in the plugin source field.
3. Continue through the installation prompts.
4. Restart VS Code so the skills and MCP servers take effect.

**Manual**

```bash
npx skills add imagekit-developer/skills --all
code --add-mcp "{\"name\":\"imagekit_public_mcp\",\"type\":\"http\",\"url\":\"https://devtools-mcp.imagekit.io/mcp\"}"
code --add-mcp "{\"name\":\"imagekit_api\",\"type\":\"http\",\"url\":\"https://api-mcp.imagekit.in/mcp\"}"
```
{% /accordionitem %}

{% accordionitem title="Claude Code" %}
**Plugin (guided)**

In Claude Code, open **Customize → Add Marketplace**, enter `imagekit-developer/skills`, then install the plugin and its connectors.

**Manual**

```bash
npx skills add imagekit-developer/skills --all
claude mcp add --transport http imagekit_public_mcp https://devtools-mcp.imagekit.io/mcp
claude mcp add --transport http imagekit_api https://api-mcp.imagekit.in/mcp
```

Restart Claude Code for the MCP servers to take effect.
{% /accordionitem %}

{% accordionitem title="Cursor" %}
```bash
npx skills add imagekit-developer/skills --all
```

Add the MCP servers from the [skills repository](https://github.com/imagekit-developer/skills)'s install buttons, or edit `~/.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "imagekit_public_mcp": { "url": "https://devtools-mcp.imagekit.io/mcp" },
    "imagekit_api": { "url": "https://api-mcp.imagekit.in/mcp" }
  }
}
```

Restart Cursor for the changes to take effect.
{% /accordionitem %}

{% accordionitem title="Windsurf" %}
```bash
npx skills add imagekit-developer/skills --all
```

Then edit `~/.codeium/windsurf/mcp_config.json`:
```json
{
  "mcpServers": {
    "imagekit_public_mcp": { "url": "https://devtools-mcp.imagekit.io/mcp" },
    "imagekit_api": { "url": "https://api-mcp.imagekit.in/mcp" }
  }
}
```

Restart Windsurf for the changes to take effect.
{% /accordionitem %}

{% accordionitem title="Codex" %}
```bash
npx skills add imagekit-developer/skills --all
```

Then edit `~/.codex/config.toml`:
```toml
[mcp_servers.imagekit_public_mcp]
url = "https://devtools-mcp.imagekit.io/mcp"

[mcp_servers.imagekit_api]
url = "https://api-mcp.imagekit.in/mcp"
```

Restart Codex for the MCP servers to take effect.
{% /accordionitem %}

{% /accordion %}

### What you get

{% table %}
* Skill
* What it does
---
* **mcp-preflight**
* Routing guide the agent reads before any ImageKit call, so it picks the correct MCP server and tool every time.
---
* **search-docs**
* Teaches the agent to search official ImageKit docs, API references, SDKs, and community posts before writing code, instead of relying on stale training data.
---
* **transformation-builder**
* Turns natural-language requests ("resize to 800x600 and crop to the face") into correct transformation URLs, including AI edits, background removal, generative fill, upscaling, and overlays.
---
* **upload-files**
* Uploads local images and videos to your media library with folders, tags, and metadata using a reliable script.
---
* **ai-tasks**
* Applies AI-powered tagging, metadata extraction, and quality checks to images using controlled vocabularies.
{% /table %}

## MCP servers

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard that lets AI assistants securely connect to external tools and data. ImageKit provides two hosted, remote MCP servers, so there is no local server to run or maintain. Both are connected for you when you [install the skills](#install) above, and you can also add them to any MCP client manually.

### API MCP

The API MCP server lets an AI assistant manage your ImageKit media library on your behalf. It can upload and organize files and folders, edit tags and metadata, manage versions, purge cache, and configure your account. It covers all of ImageKit's public APIs, so anything you can do with the [API](/api-reference), the agent can do too.

Connect to it at `https://api-mcp.imagekit.in/mcp`. On first connect, you provide your private API key through ImageKit's OAuth flow. The key is exchanged for a scoped access token and is never shared with the AI assistant or any third party. See [security recommendations](#security-recommendations) for how this works and how to scope access.

### DevTools MCP

The DevTools MCP server makes any AI assistant better at ImageKit, even before you connect your account. It is public and needs no authentication, so you can connect to it at `https://devtools-mcp.imagekit.io/mcp`. It exposes two tools:

- `search_docs` answers "how do I…" questions from official ImageKit docs, API references, SDK examples, and community posts, so the assistant works from real documentation instead of stale training data.
- `transformation_builder` turns natural-language requests into correct transformation URLs, including AI transformations, background removal, generative fill, upscaling, smart cropping, and overlays.

{% callout style="info" %}
Uploading local files is best done through the `upload-files` skill rather than the MCP upload tool, because the skill reliably sends file bytes. Installing the [skills](#install) sets this up for you.
{% /callout %}

## Security recommendations

The API MCP server is hosted and maintained by ImageKit on secure infrastructure, and it uses OAuth so your credentials are never exposed to the AI assistant or any third party. Only the official ImageKit MCP server can use your key, and only to make the API calls you authorize.

The server's permissions are bound to the API key you connect with, not to your ImageKit user account. The agent can only do what that key is allowed to do, so use a restricted key to limit which operations the assistant can perform.

### How authentication works

1. **Initial connection.** On first connect, you're redirected to ImageKit's secure OAuth consent screen. The URL starts with `https://api-mcp.imagekit.in`.
2. **Credential collection.** You provide your private API key through an encrypted form hosted on ImageKit's infrastructure.
3. **Token exchange.** ImageKit exchanges your key for an OAuth access token scoped to your MCP client.
4. **Encrypted storage.** Your key is encrypted and stored securely on ImageKit's servers.
5. **Scoped access.** The OAuth token authenticates subsequent requests, and your key is only used by ImageKit's servers on your behalf.
6. **Isolation.** Each client gets its own token, with no cross-client access.

### Best practices

1. **Use restricted API keys.** Create dedicated keys with the minimum permissions needed.
2. **Rotate keys regularly.** Change them periodically, and immediately if compromised.
3. **Review actions.** Keep a human in the loop for destructive operations such as bulk delete or cache purge.

## Plain text docs

You can read any ImageKit documentation page as plain-text Markdown by adding `.md` to its URL. For example, the plain-text version of this page is at [https://imagekit.io/docs/build-with-ai.md](https://imagekit.io/docs/build-with-ai.md). You can also use the **Copy page** option at the top of any page.

This helps AI tools consume our content, and it lets you paste a whole doc into an LLM. Plain text is better than scraped HTML because it contains fewer formatting tokens, includes content hidden in the default view (such as text inside a tab or accordion), and preserves a Markdown hierarchy that LLMs can parse.

We also host an [`/llms.txt`](https://imagekit.io/docs/llms.txt) file, an [emerging standard](https://llmstxt.org/) that indexes every page and links to its plain-text version. For everything in one request, [`/llms-full.txt`](https://imagekit.io/docs/llms-full.txt) concatenates the entire documentation into a single file. Point any AI agent at these so it answers from the latest ImageKit documentation instead of stale training data.

## Troubleshooting

If an MCP client fails to connect:

- Ensure you have Node.js 18 or higher installed.
- Clear the MCP auth cache: `rm -rf ~/.mcp-auth`.
- Restart your MCP client application.
- Check the client logs for error messages.

For more help, see the [ImageKit skills repository](https://github.com/imagekit-developer/skills) or contact [ImageKit support](https://imagekit.io/contact-us).


---

# Source: /integration/connect-external-storage

---
title: Connect external storage
description: ImageKit.io supports connecting external storage like Amazon S3, Azure Blob Storage, Google Cloud Storage, Web Servers, and more.
---

This method is suitable if you already use file storage like Amazon S3, Azure Blob Storage, Google Cloud Storage, Web Servers, etc., and want to use ImageKit.io for real-time optimization and URL-based transformation capabilities for your image and video files or the delivery of any other file.

## How does it work?

You can connect your external storage with ImageKit.io. ImageKit.io acts as a proxy between the CDN and your storage. This means that when a request is made to ImageKit.io for any file, ImageKit.io fetches the file from your storage, processes it in real-time, and serves the optimized media file to the user over the CDN. Let's dive deeper into how this process works.

On a high level, this is how the request flow looks like:

![Incoming request flow with external storage integration](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/how-it-works.png)

{% callout type="info" %}
Your media files remain securely stored in your storage system. ImageKit.io accesses these files in real-time upon receiving user requests. However, if you encounter slow response times from your origin server, you can see how to debug the same, as explained [here](#debugging-slow-origin-response).
{% /callout %}

## Supported external storage

ImageKit works with a variety of external storage types. You can connect any of the following types of external storage with ImageKit.io:

* **Object storage** - ImageKit.io supports all popular S3-compatible storages like [Amazon S3](/integration/aws-s3), [Wasabi](/integration/wasabi), [Alibaba OSS](/integration/alibaba-cloud-object-storage-service), [Digital Ocean Spaces](/integration/digitalocean-spaces), [Azure Blob Storage](/integration/azure-blob-storage), and [Google Cloud Storage](/integration/google-cloud-storage), etc. See generic instructions for [S3-compatible storages](/integration/s3-compatible-storage).
* **Web-server** - You can also connect any [web server](/integration/web-server) like Nginx, ELB, ALB, EC2, Magento, WordPress, etc., to ImageKit.io. [Firebase Storage](/integration/firebase-storage) also falls under this category.
* **Web proxy** - ImageKit.io can access files from any web URL using the [web proxy](/integration/web-proxy) external storage type.
* **Akeneo PIM** - If you are using Akeneo PIM, you can connect it with ImageKit.io using the [Akeneo PIM](/integration/akeneo-pim) integration to fetch product media, asset media, and reference entity media files.
* **Cloudinary backup bucket**—If you are migrating from Cloudinary, you can connect your Cloudinary backup bucket with ImageKit.io using the [Cloudinary backup bucket](/integration/cloudinary-backup-bucket) integration. Check out the [Cloudinary migration guide](/migration/cloudinary-to-imagekit) for more information related to no-code change migration.

## URL Endpoints

URL endpoints are unique access points that allow you to retrieve your media files through ImageKit.io. When you create an account, a default URL endpoint is automatically generated:

Default URL endpoint: `https://ik.imagekit.io/your_imagekit_id`

### Creating a new URL endpoint

You can create multiple URL endpoints to segregate media files based on categories like product images, user profile images, etc. To create a new URL endpoint:

1. Go to the [URL Endpoints section](https://imagekit.io/dashboard/url-endpoints) in your ImageKit.io dashboard and click on the "Add new" button.
2. Fill in the `Identifier` field. It will become part of the URL endpoint. Suppose you want to create a URL endpoint just to access the product images bucket, and you want it to be like this:

   `https://ik.imagekit.io/your_imagekit_id/product-images/`
   
 Then enter `product-images` in this field.
3. Attach the external storage (origin) to this URL endpoint. You can attach multiple origins to a single URL endpoint.

![Create a new URL Endpoint](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/add-url-endpoint.png>)

### Origin preference

When you attach multiple origins to a single URL endpoint, you can set the order in which ImageKit.io will attempt to fetch the resource from these origins.

![Manage origin preference](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/image-origin-preference.png?tr=w-1600)

{% callout type="info" title="Important information" %}
1. ImageKit always tries to fetch the file from the integrated Media Library first. If the file is not found, it tries to fetch it from the attached external storage (origins) sequentially, one after the other till it finds the file on that path.
2. Avoid adding more than two origins to a single URL endpoint for optimal performance.
3. You have the option to [configure a custom domain name](/docs/core-delivery-features#using-custom-domain-name) and optionally associate it with only a specific URL endpoint. Contact [support@imagekit.io](mailto:support@imagekit.io) for domain and URL endpoint mapping.
{% /callout %}

### Advanced URL endpoint features

URL endpoints support advanced features for migration and custom URL handling:

- **URL Rewriters** - Predefined rewriters for [Cloudinary](/migration/cloudinary-to-imagekit), [Imgix](/migration/imgix-to-imagekit), and [Akamai](/migration/akamai-to-imagekit) that allow you to keep existing URL formats during migration.
- **URL Endpoint Functions** - Write [custom JavaScript functions](/url-endpoint-functions) to implement custom URL transformation logic for complex migration scenarios where standard rewriters don't fit. Functions run first, then rewriters (if configured), so they can be used together.

## Troubleshooting 404 errors

When ImageKit encounters an error while fetching the original image from your external origin, it responds with a 404 status code and a generic "Not Found" message. You can check the `ik-error` header in the response to debug the issue.

![ik-error has a value composed of an error code and an error message](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/image (14).png?tr=w-1600>)

| Error Code   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ENOENT       | It means the file does not exist at the given path on the origin server or object storage. Check the origin server associated with the URL endpoint and ensure that the file exists.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| EACCES       | Invalid or expired authentication credentials for the corresponding origin. In this case, you should check the credentials provided in the ImageKit dashboard while configuring the origin and ensure that ImageKit.io has the necessary permission to access the file. In the case of [web server origin](/integration/web-server), you should check firewall settings and [whitelist our servers](#whitelist-requests-from-imagekit.io). In the case of object storage, you should ensure that the configured credential has read access. |
| ELIMIT       | Refer to [transformation limits](/transformations) to understand more about the reason for the error. The response status is `400` in this case.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ECONNREFUSED | The external origin refused to connect. This usually happens if your origin web server has some maximum connection limit or a firewall has blocked our request. You should check firewall settings and [whitelist our servers](#whitelist-requests-from-imagekit.io).                                                                                                                                                                                                                                                                                               |
| UNIDENTIFIED | The exact nature of the error could not be identified. This is rare, in this case, contact us at support@imagekit.io.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |

## Whitelist requests from ImageKit.io

Suppose your origin server uses any Web Application Firewall (WAF) or any other setting that could prevent ImageKit's servers from accessing your origin. In that case, we recommend that you allow our requests to your origin based on the request header value. All our requests to your origin will have a header `x-req-from` with its value set to `imagekit`.

If header-based rules cannot be added, you should allow requests from the following IP addresses.

{% callout style="info" %}
Note that these IP addresses may change in the future. Any changes will be reflected and updated in this document.
{% /callout %}

```
3.0.152.204
3.105.141.56
3.105.153.182
3.105.56.110
3.106.43.145
3.120.113.108
3.124.164.235
3.125.145.160
3.125.232.112
3.126.54.34
3.228.64.190
3.25.15.199
3.6.106.236
3.6.117.197
3.6.117.226
3.6.125.142
3.6.139.207
3.6.31.234
3.6.77.26
13.211.250.60
13.234.210.223
13.235.117.100
13.239.68.153
13.239.93.60
13.250.152.216
13.251.231.118
13.54.10.227
13.57.157.178
13.57.80.35
13.57.84.219
15.206.35.88
18.136.180.238
18.138.42.101
18.138.48.167
18.140.193.132
18.144.94.93
18.184.51.46
18.194.51.214
18.214.253.69
34.198.33.10
34.227.255.75
35.156.190.52
52.1.78.96
52.220.21.200
52.221.19.26
52.23.130.57
52.29.99.236
52.52.150.88
52.52.156.33
52.53.89.205
52.63.6.226
52.76.146.253
52.86.168.184
52.9.51.127
52.9.54.118
54.183.110.13
54.198.229.74
54.93.187.13
100.25.189.19
100.26.0.170
18.138.154.61
52.66.188.11
3.123.46.194
3.226.115.3
13.52.20.231
3.24.91.28
159.65.154.196
206.189.46.125
174.138.126.207
142.93.174.223
34.228.164.220
18.156.150.128
3.123.211.55
3.126.236.57
3.126.25.38
3.66.248.204
3.74.172.234
3.76.53.155
3.77.243.243
3.77.50.194
54.151.133.111
52.74.122.107
3.1.207.90
52.77.198.19
18.136.88.63
18.138.189.41
13.215.97.100
13.228.210.47
13.228.217.227
13.250.195.31
13.251.132.82
18.138.97.218
3.1.46.98
52.220.37.193
52.76.110.156
54.169.79.116
100.24.177.67
18.214.141.92
50.17.57.46
52.45.208.226
54.145.114.168
54.237.174.138
43.204.172.86
3.108.149.71
65.1.72.129
43.205.66.219
13.234.247.83
15.206.97.20
13.233.234.115
13.234.159.248
52.52.35.45
52.53.66.106
52.8.243.221
52.8.34.3
52.9.239.52
54.176.154.89
54.176.68.12
```

## Staging vs production setup

There are two ways to handle the staging vs production setup with external storage:

* **Use different external storage & URL Endpoints** - Create separate external storage for staging and production. You can then create separate URL endpoints for staging and production and associate the respective storage with them. This way, you can keep the media delivery separate for staging and production.
* **Using sub-account** - In the above setup, the Media Library and other account settings will still be shared between the two environments. If that is not desired, or if you want separate analytics for both the environments, you can use a separate [sub-account](/sub-accounts) for different environments. This setup lets you confidently iterate on configurations and share credentials with your team without affecting the production setup. Sub-accounts are available only on enterprise plans.
  
## Serving media from your local machine

If you want to access media files from your local host, you can use [ngrok](https://ngrok.com) to create a secure tunnel to your local machine. You can then use the ngrok URL as the origin URL in ImageKit.io. For example, if your local server is running on `http://localhost:3000`, you can create a tunnel using `ngrok http 3000` and use the ngrok URL like `https://xxxxxxxx.ngrok.io` as the origin URL in ImageKit.io.

## Debugging slow origin response

ImageKit returns a standard [Server-Timing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Server-Timing) header in the response that provides detailed information about the time it took to process the request. You can use these headers to identify the bottleneck in the request processing.

![Server-Timing headers in the response](https://ik.imagekit.io/ikmedia/docs_images/integration/server-timings.png?tr=w-1600)

```
Server-Timing:
transformation;dur=193,download;dur=35,cdn-rid;desc="emLLQhxPrnjER3V6q7vg3a0uB2PeL8WfjQGrDML6SCRXCn1_a5vGGw==",cdn-downstream-fbl;dur=470
```

* **download** - Time taken in milliseconds by ImageKit to download the original file from the origin.
* **transformation** - Time taken in milliseconds by ImageKit to apply transformations.

If your download time is high, then try the following steps:
- Check that your origin is working correctly and can respond to ImageKit requests quickly
- Check your [processing region](/account-management#imagekit-id-and-processing-region) and the geographical location of your origin. The longer the physical distance between the two, the longer the download time. ImageKit.io has seven processing regions: North California (United States), North Virginia (United States), Frankfurt (Europe), Mumbai (India), Singapore (Singapore), Sydney (Australia), and Montreal (Canada). To change your processing region, you can speak to our [support team](mailto:support@imagekit.io). Additional one-time charges may apply for this change based on your traffic volume.
- Try using the feature to [save a copy of the original asset](#save-a-copy-of-original-assets-on-demand) in ImageKit

## Save a copy of original assets on demand
This feature is available only on enterprise plans. When enabled, apart from the transformed file, ImageKit.io also caches the original file on its servers while processing the first request to a resource. Subsequent transformations for the same resource are generated from the copy stored in ImageKit instead of downloading the original resource again from the origin server. 

This feature not only helps reduce the processing time by significantly reducing the time it takes to access the original file but also helps reduce data transfer costs, if applicable, when ImageKit downloads the content from your origin server.


---

# Source: /migration/overview

---
title: Migrate to ImageKit
description: Easily migrate to ImageKit from Cloudinary, Imgix, Akamai, etc, without changing existing URLs.
---

If you are using another image or video optimization and delivery service like Cloudinary, Imgix, or Akamai, you can easily migrate to ImageKit without changing the URLs in your application. ImageKit provides tools and features that make the migration process seamless and easy. These capabilities have helped companies migrate in days instead of months with zero downtime.

## URL rewriters

URL rewriters are configured on [URL endpoint](https://imagekit.io/dashboard/url-endpoints) under the "Advanced settings" tab. They rewrite the incoming URL to the format that ImageKit understands. This allows you to keep the existing URLs in your application and still use ImageKit for media optimization, transformation, and delivery.

For example, if you configure Cloudinary URL rewriter to the endpoint, ImageKit will accept transformations written in Cloudinary's syntax for all URLs on this endpoint.

![URL-rewiter](https://ik.imagekit.io/ikmedia/docs_images/integration/url-endpoints/url-rewriter.png?tr=w-1600)

Refer to specific URL rewriters for more details:

* [Cloudinary URL rewriter](/migration/cloudinary-to-imagekit)
* [Imgix URL rewriter](/migration/imgix-to-imagekit)
* [Akamai Image Manager URL rewriter](/migration/akamai-to-imagekit)

## URL Endpoint Functions

For complex migration scenarios where you need custom URL transformation logic beyond what predefined URL rewriters offer, you can use [URL Endpoint Functions](/url-endpoint-functions). This feature allows you to write custom JavaScript code that executes on incoming requests at the URL endpoint level.

URL Endpoint Functions are ideal for migrations where:
- Your legacy system uses custom URL patterns that don't match standard platforms
- You need complex parameter extraction or path rewrites
- You have multi-tenant or multi-brand scenarios with different URL structures
- You can't change URLs in your application (embedded in content, printed materials, etc.)

**Important:** URL Endpoint Functions run **first**, followed by URL rewriters (if configured). This means you can use both together—the function pre-processes the URL, then the rewriter handles platform-specific transformations.

Learn more in the [URL Endpoint Functions documentation](/url-endpoint-functions).

## Platform-specific migration guides

In addition to URL rewriters, we have created platform-specific migration guides that provide step-by-step instructions on migrating from popular services like Cloudinary, Imgix, and Akamai Image Manager to ImageKit.

* [Migrate from Cloudinary to ImageKit](/migration/cloudinary-to-imagekit)
* [Migrate from Imgix to ImageKit](/migration/imgix-to-imagekit)
* [Migrate from Akamai Image Manager to ImageKit](/migration/akamai-to-imagekit)

## Managed migration for large accounts

For large accounts, we provide managed migration services, where our team of experts will work with you to plan and execute the migration with zero downtime. We have helped companies with millions of media files. Check out our [migration case studies](https://imagekit.io/blog/swiggy-imagekit-case-study/) of Swiggy to learn more.


---

# Source: /migration/cloudinary-to-imagekit

---
title: Migrate from Cloudinary to ImageKit
description: Learn how to migrate from Cloudinary to ImageKit without changing existing URLs. Additionally, discover tools to migrate uploaded files and media assets to ImageKit DAM.
---

If you are using Cloudinary for media asset delivery and storage, you can easily migrate to ImageKit without changing existing URLs. ImageKit provides tools and features that make the migration process seamless and easy. These capabilities have helped companies migrate in days instead of months with zero downtime.

Based on our experience of having done this migration for several customers, the following steps will help you migrate successfully to ImageKit with minimal effort and no downtime.

# Basic steps for migration
- [Connect your storage to ImageKit](#connect-your-storage-to-imagekit). This could be your Cloudinary backup bucket or any other cloud storage where your assets are stored
- [Set up ImageKit for media delivery](#set-up-imagekit-for-media-delivery) with the use of ImageKit URL Endpoints, Cloudinary URL Rewriter, custom domain names, and other features
- [Test and make the switch](#test-and-make-the-switch) to ImageKit for media delivery.
- [Switch new asset uploads](#switch-new-asset-uploads) to ImageKit's Media Library, if needed, using ImageKit's upload APIs.
- [Migrate old assets to ImageKit](#migrate-old-assets-from-cloudinary), using one of the few migration methods available

If your setup or requirement is more complex, you can always contact our team at [support@imagekit.io](mailto:support@imagekit.io) for assistance.


## Connect your storage to ImageKit
There are three ways in which this can be done

### Using Cloudinary Backup Bucket

If you store assets in Cloudinary's Media Library, you can [refer to their documentation](https://cloudinary.com/documentation/backups_and_version_management#using_your_own_backup_storage) and enable backup to your own AWS S3 bucket. Once this is turned on, all newly uploaded assets will automatically get added to this backup bucket. You will have to perform a one-time backup for your older assets to this bucket.

Once the backup is created, you can connect it using the [Cloudinary Backup Bucket integration](/integration/cloudinary-backup-bucket) in ImageKit.

### Using a cloud storage

Suppose you upload assets to an object storage like AWS S3 and use that with Cloudinary or have moved your assets to a cloud storage. In that case, you can connect it like a standard cloud storage bucket to ImageKit using one of the integrations available [here](/integration/connect-external-storage).

#### Temporary origin: Using Cloudinary as a Web Server

You can also add `https://res.cloudinary.com/<your_cloudinary_id>` as a [Web Server type of external storage](/integration/web-server) in ImageKit. When a request comes to ImageKit, we will get the assets from Cloudinary and perform optimizations and transformations on it. However, if your aim is to move away from Cloudinary, we do not recommend using this for the long run. If you use this, then you should definitely [migrate new asset uploads](#switch-new-asset-uploads) and [old asset uploads](#migrate-old-assets-from-cloudinary) to ImageKit.

{% callout style="info" %}
Cloudinary URLs have `/image/upload`, `/video/upload` etc. in their URLs. You may or may not want them in your final URLs with ImageKit, or your connected external storage may not have files on these paths. To handle this, you can change the Cloudinary backup bucket configuration or modify the "Asset and Delivery Type" setting of the Cloudinary URL Rewriter, as explained later.
{% /callout %}


## Set up ImageKit for Media Delivery
By the end of this section, we will have working URLs in ImageKit that can access the images on the same or similar paths to those in Cloudinary, and you will be ready for media delivery migration afterward.

### URL Endpoint

Ensure you have a [URL endpoint](/integration/connect-external-storage#url-endpoints) connected to the storage you added to ImageKit in Step 1. At this step, if a file is accessible via Cloudinary, it should also become accessible via ImageKit. 

```
<!-- Cloudinary URL without transformations -->
https://res.cloudinary.com/cloud_id/image/upload/v1231245131/rest-of-the-path.jpg

<!-- Corresponding ImageKit URL -->
https://ik.imagekit.io/imagekit_id/image/upload/v1231245131/rest-of-the-path.jpg
```

If this does not work, please check your origin configuration, [debug the error](/integration/connect-external-storage#troublshooting-404-errors), or contact [support@imagekit.io](mailto:support@imagekit.io) to get this working before proceeding to the next steps.

{% callout style="info" %}
Note that we are using Cloudinary's versioning `v1231245131` in the URL in the example above. You must use the Cloudinary URL Rewriter, as [explained below](#url-based-transformations), which automatically removes this versioning string for lookups.
{% /callout %}


### URL-based transformations

You have two options for transforming files using ImageKit URLs

#### Option 1 - Using Cloudinary URL Rewriter

Suppose you do not want to change the URL and want to continue using the Cloudinary transformations and versioning that appears in the URL. In that case, you should enable the Cloudinary URL Rewriter for your endpoint. This can be enabled under the "Advanced Settings" tab of the URL endpoint. Also, if you added a Cloudinary backup bucket with `res/<cloud_id/` as the Bucket folder, check the "Keep Cloudinary asset and delivery types" setting while enabling the rewriter. 
 
The transformations supported by the URL Rewriter, how they work, and the impact of this "Keep asset and delivery type" setting have been [explained here](#cloudinary-url-rewriter-specification).

![Cloudinary URL Rewriter](https://ik.imagekit.io/ikmedia/docs_images/integration/url-endpoints/url-rewriter.png?tr=w-1200)

If you opt for this, your URL will look like this.

```
<!-- URL with Cloudinary transformations -->
https://ik.imagekit.io/your_imagekit_id/image/upload/w_200,h_300,f_auto,q_auto/rest-of-the-path.jpg
```

#### Option 2 - Using ImageKit Transformations

You can use ImageKit's transformation parameters in the URL. While this requires a URL change, it guarantees that all possible transformations will work, not just the ones supported in the URL rewriter. If you opt for this, your URL will look like this.

```
<!-- With transformations in path -->
https://ik.imagekit.io/your_imagekit_id/image/upload/tr:w-200,h-300/v1233223113/rest-of-the-path.jpg

<!-- With transformations in query -->
https://ik.imagekit.io/your_imagekit_id/image/upload/v1233223113/rest-of-the-path.jpg?tr=w-200,h-300
```

{% callout style="info" %}
Unlike Cloudinary, ImageKit can automatically compress and convert the media file to the correct format without having any parameters in the URL. That is why the ImageKit transformation URLs above don't have any format or quality parameters. Read more about it [here](/image-optimization).
{% /callout %}


### Setup a custom domain name

All ImageKit paid plans offer a [custom domain name](/docs/core-delivery-features#using-custom-domain-name). You may or may not use one with Cloudinary, but we recommend setting it up in ImageKit.

With the domain set up, your URL will look like this.

```
<!-- URL with Cloudinary transformations + ImageKit Cloudinary URL Rewriter -->
https://media.yourdomain.com/image/upload/w_200,h_300,f_auto,q_auto/rest-of-the-path.jpg

<!-- URL with ImageKit transformations in path -->
https://media.yourdomain.com/image/upload/tr:w-200,h-300/rest-of-the-path.jpg

<!-- URL with ImageKit transformations in query -->
https://media.yourdomain.com/image/upload/rest-of-the-path.jpg?tr=w-200,h-300
```

As you can see above, with the Cloudinary URL Rewriter enabled in ImageKit, the URL looks exactly like what you would have on Cloudinary. This means that, in many cases, after the right setup, moving to ImageKit would be as simple as a DNS switch.

{% callout style="info" %}
To have no impact on your production setup with Cloudinary, we recommend setting up a domain name parallel to the one you use with Cloudinary. For example, if you use `media.yourwebsite.com` with Cloudinary, get `media2.yourwebsite.com` set up with ImageKit. This allows you to test and compare URLs in parallel. Once tested, you can always switch the DNS for even the old domain `media.yourwebsite.com` to get it to work with ImageKit.
{% /callout %}

## Test and make the switch

Now, you should be able to access existing assets stored in Cloudinary through ImageKit.

At this stage, you should test the following.

1. Is the image or video accessible using Cloudinary now also accessible using ImageKit, just by changing `res.cloudinary.com/cloud_id` in the URL with `ik.imagekit.io/your_imagekit_id` or with the custom domain?
2. Does the transformation with ImageKit's Cloudinary URL Rewriter give you the same output image as the original Cloudinary transformation?
3. Have you removed Cloudinary's versioning parameter from the URLs or enabled the Cloudinary URL Rewriter? 

Once you are confident that ImageKit is serving your assets correctly, you can either:

1. Replace `res.cloudinary.com/cloud_id` with `ik.imagekit.io/your_imagekit_id` or the custom domain name set up in ImageKit in your application code.
2. If you use a custom domain with Cloudinary, update your DNS to point your existing domain to ImageKit. The ImageKit support team or your point of contact at ImageKit will give you this DNS change. This option requires no changes in your application code.


## Switch new asset uploads

Once you have switched the delivery of existing assets on Cloudinary to ImageKit, you should see a decrease in bandwidth output from your Cloudinary account. 

We now need to change the asset uploads.

If you upload assets to Cloudinary, either using their dashboard or Cloudinary's APIs, you will switch to uploading new assets to ImageKit Media Library, the integrated DAM, via the dashboard or the upload APIs.

This will ensure that for new assets, ImageKit gets the original asset from its own DAM, and does not go to your connected storage in Step 1.

If you use an external object storage like AWS S3 with Cloudinary and continue to do the same with ImageKit, then this step is optional if your team wishes to use ImageKit's Digital Asset Management capabilities.

## Migrate old assets from Cloudinary

With the number of assets now constant in the Cloudinary media library, we can now move the remaining assets from Cloudinary to ImageKit DAM. There are a few ways to do it -

1. Using [imagekit cli](https://github.com/imagekit-developer/imagekit-cli) - This CLI is easy to configure and use. It downloads files from Cloudinary and uploads them to ImageKit DAM.
2. Do It Yourself - You can write a script to download files from Cloudinary and upload them to ImageKit DAM using APIs. We recommend this method only if you have to migrate some metadata or tags from Cloudinary to ImageKit or have any other requirement that the CLI does not fulfill.

After this step is completed, ImageKit will get all the assets from its own DAM instead of from the connected external storage. This means that you should not see any new storage or bandwidth usage on your Cloudinary account, and all assets on your website or app should be served via ImageKit after this step. 
   
## Cloudinary URL Rewriter specification
The Cloudinary URL Rewriter automatically understands Cloudinary transformations and versioning in the URL and either removes them or translates them internally to ImageKit equivalents. Using this, you don't have to change your Cloudinary URL and can still get the same transformations with ImageKit.

The following Cloudinary transformations are supported for translation:

{% table %}

- Cloudinary transformation {% width="20%" %}
- Example translation  {% width="40%" %}
- Remarks  {% width="40%" %}

---

- width
- `w_100` → `w-100`
- 

---

- height
- `h_100` → `h-100`
- 

---

- aspect ratio
- `ar_2.5` → `ar-2.5-1`

  `ar_3` → `ar-3-1`

  `ar_4:3` → `ar-4-3`
- 

---

- gravity
- `g_north` → `fo-top`

  `g_center` → `fo-center`

  `g_auto` → `fo-auto`

  `g_face` → `fo-face`
- Supported values: 
  - north
  - south
  - east
  - west
  - north_west
  - north_east
  - south_east
  - south_west
  - auto
  - custom
  - face

---

- x
- `x_100` → `x-100`
-

---

- y
- `y_100` → `y-100`
-

---

- format
- `f_jpg` → `f-jpg`
- Supported values: 
  - auto
  - jpg
  - jpeg
  - png
  - webp
  - gif
  - avif

---

- quality
- `q_60` → `q-60`

  `q_auto` → `q-70`

  `q_auto:low` → `q-50`
- Auto quality mapping (images):
    - low: 50
    - eco: 60
    - good: 70
    - best: 86
  
  Auto quality mapping (videos):
    - low: 40
    - eco: 45
    - good: 50
    - best: 60

---

- angle
- `a_90` → `rt-90`

  `a_-67` → `rt-N67`
-

---

- radius
- `r_20` → `r-20`

  `r_20:30:40:50` → `r-20`

  `r_max` → `r-max`
-

---

- effects
- `e_blur` → `bl-1`

  `e_blur:500` → `bl-5`

  `e_grayscale` → `e-grayscale`

  `e_contrast:100` → `e-contrast`

  `e_sharpen:500` → `e-sharpen-5`

  `e_unsharp_mask:500` → `e-usm-0-5-1-0.05`

  `e_unsharp_mask:250` → `e-usm-0-2.5-1-0.05`

  `e_trim` → `t-true`

  `e_trim:20` → `t-20`

  `e_trim:20:red` → `t-20`

  `e_replace_color:green` → `cr-green`

  `e_replace_color:green:40:2F4F4F` → `cr-green_40_2F4F4F`

  `e_distort:150:340:1500:10:1500:1550:50:1000` → `e-distort-p-150_340_1500_10_1500_1550_50_1000`

  `e_distort:arc:120` → `e-distort-a-120`

  `e_cut_out` → `lm-cutout`

  `e_multiply` → `lm-multiply`

  `e_displace` → `lm-displace`

  `e_colorize:55` → `e-colorize-in-55`

  `co_darkviolet,e_colorize:55` → `e-colorize-co-darkviolet_in-55`

- Supported values:
    - blur
    - grayscale
    - contrast
    - sharpen
    - unsharp_mask
    - trim
    - replace_color
    - distort
    - multiply
    - cut_out
    - displace
    - colorize
  
  The final output from ImageKit may vary from the output from Cloudinary.

---

- border
- `bo_5px_solid_red` → `b-5-red`

  `bo_5px_solid_BLUE` → `b-5-blue`

  `bo_5px_solid_rgb:AAAA54` → `b-5-AAAA54`

  `bo_5px_solid_rgb:AAAA54A9` → `b-5-AAAA5466`

  `bo_5px_solid_rgb:B4F` → `b-5-BB44FF`

  `bo_5px_solid_rgb:B4F9` → `b-5-BB44FF60`

- 1. Color values are case insensitive. 
  1. Alpha values in RGB codes are accepted in the range [00-FF] and translated to a value in the range [00-99]
   
---

- background
- `b_red` → `bg-red`

  `b_BLUE` → `bg-blue`

  `b_rgb:AAAA54` → `bg-AAAA54`

  `b_rgb:AAAA54A9` → `bg-AAAA5466`

  `b_rgb:B4F` → `bg-BB44FF`

  `b_rgb:B4F9` → `bg-BB44FF60`

  `b_blurred` → `bg-blurred`

  `b_blurred:100` → `bg-blurred_5`

  `b_blurred:100:10` → `bg-blurred_5_25`

  `b_auto:predominant_gradient` → `bg-gradient_dominant`

  `b_auto:predominant_gradient:2` → `bg-gradient_dominant_2`

  `b_auto:predominant_gradient:4` → `bg-gradient_dominant_4`

- 1. Color values are case insensitive. 
  2. Alpha values in RGB codes are accepted in the range [00-FF] and translated to a value in the range [00-99]
  3. `b_blurred` for blurred background with automatic blur-intensity.
  4. `b_blurred[:BlurIntensity][:Brightness]` for customized blur-intensity & brightness, blur-intensity is accepted in the range 0 to 2000, and brightness is accepted in the range -300 to 100 (negative value for darker background & positive value for lighter background)

---

- colorize
- `co_red` → `otc-red`

  `co_BLUE` → `otc-blue`

  `co_rgb:AAAA54` → `otc-AAAA54`

  `co_rgb:AAAA54A9` → `otc-AAAA5466`

  `co_rgb:B4F` → `otc-BB44FF`

  `co_rgb:B4F9` → `otc-BB44FF60`

- 1. These `co_*` → `otc-*` mappings apply **to text overlays** (they set overlay text color). 
  2. `co_*` with `e_colorize` is used to specify the color of tint as explained [here](/effects-and-enhancements#colorize---e-colorize).
  2. Color values are case insensitive. 
  3. Alpha values in RGB codes are accepted in the range [00-FF] and translated to a value in the range [00-99]

---

- DPR
- `dpr_3.0` → `dpr-3.0`
-

---

- crop
- `c_crop` → `cm-extract`

  `c_fill` → `c-maintain_ratio`

  `c_fit` → `c-at_max_enlarge`

  `c_limit` → `c-at_max`

  `c_pad` → `cm-pad_resize`

  `c_scale` → `c-force`

  `c_lpad` → `cm-pad_resize_no_enlarge`

  `c_mpad` → `cm-pad_extract_no_shrink`

  `c_lfill` → `c-maintain_ratio_no_enlarge`
- Supported values: 
  - crop
  - fill
  - fit
  - limit
  - pad
  - scale
  - lpad
  - mpad
  - lfill
  
---

- text overlays
- `l_text:Roboto_50:<value>` → `ot-<value>,otf-Roboto,ots-50`

  `l_text:Roboto_50_bold_left:<value>` → `ot-<value>,otf-Roboto,ots-50,ott-b,otia-left`

  `l_text:<fontPath>_50_bold_left:<value>` → `ot-<value>,otf-<fontPath>,ots-50,ott-b,otia-left`

- Supported text style qualifiers: 
  - bold
  - italic
  - left
  - right
  - center
  - start
  - end
  
  [Custom fonts](/add-overlays-on-images#custom-fonts-example) can be used by specifying the full path to a font file in your Media Library

---

- image overlays
- `l_<imagePath>` → `oi-<imagePath>`
- Full path to the overlaid image in the Media Library must be specified

---

- named transform
- `t_<transform_name>` → `n-<transform_name>`
- ImageKit does not translate the actual underlying transformations associated with your named transforms. They must be manually translated and [added in your ImageKit dashboard](/transformations#named-transformations) while retaining the same name.

---

- fl_progressive
- `fl_progressive` → `pr-true`

  `fl_progressive:steep` → `pr-true`

  `fl_progressive:semi` → `pr-true`

  `fl_progressive:none` → `pr-false`
-

---

- fl_layer_apply
-
- Marks the end of a group of transformations being applied in the context of an overlay. ImageKit detects the presence of a `fl_layer_apply` and applies the relevantly positioned transforms to the overlaid asset instead of the main asset.

---

- fl_cutter
- `fl_cutter` → `e-cutter`
-
 
---

- start offset
- `so_10.5599` → `so-10.56`
-

---

- end offset
- `eo_10.5522` → `eo-10.55`
-

---

- duration
- `du_10.5500` → `du-10.55`
-

---

- zoom
- `z_2.0` → `z-2.0`

  `z_0.5` → `z-0.5`
- 

---

- default image

- `d_notfound.png` → `di-notfound.png`
-

{% /table %}

**Note:** The rewriter will silently ignore any transformation with a valid key but an invalid value. For example, `h_100,w_<invalid>/a_90`  will be translated to `h-100:rt-90`. Refer to the table to see what constitutes a valid value for different transforms.

### Handling unsupported Cloudinary transformations
By default, when the rewriter encounters a Cloudinary transformation that is not supported for rewriting, it ignores it and continues translating other transformations in the URL. For example, `cs_srgb/a_90`  will be translated to `rt-90`. You can change this behavior so that such URLs are not rewritten at all using the "Skip rewrite if unsupported transformation is present" setting.

### Asset and Delivery type setting in Cloudinary URL Rewriter

When you have `/image/upload` in the Cloudinary URL, these are the asset (`image`) and the delivery types (`upload`). If you enable the "Keep Cloudinary asset and delivery types" setting, then ImageKit will forward `/image/upload`, `/video/upload`, etc., as it appears in the URL, to the external storage connected to ImageKit. With this setting disabled, ImageKit removes `/image/upload/`, `/video/upload`, etc., from the URL before forwarding the remaining file path to the external storage. Disabling it is useful when you have an external storage that does not have these folders or if you have connected the Cloudinary backup bucket with the Bucket folder as `res/<cloud_id>/image/upload`, etc., as [mentioned here](/integration/cloudinary-backup-bucket#other-options-for-your-url-with-imagekit).

Cloudinary also supports prefixes such as `/images`, `/files`, and `/private_files` instead of the standard `/image/upload`, `/raw/upload`, and `/image/private` for dynamic SEO suffixes. ImageKit detects the presence of such a prefix in your URL and interprets it using [Dynamic suffixes](/docs/seo-friendly-url), a similar feature available in ImageKit. Irrespective of the above setting, the prefix `/images`, `/files`, or `/private_files` is removed from the URL before attempting to get the object from the origin.


---

# Source: /migration/imgix-to-imagekit

---
title: Migration from Imgix to ImageKit.io
description: Learn how to migrate from Imgix to ImageKit without changing existing URLs.
---

If you are using Imgix, migrating to ImageKit.io is straightforward and can be done without changing your existing URLs. This guide will help you understand the steps to migrate from Imgix to ImageKit.io.

## Step 1: Configure external storage

ImageKit supports all external storage that Imgix supports. That means you can easily configure existing storage in ImageKit. Refer to [configure external storage](/integration/connect-external-storage) and follow the integration steps based on your storage.

## Step 2: Enable Imgix URL rewriter

Open [URL endpoints](https://imagekit.io/dashboard/url-endpoints/) in the dashboard, and enable "URL rewriter" in the desired URL endpoint under the "Advanced settings" tab, and select "Imgix" from the dropdown. This will parse the incoming URL transformations to the format that ImageKit understands. This allows you to keep the existing Imgix transformations in your application and still use ImageKit for media optimization, transformation, and delivery.

![Imgix URL rewriter](https://ik.imagekit.io/ikmedia/docs_images/integration/url-endpoints/imgix-rewriter.png?tr=w-1200)

## Step 3: Test and make the switch

Now, you should be able to access existing assets through ImageKit. At the same time, existing Imgix transformations should work without any changes.

Let's fetch an image without any transformation. The same would work for other file types as well.

* **Original image through Imgix (old URL)**\
 [https://example.imgix.net/rest-of-the-path.jpg](https://example.imgix.net/rest-of-the-path.jpg)
* **The same image using ImageKit.io URL endpoint**\
 [https://ik.imagekit.io/your_imagekit_id/rest-of-the-path.jpg](https://ik.imagekit.io/your_imagekit_id/rest-of-the-path.jpg)

Let's see if transformations work as expected. The same would work for videos as well.

* **Imgix transformation (old URL)**\
 [https://example.imgix.net/rest-of-the-path.jpg?w=100](https://example.imgix.net/rest-of-the-path.jpg?w=100)
* **With ImageKit**\
 [https://ik.imagekit.io/your_imagekit_id/rest-of-the-path.jpg?w=100](https://ik.imagekit.io/your_imagekit_id/rest-of-the-path.jpg?w=100)

Refer to the [Imgix URL rewriter specification](#imgix-url-rewriter-specification) for a list of supported transformations and how they are translated.

Once you are confident that ImageKit is serving your assets correctly, you can either:

1. **If you use a custom domain on Imgix**, then read more about [setting up a custom domain](/docs/core-delivery-features#using-custom-domain-name) on ImageKit for media delivery.
2. Otherwise, replace the imgix domain `example.imgix.net` in your URLs with `ik.imagekit.io/your_imagekit_id`.

## Imgix URL rewriter specification


{% table %}

- Imgix transformation {% width="20%" %}
- Example translation  {% width="40%" %}
- Remarks  {% width="40%" %}

---

- width
- `w=100` → `w-100`
- 

---

- height
- `h=100` → `h-100`
- 

---

- aspect ratio
- `ar=2:3` → `ar-2-3`

  `ar=3:1` → `ar-3-1`

  `ar=2:4` → `ar-2-4`
- Aspect ratio will only work when we provide either width or height (not both) and fit

---

- crop
- `crop=top` → `fo-top`

  `crop=top,left` → `fo-top_left`

  `crop=left,top` → `fo-top_left`

  `crop=faces` → `fo-auto`
- Supported values:

  - top

  - left

  - right

  - bottom

  - top,left

  - top,right

  - bottom,right

  - bottom,left

  - left,top

  - right,top

  - right,bottom

  - left,bottom

  - faces

---

- fit
- `fit=clip` → `c-at_max_enlarge`

  `fit=fill` → `cm-pad_resize`

  `fit=scale` → `c-force`

  `fit=crop` → `no mapping required`

  `fit=fillmax` → `cm-pad_resize`

  `fit=max` → `c-at_max`

  `fit=facearea` → `fo-face`
- Supported values:

  - clip

  - crop

  - fill

  - fillmax

  - max

  - scale

  - facearea

 For fit=fillmax, if the requested dimensions are greater than the original dimensions, then the padding will be added along either one of the dimensions (height or width), not both.

---

- fill
- 
- Supported values:

  - solid

 Blur will fall back to solid

---

- format
- `fm=jpg` → `f-jpg`
- Supported values:

  - jpeg → jpeg

  - jpg → jpg

  - jp2 → jpg

  - png → png

  - webp → webp

  - gif → gif

  - avif → avif

  - png8 → png

  - png32 → png

---

- quality
- `q=60` → `q-60`
- 

---

- orient
- 
- Supported values:

  - 1 → 0

  - 6 → 90

  - 3 → 180

  - 8 → 270

  - 0 → 0

  - 90 → 90

  - 180 → 180

  - 270 → 270

 Counterclockwise rotation via orient is not supported

---

- fill-color
- `fill-color=red` → `bg-red`

  `fill-color=BLUE` → `bg-blue`

  `fill-color=AAAA54` → `bg-AAAA54`

  `fill-color=A9AAAA54` → `bg-AAAA5466`

  `fill-color=B4F` → `bg-BB44FF`

  `fill-color=9B4F` → `bg-BB44FF60`
- Color values are case-insensitive

 Alpha values in RGB codes are accepted in the range [00-FF] and translated to a value in the range [00-99]

---

- bg
- `bg=red` → `bg-red`

  `bg=BLUE` → `bg-blue`

  `bg=AAAA54` → `bg-AAAA54`

  `bg=A9AAAA54` → `bg-AAAA5466`

  `bg=B4F` → `bg-BB44FF`

  `bg=9B4F` → `bg-BB44FF60`
- Color values are case-insensitive

 Alpha values in RGB codes are accepted in the range [00-FF] and translated to a value in the range [00-99]

---

- dpr
- `dpr=3.0` → `dpr-3.0`
- 

---

- sharp
- `sharp=10` → `e-sharpen-200`

  `sharp=100` → `e-sharpen-2000`
- The final result produced by ImageKit could differ from the result obtained from Imgix.

---

- con
- `con=30` → `e-contrast`

  `con=-50` → `e-contrast`
- The final result produced by ImageKit could differ from the result obtained from Imgix.

---

- usm
- `usm=40` → `e-usm-2.5-8.00-1-0.05`
- The final result produced by ImageKit could differ from the result obtained from Imgix.

---

- usmrad
- `usm=-50&usmrad=2` → `e-usm-2-0.00-1-0.05`
- usmrad only works in conjunction with usm

  The final result produced by ImageKit could differ from the result obtained from Imgix.

---

- blur
- `blur=100` → `bl-5.00`

  `blur=90` → `bl-4.50`
- The final result produced by ImageKit could differ from the result obtained from Imgix.

---

- trim
- `trim=auto` → `t-true`

  `trim=color` → `t-true`
- The final result produced by ImageKit could differ from the result obtained from Imgix.

{% /table %}


---

# Source: /migration/akamai-to-imagekit

---
title: Migration from Akamai to ImageKit.io
description: Learn how to migrate from Akamai Image Manager to ImageKit without changing existing URLs.
---

Akamai Image Manager has limited image optimization and transformation support compared to ImageKit.io. Migrating to ImageKit.io can help you leverage advanced image optimization and transformation capabilities, leading to faster loading times and improved user experience. This guide outlines the steps for migrating your media assets delivery and optimization from Akamai Image Manager to ImageKit.io.

## Step 1: Configure your origin in ImageKit.io

ImageKit.io supports all external storage that Akamai Image Manager supports. That means you can easily configure existing storage in ImageKit. Refer to [configure external storage](/integration/connect-external-storage) and follow the integration steps based on your storage.

{% callout "info" %}
If you use Akamai NetStorage, [expose it on a public endpoint](https://techdocs.akamai.com/netstorage/docs/downloads-with-netstorage#add-netstorage-as-the-origin) and configure it as [web folder](/integration/web-server) in ImageKit.

Alternatively, you can migrate your assets to your own S3 or ImageKit storage using Rclone. Refer to [https://rclone.org/netstorage/](https://rclone.org/netstorage/) and [https://rclone.org/imagekit/](https://rclone.org/imagekit/) for more information.
{% /callout %}

## Step 2: Enable Akamai URL rewriter

Open [URL endpoints](https://imagekit.io/dashboard/url-endpoints/) in the dashboard, and enable URL rewriter in the desired URL endpoint under the "Advanced settings" tab. This will rewrite the incoming URL to the format that ImageKit understands. This allows you to keep the existing Akamai transformations in your application and still use ImageKit for media optimization, transformation, and delivery.

![Akamai URL rewriter](https://ik.imagekit.io/ikmedia/docs_images/integration/url-endpoints/akamai-url-rewriter.png?tr=w-1200)

## Step 3: Test and make the switch

Now, you should be able to access existing assets through ImageKit. At the same time, existing Akamai transformations should work without any changes.

{% callout "warning" %}
Test the migration thoroughly before making the switch. You can use a local host entry to test the migration without changing the DNS settings.
{% /callout %}

### Create a local host entry
You should create a separate property in Akamai to test the migration. This will help you test the migration without changing the DNS settings.

However, if you want to test on existing domain names, you can create a local host entry in your system to point the domain to ImageKit. This will help you test the migration without changing the DNS settings.

Use the `dig ik.imagekit.io` command to find the IP address and add the following entry to your host file.

**For Windows**

1. Open your text editor in Administrator mode.
2. In the text editor, open C:\Windows\System32\drivers\etc\hosts.
3. Add the IP Address and hostname. \
   Example: `171.10.10.5 custom.domain.com`
4. Save the changes.
 
**For Linux**

1. Open terminal.
2. Use the nano command line text editor or a different one you have available to open the host file. The command with nano is as follows (the command will require your Linux user password) 
3. `sudo nano /etc/hosts`
4. Add the appropriate changes in the host file. \
   Example: `171.10.10.5 custom.domain.com`
5. Use the Control and 'X' key combination to save the changes.

Let's fetch an image without any transformation. The same would work for other file types as well.

* **Original image through Akamai (old URL)**\
 [http://custom.domain.com/rest-of-the-path.jpg](http://custom.domain.com/rest-of-the-path.jpg)
* **The same image using ImageKit.io URL endpoint**\
 [http://custom.domain.com/rest-of-the-path.jpg](http://custom.domain.com/rest-of-the-path.jpg)

Let's see if transformations work as expected. The same would work for videos as well.

* **Akamai transformation (old URL)**\
 [http://custom.domain.com/rest-of-the-path.jpg?imwidth=420](http://custom.domain.com/rest-of-the-path.jpg?imwidth=420)
* **With ImageKit**\
 [http://custom.domain.com/rest-of-the-path.jpg?imwidth=420](http://custom.domain.com/rest-of-the-path.jpg?imwidth=420)

For a list of supported transformations and how they are translated, refer to the [Akamai URL Rewriter specification](#akamai-url-rewriter-specification).

Once you are confident that ImageKit is serving your assets correctly, you should update your DNS settings to point to ImageKit. This will ensure that all your assets are served through ImageKit.

## Akamai URL rewriter specification

{% table %}

- Akamai transformation {% width="30%" %}
- Example translation  {% width="70%" %}

---

- width
- `imwidth=100` → `w-100`


---

- height
- `imheight=100` → `h-100`

---

- Resize
- `im=Resize=(250,125)` → `w-250,h-125,c-at_max`

  `im=Resize,width=250,height=125` → `w-250,h-125,c-at_max`

  `im=Resize,height=250,width=125` → `h-250,w-125,c-at_max`

---

- Scale
- `im=Scale=(0.6,1.5)` → `w-0.6_mul_iw,h-1.5_mul_ih,c-force`

  `im=Scale,width=0.6,height=1.5` → `w-0.6_mul_iw,h-1.5_mul_ih,c-force`

  `im=Scale,height=0.6,width=1.5` → `h-0.6_mul_ih,w-1.5_mul_iw,c-force`
  
---
- format
- `imformat=chrome` → `f-webp`

  `imformat=safari` → `f-orig`

  `imformat=generic` → `f-orig`

{% /table %}


---

# Source: /url-endpoint-functions

---
title: URL Endpoint Functions
description: Execute custom JavaScript functions to dynamically rewrite URLs for complex migration scenarios and custom routing logic.
---

URL Endpoint Functions let you run custom JavaScript code on incoming requests before ImageKit processes them. Use them for migrations where standard [URL rewriters](/migration/overview#url-rewriters) don't fit your legacy URL patterns.

**Use cases:** Migrate from legacy systems with custom URL formats, extract and convert transformation parameters from non-standard patterns, and handle complex path rewrites during consolidation.

## How it works

Functions are created and published by the ImageKit team. Once published, you can attach them to any URL endpoint. Clone our [GitHub template](https://github.com/imagekit-developer/url-endpoint-function-ACME) with support for multiple handlers, write your functions with tests, then contact ImageKit to deploy them. View and attach published functions in your [dashboard](https://imagekit.io/dashboard/settings/url-endpoint-functions).

The repository supports multiple handlers (`handler1.js`, `handler2.js`, etc.), each with its own test suite.

{% callout type="info" %}
**Execution order:** Functions run first, then URL rewriters (if configured), so you can use both together. Functions have a 1-second timeout and support standard Node.js modules (`crypto`, `url`, `querystring`, `path`) but not external npm packages.
{% /callout %}

## Function specification

```javascript
function handler(url, urlPrefix, context) {
  // Your logic here
  return { url: modifiedUrl }
}

module.exports.handler = handler
```

**Parameters:**
- `url` - Full request URL with protocol, hostname, path, and query string
- `urlPrefix` - URL endpoint identifier (e.g., `"product-images"`)
- `context.clientNumber` - Client identifier  
- `context.logger` - Logger for errors and info

**Return values:**

Continue processing:
```javascript
{ 
  url: string,       // Required: Full URL with protocol and hostname
  signURL: boolean   // Optional: Sign the URL? (default: false)
}
```

Early response (stop processing):
```javascript
{
  status: number,                    // Required: HTTP status code
  body: string | object,             // Required: Response body
  headers: Record<string, string>    // Optional: Response headers
}
```

## Examples

### Example 1: Simple Path Rewrite for Migration

When migrating from a legacy system where URLs used different versioning paths:

```javascript
function handler(url, urlPrefix, context) {
  // Migrate old /v1/ paths to /v2/ paths
  // Useful when you can't change URLs in your application
  return {
    url: url.replace("/v1/", "/v2/"),
  }
}

module.exports.handler = handler
```

**Use case:** You have thousands of URLs in your CMS, emails, or printed materials pointing to `/v1/` paths, but your new storage structure uses `/v2/` paths.

### Example 2: Parameter Extraction Pattern

Extract transformation parameters from legacy URL formats and convert them to ImageKit's format:

```javascript
function handler(url, urlPrefix, context) {
  // Convert: /w_100/h_200/image.jpg → /image.jpg?tr=w-100,h-200

  const parsedUrl = new URL(url)
  const params = []
  const regex = /\/(w|h)_(\d+)/g

  // Extract parameters and build transformation string
  let cleanPath = parsedUrl.pathname.replace(regex, (match, key, value) => {
    params.push(`${key}-${value}`)
    return ""
  })

  // Clean up multiple slashes
  cleanPath = cleanPath.replace(/\/{2,}/g, "/")

  if (params.length > 0) {
    parsedUrl.pathname = cleanPath
    parsedUrl.search = `?tr=${params.join(",")}`
  }

  return {
    url: parsedUrl.toString(),
    signURL: true, // ImageKit will sign the modified URL
  }
}

module.exports.handler = handler
```

**Example transformation:**
- Input: `https://ik.imagekit.io/demo/w_300/h_200/product.jpg`
- Output: `https://ik.imagekit.io/demo/product.jpg?tr=w-300,h-200`

**Use case:** Migrating from a system that embedded transformation parameters in the path (like an older CDN or custom solution) where changing application code isn't feasible.

### Example 3: Using with URL Rewriters

Combine URL Endpoint Functions with URL rewriters for complex migrations:

```javascript
function handler(url, urlPrefix, context) {
  const parsedUrl = new URL(url)
  
  // First, remove your old CDN's specific prefix
  parsedUrl.pathname = parsedUrl.pathname.replace(/^\/legacy-cdn\//, "/")
  
  // The modified URL will then be processed by Cloudinary URL rewriter
  // if you have it enabled on this endpoint
  return {
    url: parsedUrl.toString(),
  }
}

module.exports.handler = handler
```

**Use case:** Migrating from a custom CDN setup that wrapped Cloudinary URLs. The function strips your custom prefix, then the Cloudinary URL rewriter handles the Cloudinary-specific transformations.

### Example 4: Error Handling and Logging

Always handle errors and log for debugging:

```javascript
function handler(url, urlPrefix, context) {
  try {
    context.logger.info({ url }, "Processing request")
    
    const modifiedUrl = complexTransform(url)
    
    context.logger.info({ modifiedUrl }, "Transform complete")
    return { url: modifiedUrl }
  } catch (error) {
    context.logger.error({ error: error.message }, "Transform failed")
    return { url } // Fallback to original
  }
}

function complexTransform(url) {
  // Your transformation logic
  return url
}

module.exports.handler = handler
```

## Development workflow

### 1. Clone the template repository

Clone our [GitHub template](https://github.com/imagekit-developer/url-endpoint-function-ACME) which supports multiple handlers in one repository. Each handler follows the naming pattern `handler1.js` + `handler1.test.js`, `handler2.js` + `handler2.test.js`, etc. The template includes ready-to-use examples in the `/examples` folder, a Jest test suite, GitHub Actions CI/CD, and coverage reporting.

```bash
git clone https://github.com/imagekit-developer/url-endpoint-function-ACME.git
cd url-endpoint-function-ACME
npm install
```

### 2. Write and test your handlers

Create or modify handler files (e.g., `handler1.js`):

```javascript
function handler(url, urlPrefix, context) {
  // Your logic
  return { url: modifiedUrl }
}

module.exports.handler = handler;
```

Add corresponding tests in `handler1.test.js` and run:

```bash
npm test              # Run all tests
npm run test:watch    # Watch mode
npm run test:coverage # With coverage
```

All `handler*.js` files are tested automatically by the CI pipeline.

### 3. Request deployment

Contact [support@imagekit.io](mailto:support@imagekit.io) with your GitHub repository URL, the handler filename(s) you want published (e.g., `handler1.js`, `handler2.js`), function name(s) and descriptions, and target URL endpoints. The ImageKit team will create and publish your functions.

### 4. Attach to URL endpoints

Once published, view available functions in your [dashboard](https://imagekit.io/dashboard/settings/url-endpoint-functions) and attach them to URL endpoints under "Advanced settings".

## Combining with URL rewriters

Functions run before URL rewriters, enabling powerful combinations:

```javascript
function handler(url, urlPrefix, context) {
  // Strip legacy prefix
  const modifiedUrl = url.replace("/legacy/media/", "/")
  
  // URL then processed by Cloudinary rewriter (if enabled)
  // which handles w_300,h_200 syntax
  return { url: modifiedUrl }
}

module.exports.handler = handler
```

## Functions vs URL Rewriters

| Feature | URL Rewriters | URL Endpoint Functions |
|---------|---------------|------------------------|
| **Use case** | Standard platform migrations (Cloudinary, Imgix, Akamai) | Custom legacy URL patterns |
| **Configuration** | Select from dropdown | Custom JavaScript code |
| **Execution order** | Second | First |
| **Best for** | Quick migrations from known platforms | Complex custom requirements |

## Related resources

See also: [URL Rewriters](/migration/overview#url-rewriters) for Cloudinary, Imgix, and Akamai migrations, [URL Endpoints](/integration/connect-external-storage#url-endpoints) for endpoint configuration, and [Transformations](/transformations) for ImageKit transformation parameters.

## Need help?

Contact [support@imagekit.io](mailto:support@imagekit.io) for assistance with function development or deployment.


---

# Source: /transformations

---
title: Transform and adapt media assets
description: Learn how URL-based transformations work in ImageKit and how to adapt media assets to your requirements.
---

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.

## Basic example and URL structure

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:

{% linetabs %}
{% linetab title="Original 600x600 image" %}

[https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg)

![](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg)

{% /linetab %}
{% linetab title="Resized 300x300 image" %}

[https://ik.imagekit.io/ikmedia/tr:w-300,h-300/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:w-300,h-300/docs_images/examples/example_food_3.jpg)

![](https://ik.imagekit.io/ikmedia/tr:w-300,h-300/docs_images/examples/example_food_3.jpg)

{% /linetab %}

{% /linetabs %}

## Transformations overview

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

{% table %}

- Transformation {% width="40%" %}
- Images
- Videos

---

- Basic
- Resize, crop, smart crop images. [Learn more](/image-resize-and-crop).
- Resize and crop videos. [Learn more](/video-resize-and-crop).

---

- Common transformations
- All common image transformations like quality, format, rotation, border, etc. \
 [Learn more](/effects-and-enhancements).
- - All common video transformations like background color, border, radius, rotation, etc. [Learn more](/common-video-transformations).
  - [Trim videos](/trim-videos) - control start and end time.
  - [Audio related transformations](/audio-transformations) - mute video, extract audio, etc.

---

- Generate thumbnails
- Generate thumbnails from vector and animated images. \
 [Learn more](/vector-and-animated-images).
- Create video thumbnails. \
 [Learn more](/create-video-thumbnails).

---

- Overlays
- Add image and text overlays on images. \
 [Learn more](/add-overlays-on-images).
- Add image, video, text, and subtitle overlays to videos. \
 [Learn more](/add-overlays-on-videos).

---
- Arithmetic expressions
- Supported in images. \
 [Learn more](/arithmetic-expressions-in-transformations).
- Supported in videos. \
 [Learn more](/arithmetic-expressions-in-transformations).

---

- Conditional transformations
- You can apply transformations conditionally based on certain properties of the input asset. [Learn more](/conditional-transformations).
- Not supported in video.

---

- AI transformations
- Generate images via a text prompt, remove background, change background, crop objects, improve image quality, and more. [Learn more](/ai-transformations).
- Not supported in video.

---

- Adaptive bitrate streaming
- Not applicable.
- Use Adaptive Bitrate Streaming for long videos with ImageKit. \
 [Learn more](/adaptive-bitrate-streaming).
  
{% /table %}

## Troubleshooting invalid transformation

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:

![Invalid transformation](https://ik.imagekit.io/ikmedia/docs_images/features/transformation/invalid-transformation.png?tr=w-1200)

{% callout style="info" %}
For not found error, you can consider using [default image](/image-transformation#default-image---di) transformation for better user experience.
{% /callout %}

## Limits

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](mailto:support@imagekit.io) if you need to adjust these limits.

{% table %}

- Limits {% width="70%" %}
- Free plan {% width="10%" %}
- Paid plan {% width="10%" %}
- Adjustable {% width="10%" %}

---

- Max image file size for processing.
- 20MB
- 40MB
- Yes

---

- Max video file size for processing.
- 100MB
- 2GB
- Yes

---

- Max raw file size for delivery (includes everything that ImageKit can't process).
- 20MB
- 40MB
- Yes
- 
---

- Max image megapixels for processing.
- 25MP
- 100MP
- Yes

---

- Max multi-frame image megapixels for processing.
- 50MP
- 100MP
- Yes

---

- Max image transformation dimensions (dimensions greater than this in the transformation string will get ignored).
- 65535 px
- 65535 px
- No

---

- Max WebP image transformation dimensions (dimensions greater than this will not work for transformation).
- 16383 px
- 16383 px
- No

---

- Input file size for SVG images when not converting to a raster format
- 1MB
- 1MB
- No

---

- Input file size for vector formats such as PDF, EPS etc.
- 5MB
- 5MB
- No
  
{% /table %}

## Supported formats

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. TIFF images are supported as input but not as 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.

{% callout style="info" %}
For video transformation and optimization, ImageKit relies on the presence of a `.mp4` or `.mov` extension in the URL. If your resource doesn't have that extension, you can add `/ik-video.mp4` at the end. ImageKit uses it as a hint to fetch the original asset from your media library or origin and perform video transformation/optimization.

For example, if your original asset URL is \
`https://ik.imagekit.io/demo/img/video-no-extension_X9my06BI-`

You can add `/ik-video.mp4` at the end to perform video transformation and optimization i.e. \
`https://ik.imagekit.io/demo/img/video-no-extension_X9my06BI-/ik-video.mp4`
{% /callout %}

## Chained transformations

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.

```markup
                                  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:

![](<https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_1.jpg?tr=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>)

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](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_1.jpg?tr=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)

## Named transformations

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](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](https://ik.imagekit.io/ikmedia/tr:n-blur_thumbnail/default-image.jpg)

{% callout style="info" %}
You can restrict the use of unnamed transformations and only allow named transformations. This way, you can control the transformations applied to your assets. [Learn more](media-delivery-basic-security) about basic security features in ImageKit.io.
{% /callout %}

You can [create and manage named transformations](https://imagekit.io/dashboard/settings/named-transforms) within the ImageKit.io dashboard.

![Create new named transformation](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/create-named-transformation.png)

## Overlay using Layers
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.

### Syntax of layers

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.

```markup
         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
```

### Input of layer
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.

### Position of layer

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. 

| Parameter | Description                                                                                                                                                                                                                                                                 |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| lx        | `x` of the top-left corner in the base asset where the layer's top-left corner would be placed. It can also accept arithmetic expressions such as `bw_mul_0.4`, or `bw_sub_cw`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations). |
| ly        | `y` of the top-left corner in the base asset where the layer's top-left corner would be placed. It can also accept arithmetic expressions such as `bh_mul_0.4`, or `bh_sub_ch`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations). |
| lxc       | `x` of the point in the base asset where the layer's center would be placed. It can also accept arithmetic expressions such as `bw_mul_0.4`, or `bw_sub_cw`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations). |
| lyc       | `y` of the point in the base asset where the layer's center would be placed. It can also accept arithmetic expressions such as `bh_mul_0.4`, or `bh_sub_ch`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations). |
| lap       | Sets the anchor point on the base asset from which the layer offset is calculated. Possible values are `top`, `left`, `right`, `bottom`, `top_left`, `top_right`, `bottom_left`, `bottom_right`, and `center`. The default value is `top_left`. |
| lfo       | Position of the layer in relative terms e.g., `center`, `top`, `left`, `bottom`, `right`, `top_left`, `top_right`, `bottom_left`, and `bottom_right`. The default value is `center`.                                                                                        |
| lso       | Start time of the base video in seconds when the layer should appear. It accepts a positive number upto two decimal e.g. 20 or 20.50. Only applicable if parent layer or base is video. It can also accept arithmetic expressions such as `bdu_mul_0.4`, or `bdu_sub_idu`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).                                                                                     |
| ldu       | Duration in seconds during which layer should appear on the base video. It accepts a positive number upto two decimal e.g. 20 or 20.50. Only applicable if parent layer or base is video. It can also accept arithmetic expressions such as `bdu_mul_0.4`, or `bdu_sub_idu`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).                                                                                   |
| leo       | End time of the base video when this layer should disappear. In case both `leo` and `ldu` are present, `ldu` is ignored. It accepts a positive number upto two decimal e.g. 20 or 20.50. Only applicable if parent layer or base is video. It can also accept arithmetic expressions such as `bdu_mul_0.4`, or `bdu_sub_idu`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).                                 |

**Note:**
1. If one or more of `lx`, `ly`, `lxc`, or `lyc` parameters are specified along with `lfo`, then `lfo` parameter is ignored.
2. `lap` can only be used with one or more of `lx`, `ly`, `lxc`, or `lyc`
3. `lxc` cannot be used with `lx`, and `lyc` cannot be used with `ly`. However, `lxc` can be used with `ly`, and `lyc` with `lx`.

### Nesting of layers

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.

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

Learn more about overlays with detailed examples:

* Add image overlay on [images](/add-overlays-on-images#add-images-over-image) and [videos](/add-overlays-on-videos#add-images-over-video).
* Add text overlay on [images](/add-overlays-on-images#add-text-over-image) and [videos](/add-overlays-on-videos#add-text-over-video).
* Add [video overlay](/add-overlays-on-videos#add-video-over-video) on videos.
* Add solid color blocks over [images](/add-overlays-on-images#add-solid-color-blocks-over-image) and [videos](/add-overlays-on-videos#add-solid-color-blocks-over-video).
* [Nest text and image layers inside canvas](/add-overlays-on-videos#nest-text-and-image-layers-inside-canvas)
* [Add subtitles](/add-overlays-on-videos#add-subtitles-over-a-video) on videos.

### Layer modes

Layer modes control how layers blend with the base image using the `lm` parameter. By default, layers completely cover the underlying content. Four blend modes are available: **multiply** (darkening), **displacement** (distortion using a map), **cutout** (inverse transparency mask), and **cutter** (shape mask).

Syntax: `l-<type>,i-<layer_input>,lm-<mode>,<other_params>,l-end`

See [detailed examples with layer modes](/add-overlays-on-images#layer-modes) for multiply, displacement, cutout, and cutter effects.


---

# Source: /image-transformation

---
title: Image Transformation
description: Learn how to transform images using the ImageKit.io URL-based transformation parameters.
---

ImageKit lets you manipulate images on-the-fly using URL-based transformations. You can resize, crop, rotate, and apply various other transformations to images using simple URL parameters.

## Basic example

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

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

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

`https://ik.imagekit.io/ikmedia/docs_images/examples/example_fashion_1.jpg`

{% linetabs %}

{% linetab title="200px wide resized image" %}
[https://ik.imagekit.io/ikmedia/tr:`w-200`/docs_images/examples/example_fashion_1.jpg](https://ik.imagekit.io/ikmedia/tr:w-200/docs_images/examples/example_fashion_1.jpg)

![200px wide image](<https://ik.imagekit.io/ikmedia/tr:w-200/docs_images/examples/example_fashion_1.jpg>)
{% /linetab %}

{% linetab title="Avatar image" %}
[https://ik.imagekit.io/ikmedia/tr:`w-300,h-300,fo-face:r-max`/docs_images/examples/example_fashion_1.jpg](https://ik.imagekit.io/ikmedia/tr:w-300,h-300,fo-face:r-max/docs_images/examples/example_fashion_1.jpg)

![Avatar image](<https://ik.imagekit.io/ikmedia/tr:w-300,h-300,fo-face:r-max/docs_images/examples/example_fashion_1.jpg>)
{% /linetab %}

{% /linetabs %}

## Image transformation overview

Overview of different image transformations available in ImageKit.

* [Basic image resizing and cropping](/image-resize-and-crop). Learn different crop modes and AI-powered smart cropping to adapt images for different layouts.
* AI-based [object-aware](/image-resize-and-crop#object-aware-cropping---fo-object-name) and [smart cropping](/image-resize-and-crop#auto-smart-cropping---fo-auto) to generate images that focus on the main subject.
* AI-powered image generation via text prompt, background removal, drop shadow, retouching, upscaling, and other operations. [Learn more](/ai-transformations).
* Adding text and image overlays with advanced [layer modes](/transformations#layer-modes) for blend effects. [Learn more](/add-overlays-on-images).
* Image enhancements like sharpening, contrast stretching, gradient, shadow effect, and other common operations. [Learn more](/effects-and-enhancements).
* Convert GIF to videos, SVG rasterization, and other operations on vector formats like PSD, AI, EPS, and PDF files. [Learn more](/vector-and-animated-images).
* Conditional transformations. [Learn more](/conditional-transformations).

## Limits and supported image formats

Refer to [supported image formats](/transformations#supported-formats) for a list of image formats supported by ImageKit.io for transformations. Check out various [limits](/transformations#limits).

## Expensive transformation limits

By default, we do not charge for transformations when you use ImageKit.io. However, if an account extensively uses expensive transformations such as AVIF conversion, complex text or image overlays, smart crop, or other AI-related transformations, in that case, our sales team may reach out to explore alternative options. Those options include upgrading to a custom plan that fits the usage pattern, helping you bring down the unique transformation count, or even migrating off our platform if ImageKit is not the right fit for your requirements. Please note that over 99% of the customers do not face these limitations.

## Client Hints

Client hints are the hints provided by the client device to the server along with the request itself. These hints allow the server to fulfill a particular request with the most optimal resource.

Client hints provide this information via HTTP request headers. For example,

![DPR request header](https://ik.imgkit.net/demo/imagekitwebsite/tr:f-png/wp-content/uploads/dpr_request_header.jpg)

You can [learn more about client hints](https://imagekit.io/responsive-images/#chapter-7---using-client-hints) from the responsive image guide.

{% callout style="info" %}
**Enable client hints before using them** \
Not every request has these HTTP headers. You will have to explicitly tell the browser to include these client hints using a meta tag:

```html
<meta http-equiv="Accept-CH" content="Sec-CH-DPR, Sec-CH-Width">
```
{% /callout %}

ImageKit supports the following standard client hints:

* [Sec-CH-Width](https://imagekit.io/responsive-images/#sec-ch-width)
* [Sec-CH-DPR](https://imagekit.io/responsive-images/#sec-ch-dpr)
* [Save-Data](https://imagekit.io/responsive-images/#save-data)

To allow ImageKit to read values from the client hint request headers (DPR and Width), you have to set `dpr` and `width` to `auto` in transformation parameters.

For example, when the browser requests:

```
GET: https://ik.imagekit.io/your_imagekitid/tr:w-100,dpr-auto/image_name.jpg
Sec-CH-DPR: 2
```

In this case, an [extrinsic width](https://developer.mozilla.org/en-US/docs/Glossary/Intrinsic_Size#extrinsic_sizing) of 100 pixels is required. To calculate the extrinsic width of the to-be-delivered image, ImageKit reads the client hint header `Sec-CH-DPR` value and multiplies it with the specified extrinsic width. Therefore, the final actual width of the delivered image is `200`.

`100 * 2 = 200 px`

If the browser requests:

```
https://ik.imagekit.io/your_imagekitid/tr:w-auto,dpr-auto/image_name.jpg
Sec-CH-DPR: 2
Sec-CH-Width: 600
```

In this case, an [intrinsic size](https://developer.mozilla.org/en-US/docs/Glossary/Intrinsic_Size) of 600 pixels is required. The browser sends `Sec-CH-Width` request header and also considers the DPR of the user-device while calculating the value of `Sec-CH-Width` header. Therefore, ImageKit ignores the `Sec-CH-DPR` value and delivers an image of width `600`. ImageKit will return `Content-DPR` response header so that browser can scale the image correctly. 

### The Content-DPR Header

ImageKit rounds the [intrinsic size](https://developer.mozilla.org/en-US/docs/Glossary/Intrinsic_Size) of the image to the next smallest 100. If the `Sec-CH-Width`header indicates a width of 150 px, then ImageKit will deliver an image with a width of 200 px.

Now, if the DPR of the device is 2,  then the device will end up rendering an image of width 100 px (200 / 2), which is the incorrect width. The correct intended width to be displayed is 75px (150 / 2). To rectify this miscalculation due to the rounding to the next 100, the Content-DPR header is used.

Content-DPR is a response header and indicates the actual DPR of the response image. It is calculated as follows:

`Content-DPR = [Selected Image Size] / (Width / DPR)`


Let's learn this with a few examples:

```
GET: https://ik.imagekit.io/your_imagekitid/tr:w-auto,dpr-auto/image_name.jpg
Sec-CH-DPR: 2
Sec-CH-Width: 212
```

ImageKit rounds off `212` to 300, and an image of width 300 pixels is delivered. Now, the Content-DPR header is calculated as follows:

`Content-DPR = 300/ (212 / 2) = 2.83`

Hence, ImageKit responds with a `300` pixel wide image and `Content-DPR` response header with a value `2.83`

```
Content-DPR: 2.83
```

When the browser receives the image and the header, it scales it down to 300 / 2.83 = 106 px, which is the intended final width of the rendered image. If there were no `Content-DPR` header received, the browser would scale down the image as 300 / 2 = 150 px, which might break your layout.

WebP conversion using `Accept` header is enabled by default and part of the [automatic image format conversion](/image-optimization).


## Default image - (di)

When an image that is requested using ImageKit.io does not exist, a 404 error is displayed. In certain scenarios, you would want a default image to be delivered instead of the 404 error message.

ImageKit.io provides an alternative to achieve this without having to make changes at the application level using this parameter. The image specified in this parameter should be accessible using the default endpoint of your ImageKit.io account.

[https://ik.imagekit.io/ikmedia/tr:di-docs_images@@examples@@example_food_3.jpg/non_existent_image.jpg](https://ik.imagekit.io/ikmedia/tr:di-docs_images@@examples@@example_food_3.jpg/non_existent_image.jpg)

> If the default image is nested inside multiple folders, then you need to specify the entire default image path in this parameter. Replace `/` with `@@` in the default image path. For example, if the default image is accessible on `https://ik.imagekit.io/ikmedia/path/to/image.jpg`, then the `di` parameter should be `di-@@path@@to@@image.jpg`.


---

# Source: /image-resize-and-crop

---
title: Resize and crop images
description: Learn how to resize and crop images using ImageKit.io's real-time URL-based transformation API.
---

## Width - (w)

This parameter specifies the width of the output image. It accepts an integer value greater than 1. If a value between 0 and 1 is specified, it acts as a percentage width. Therefore, 0.1 means 10% of the original width, 0.4 means 40% of the original width, and so on.

You can also specify the auto value for this parameter (w-auto). Doing so will instruct ImageKit.io to read the width value from the [Sec-CH-Width](https://imagekit.io/responsive-images/#sec-ch-width) Client Hint request header. Learn more about client hints [here](/image-transformation#client-hints).

You can also provide an arithmetic expression such as `iw_div_2`, `cw_mul_0.8`, or `ih` as a value for this parameter. Doing so will first calculate the value of the expression and then apply transformations using that value. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).

{% callout style="info" %}
**Note**: If you only specify the `w` parameter, then while adjusting the width, it will automatically scale the height in order to maintain the aspect ratio.
{% /callout %}

{% linetabs %}
{% linetab title="Original image" %}
[https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg)

![Original Image](<https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg>)

{% /linetab %}

{% linetab title="200px wide" %}
[https://ik.imagekit.io/ikmedia/tr:w-200/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:w-200/docs_images/examples/example_food_3.jpg)

![200px wide](<https://ik.imagekit.io/ikmedia/tr:w-200/docs_images/examples/example_food_3.jpg>)

{% /linetab %}

{% linetab title="40% width of original image" %}
[https://ik.imagekit.io/ikmedia/tr:w-0.4/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:w-0.4/docs_images/examples/example_food_3.jpg)

![40% width of original image ](<https://ik.imagekit.io/ikmedia/tr:w-0.4/docs_images/examples/example_food_3.jpg>)

{% /linetab %}

{% linetab title="W=ih_div_2" %}
[https://ik.imagekit.io/ikmedia/tr:w-ih_div_2/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:w-ih_div_2/docs_images/examples/example_food_3.jpg)

![width equal to half of height](<https://ik.imagekit.io/ikmedia/tr:w-ih_div_2/docs_images/examples/example_food_3.jpg>)

{% /linetab %}
{% /linetabs %}

## Height - (h)

This parameter specifies the height of the output image. It accepts an integer value greater than 1. If a value between 0 and 1 is specified, the value acts as a percentage height. Therefore, 0.1 means 10% of the original height, 0.4 means 40% of the original height, and so on.

You can also provide an arithmetic expression such as `ih_div_2`, `ch_mul_0.5`, or `ih` as a value for this parameter. Doing so will first calculate the value of the expression and then apply transformations using that value. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).

{% callout style="info" %}
**Note**: If you only specify the `h` parameter, then while adjusting the height, it will automatically scale the width in order to maintain the aspect ratio.
{% /callout %}

{% linetabs %}
{% linetab title="Original image" %}
[https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg)

![Original Image](<https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg>)

{% /linetab %}

{% linetab title="200px height" %}
[https://ik.imagekit.io/ikmedia/tr:h-200/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:h-200/docs_images/examples/example_food_3.jpg)

![200px wide](<https://ik.imagekit.io/ikmedia/tr:h-200/docs_images/examples/example_food_3.jpg>)

{% /linetab %}

{% linetab title="40% height of original image" %}
[https://ik.imagekit.io/ikmedia/tr:h-0.4/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:h-0.4/docs_images/examples/example_food_3.jpg)

![40% width of Original Image ](<https://ik.imagekit.io/ikmedia/tr:h-0.4/docs_images/examples/example_food_3.jpg>)

{% /linetab %}

{% linetab title="H=ih_div_2" %}
[https://ik.imagekit.io/ikmedia/tr:h-iw_div_2/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:h-iw_div_2/docs_images/examples/example_food_3.jpg)

![height equal to half of width](<https://ik.imagekit.io/ikmedia/tr:h-iw_div_2/docs_images/examples/example_food_3.jpg>)

{% /linetab %}
{% /linetabs %}


## Aspect ratio - (ar)

Used to specify the aspect ratio of the output image or the ratio of width to height of the output image. This parameter must be used along with either the [height(h)](#height---h) or [width(w)](#width---w) parameter. The format for specifying this transformation is `ar-<width>-<height>`.

You can also provide an arithmetic expression such as `iar_div_2` or `car_mul_0.75` as a value for this parameter. Doing so will first calculate the value of the expression and then apply transformations using that value. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).

{% callout style="info" %}
**Note**: If you specify both height(h) and width(w) in the URL along with the aspect ratio(ar), then the aspect ratio is ignored.
{% /callout %}

{% linetabs %}
{% linetab title="Original image" %}
[https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg)

![Original Image](<https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg>)

{% /linetab %}

{% linetab title="Width 400px and aspect ratio 4:3" %}
[https://ik.imagekit.io/ikmedia/tr:ar-4-3,w-400/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:ar-4-3,w-400/docs_images/examples/example_food_3.jpg)

![200px wide](<https://ik.imagekit.io/ikmedia/tr:ar-4-3,w-400/docs_images/examples/example_food_3.jpg>)

{% /linetab %}
{% linetab title="Width 400px and aspect ratio double" %}
[https://ik.imagekit.io/ikmedia/tr:ar-iar_mul_2,w-400/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:ar-iar_mul_2,w-400/docs_images/examples/example_food_3.jpg)

![200px wide](<https://ik.imagekit.io/ikmedia/tr:ar-iar_mul_2,w-400/docs_images/examples/example_food_3.jpg>)

{% /linetab %}
{% /linetabs %}

## Crop, Crop modes & Focus

If only one of the height(h) or width(w) dimensions is specified, ImageKit.io adjusts the other dimension accordingly to preserve the aspect ratio, and no cropping takes place.

But when you specify both [height(h)](#height---h) and [width(w)](#width---w) dimensions, you need to choose the right cropping strategy based on your website layout and desired output image.

### Choosing the right cropping strategy

* If you want to preserve the whole image content (no cropping) and need the exact same dimensions (height and width) in the output image as requested, choose either the [pad resize crop](#pad-resize-crop-strategy---cm-pad_resize) or [forced crop](#forced-crop-strategy---c-force) strategy. If you want the same behavior as `pad_resize` but want to avoid upscaling images when requested dimensions are larger than the original (keeping them at their original size with padding added to fill the requested dimensions), use the [pad resize crop (no enlarge)](#pad-resize-crop-strategy-no-enlarge---cm-pad_resize_no_enlarge) strategy.

* If you want to preserve the whole image content (no cropping), but it is okay if one or both the dimensions (height or width) in the output image are adjusted to preserve the aspect ratio. Then choose either of the [max-size cropping](#max-size-cropping-strategy---c-at_max) or [min-size cropping](#min-size-cropping-strategy---c-at_least) strategy. You can also use the [max-size-enlarge cropping](#max-size-enlarge-cropping-strategy---c-at_max_enlarge) strategy if you want to allow enlarging of the image in case the requested dimensions are more than the original image dimension.

* If you need the exact same dimensions (height and width) in the output image as requested but it's okay to crop the image to preserve the aspect ratio (or extract a region from the original image), choose either the [maintain ratio crop](#maintain-ratio-crop-strategy---c-maintain_ratio), [extract crop](#extract-crop-strategy---cm-extract), or [pad extract crop](#pad-extract-crop-strategy---cm-pad_extract) strategy. If you want the same behavior as `maintain_ratio` but want to avoid upscaling images (returning them as-is when they are smaller than the requested dimensions), use the [maintain ratio crop (no enlarge)](#maintain-ratio-crop-strategy-no-enlarge---c-maintain_ratio_no_enlarge) strategy. You can combine the extract crop strategy with different focus values to get the desired result.

* If you never want to crop or downscale the image, and want to only add padding around it when the requested dimensions are larger than the original, use the [pad extract crop (no shrink)](#pad-extract-crop-strategy-no-shrink---cm-pad_extract_no_shrink) strategy. When the requested size is larger than the original, padding is added around the image to fill the dimensions. When the requested size is smaller, the original image is returned as-is.

{% callout style="info" %}
**Note:** When choosing among different strategies for cropping, think in terms of your website layout and desired output image.
{% /callout %}


## Pad resize crop strategy - (cm-pad_resize)

In the pad resize crop strategy, the output image's dimensions (height and width) are the same as requested, no cropping takes place, and the aspect ratio is preserved. This is accomplished by adding padding around the output image to match the exact dimension as requested.

{% linetabs %}
{% linetab title="Original image" %}
[https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg)

![Original Image](<https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg>)

{% /linetab %}

{% linetab title="cm-pad_resize" %}
[https://ik.imagekit.io/ikmedia/tr:w-300,h-200,cm-pad_resize,bg-F3F3F3/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:w-300,h-200,cm-pad_resize,bg-F3F3F3/docs_images/examples/example_food_3.jpg)

The output image is exactly 300x200. However, to maintain the aspect ratio and prevent cropping, a solid colored padding is added around the resized image.

![cm-pad_resize](<https://ik.imagekit.io/ikmedia/tr:w-300,h-200,cm-pad_resize,bg-F3F3F3/docs_images/examples/example_food_3.jpg>)

For the sake of clarity, we have made the padding background grey in color (`#F3F3F3`) using the [background parameter (`bg`)](/effects-and-enhancements#background---bg) in the URL.
{% /linetab %}
{% /linetabs %}

### Example - All padding on one side

In the examples above, we saw that when the image is padded using the pad resize crop strategy, the padding is equal on both sides of the image. However, there might be cases where we want all the padding to be added on only one side of the image. This can be done using the focus (fo) parameter.

{% linetabs %}
{% linetab title="Padding to the right " %}
[https://ik.imagekit.io/ikmedia/tr:w-300,h-200,cm-pad_resize,bg-F3F3F3,fo-left/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:w-300,h-200,cm-pad_resize,bg-F3F3F3,fo-left/docs_images/examples/example_food_3.jpg)

We added the `fo-left` transformation to our image. Now, all the padding is on the right of the image, while the image itself is on the left (determined by the value of [focus(fo)](#focus---fo) parameter).

![Padding to the right](<https://ik.imagekit.io/ikmedia/tr:w-300,h-200,cm-pad_resize,bg-F3F3F3,fo-left/docs_images/examples/example_food_3.jpg>)

{% /linetab %}

{% linetab title="Padding to the bottom" %}
[https://ik.imagekit.io/ikmedia/tr:w-100,h-200,cm-pad_resize,bg-F3F3F3,fo-top/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:w-100,h-200,cm-pad_resize,bg-F3F3F3,fo-top/docs_images/examples/example_food_3.jpg)

We added the `fo-top` transformation to our image. Now, all the padding is on the bottom of the image, while the image itself is on the top (determined by the value of the [focus (fo)](#focus---fo) parameter).

![Padding to the bottom](<https://ik.imagekit.io/ikmedia/tr:w-100,h-200,cm-pad_resize,bg-F3F3F3,fo-top/docs_images/examples/example_food_3.jpg>)

{% /linetab %}
{% /linetabs %}

## Pad resize crop strategy (no enlarge) - (cm-pad_resize_no_enlarge)

This strategy works the same as the [pad resize crop strategy](#pad-resize-crop-strategy---cm-pad_resize), but it never upscales the image. If the original image is smaller than the requested dimensions, the image is not scaled up — instead, padding is added around the original-sized image to reach the requested canvas size. If the original image is larger than the requested dimensions, it is scaled down to fit, just like `cm-pad_resize`.

This is useful when you want to apply padding like a border or frame around the image without upscaling small images.

{% callout style="info" %}
**Note:** This crop strategy is only supported for images.
{% /callout %}

{% linetabs %}
{% linetab title="Original image" %}
[https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg)

![Original Image](<https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg>)

{% /linetab %}

{% linetab title="cm-pad_resize_no_enlarge" %}
[https://ik.imagekit.io/ikmedia/tr:w-800,h-800,cm-pad_resize_no_enlarge,bg-F3F3F3/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:w-800,h-800,cm-pad_resize_no_enlarge,bg-F3F3F3/docs_images/examples/example_food_3.jpg)

The original image is smaller than the requested 800x800 dimensions, so it is not upscaled. Instead, padding is added around the original-sized image to fill the 800x800 canvas.

![cm-pad_resize_no_enlarge](<https://ik.imagekit.io/ikmedia/tr:w-800,h-800,cm-pad_resize_no_enlarge,bg-F3F3F3/docs_images/examples/example_food_3.jpg>)

For the sake of clarity, we have made the padding background grey in color (`#F3F3F3`) using the [background parameter (`bg`)](/effects-and-enhancements#background---bg) in the URL.
{% /linetab %}
{% /linetabs %}

## Forced crop strategy - (c-force)

In a forced crop strategy, the output image's dimension (height and width) is exactly the same as requested. No cropping takes place, but the aspect ratio is not preserved. It forcefully squeezes the original image to fit it completely within the output dimensions.

{% linetabs %}
{% linetab title="Original image" %}
[https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg)

![Original Image](<https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg>)

{% /linetab %}

{% linetab title="c-force" %}
[https://ik.imagekit.io/ikmedia/tr:w-300,h-200,c-force/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:w-300,h-200,c-force/docs_images/examples/example_food_3.jpg)

![c-force](<https://ik.imagekit.io/ikmedia/tr:w-300,h-200,c-force/docs_images/examples/example_food_3.jpg>)

The entire original image is preserved in the output image as well, but the image has been squeezed to fit into the output image.

{% /linetab %}
{% /linetabs %}

## Max-size cropping strategy - (c-at_max)

In the max-size crop strategy, the whole image content is preserved (no cropping), and the aspect ratio is preserved, but one of the dimensions (height or width) is adjusted.

The output image is less than or equal to the dimensions specified in the URL,i.e., at least one dimension will exactly match the output dimension requested, and the other dimension will be equal to or smaller than the corresponding output dimension requested.

{% linetabs %}
{% linetab title="Original image" %}
[https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg)

![Original Image](<https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg>)

{% /linetab %}

{% linetab title="c-at_max" %}
[https://ik.imagekit.io/ikmedia/tr:w-300,h-200,c-at_max/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:w-300,h-200,c-at_max/docs_images/examples/example_food_3.jpg)

![c-at_max](<https://ik.imagekit.io/ikmedia/tr:w-300,h-200,c-at_max/docs_images/examples/example_food_3.jpg>)

The entire image content and the aspect ratio are preserved. The output image dimensions are 200x200. So, the height is exactly what is requested, but the width is smaller than what was requested.

{% /linetab %}
{% /linetabs %}

{% callout style="info" %}
**Note:** 
* This mode is particularly useful if you have a container and you want to ensure that the image will never be larger than that container.
* If the requested dimension is more than the original dimension of the image, then the original image is returned without cropping. To enlarge the images more than the original dimensions, check [max-size-enlarge cropping](#max-size-enlarge-cropping-strategy---c-at_max_enlarge) strategy.
{% /callout %}


## Max-size-enlarge cropping strategy - (c-at_max_enlarge)

This strategy is similar to the [max-size cropping](#max-size-cropping-strategy---c-at_max) strategy, except it also allows an image to be enlarged beyond its original dimensions.

The output image is less than or equal to the dimensions specified in the URL,i.e., at least one dimension will exactly match the output dimension requested, and the other dimension will be equal to or smaller than the corresponding output dimension requested.

{% linetabs %}
{% linetab title="Original image" %}
[https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg)

![Original Image](<https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg>)

{% /linetab %}

{% linetab title="c-at_max_enlarge" %}
[https://ik.imagekit.io/ikmedia/tr:w-850,h-1000,c-at_max_enlarge/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:w-850,h-1000,c-at_max_enlarge/docs_images/examples/example_food_3.jpg)

![c-at_max_enlarge](<https://ik.imagekit.io/ikmedia/tr:w-850,h-1000,c-at_max_enlarge/docs_images/examples/example_food_3.jpg>)

The entire image content and the aspect ratio are preserved. The output image dimensions are 740x1000. So, the height is exactly what is requested, but the width is smaller than what was requested.

{% /linetab %}
{% /linetabs %}

## Min-size cropping strategy - (c-at_least)

This strategy is similar to the [max-size cropping](#max-size-cropping-strategy---c-at_max) strategy, with the only difference being that, unlike the max-size strategy, the image is equal to or larger than the requested dimensions. 

One of the dimensions will be exactly the same as what is requested, while the other dimension will be equal to or larger than what is requested.

{% linetabs %}
{% linetab title="Original image" %}
[https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg)

![Original Image](<https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg>)

{% /linetab %}

{% linetab title="c-at_least" %}
[https://ik.imagekit.io/ikmedia/tr:w-300,h-200,c-at_least/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:w-300,h-200,c-at_least/docs_images/examples/example_food_3.jpg)

![c-at_least](<https://ik.imagekit.io/ikmedia/tr:w-300,h-200,c-at_least/docs_images/examples/example_food_3.jpg>)

The entire image content and aspect ratio are preserved. The output image dimensions are 300x300. So, the width is exactly the same as what was requested, but the height is larger than what was requested.

{% /linetab %}
{% /linetabs %}

{% callout style="info" %}
**Note:** This is useful for cases where you want to have an image that is always at least as large as the container.
{% /callout %}

## Maintain ratio crop strategy - (c-maintain_ratio)

This is the default crop strategy. If nothing is specified in the URL, this strategy gets applied automatically. 

In this strategy, the output image's dimension (height and width) is the same as requested, and the aspect ratio is preserved. This is accomplished by resizing the image to the requested dimension and in the process cropping parts from the original image.

{% callout style="info" %}
**Note:** By default, ImageKit.io extracts the image from the center, but you can change this using the [focus](#focus---fo) parameter.
{% /callout %}

{% linetabs %}
{% linetab title="Original image" %}
[https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg)

![Original Image](<https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg>)

{% /linetab %}

{% linetab title="c-maintain_ratio(Center crop)" %}
[https://ik.imagekit.io/ikmedia/tr:w-300,h-200,c-maintain_ratio/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:w-300,h-200,c-maintain_ratio/docs_images/examples/example_food_3.jpg) or [https://ik.imagekit.io/ikmedia/tr:w-300,h-200/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:w-300,h-200/docs_images/examples/example_food_3.jpg)

![c-maintain_ratio(Center crop)](<https://ik.imagekit.io/ikmedia/tr:w-300,h-200/docs_images/examples/example_food_3.jpg>)

In the above image, the top and the bottom of the image got cropped out. But the aspect ratio has been preserved from the original to the output image.

{% /linetab %}

{% linetab title="c-maintain_ratio with fo-custom" %}
Original Image URL - [https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg)

![Original Image](<https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg>)

Using c-maintain_ratio with fo-custom - [https://ik.imagekit.io/ikmedia/tr:w-500,h-100,fo-custom/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:w-500,h-100,fo-custom/docs_images/examples/example_food_3.jpg)

![c-maintain_ratio with fo-custom](<https://ik.imagekit.io/ikmedia/tr:w-500,h-100,fo-custom/docs_images/examples/example_food_3.jpg>)

{% /linetab %}
{% /linetabs %}

### Examples - Object-aware cropping (maintain-ratio)

We can also provide an object-specific focus to crop the image, ensuring that the object is centered while cropping out the less important parts of the image. This focus mode can be combined with the `zoom` transformation to control how much to zoom in/out while cropping. Read more about it [here](#with-and-default-crop-mode-c-maintain_ratio).

{% linetabs %}
{% linetab title="Original" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg)

![Original 1920x1280 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg)
{% /linetab %}

{% linetab title="c-maintain_ratio (regular cropping)" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=w-400,h-400](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=w-400,h-400)

![400x400 default crop image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=w-400,h-400)
{% /linetab %}

{% linetab title="Smart crop (fo-car)" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=w-400,h-400,fo-car](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=w-400,h-400,fo-car)

![400x400 smart cropped image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=w-400,h-400,fo-car)

In the above image, rather than cropping equally from both the left and right, only the left portion was cropped to ensure the object in focus is centered. Learn more about object-aware cropping [here](#object-aware-cropping---fo-object-name).
{% /linetab %}
{% /linetabs %}

You may also provide a list of objects to the `fo` parameter if you are unsure about the exact object type. Read more about it [here](#providing-multiple-object---fo--).

## Cropping using coordinates (maintain-ratio)

In addition to using relative focus options like `fo-top` or `fo-left`, you can specify exact coordinates to control the cropped area with the `c-maintain_ratio` strategy. This gives you precise control over which part of the image is preserved.

You can use `x` and `y` to define the top-left corner of the crop, or `xc` and `yc` to define the center of the crop. These coordinates are applied after the image is resized to fit the larger of the requested dimensions, but before the final crop.

{% linetabs %}
{% linetab title="Original image" %}
[https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg)

![Original Image](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg)

{% /linetab %}

{% linetab title="Focus using x, y coordinates" %}
URL - [https://ik.imagekit.io/ikmedia/tr:w-300,h-200,x-0,y-100/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:w-300,h-200,x-0,y-100/docs_images/examples/example_food_3.jpg)

The original image (600x600) is first resized to 300x300 to match the requested width while maintaining the original aspect ratio. Then, a 300x200 area is cropped from the coordinates (0, 100) of the resized image, creating a 50px offset from the top.

![c-maintain_ratio with x,y coordinates](https://ik.imagekit.io/ikmedia/tr:w-300,h-200,x-0,y-100/docs_images/examples/example_food_3.jpg)

{% /linetab %}

{% linetab title="Focus using center coordinates xc" %}
URL - [https://ik.imagekit.io/ikmedia/tr:w-200,h-400,xc-200,yc-0/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:w-200,h-400,xc-200,yc-0/docs_images/examples/example_food_3.jpg)

The original image (600x600) is first resized to 400x400 to match the requested height while maintaining the original aspect ratio. Then, a 200x400 area is cropped centered at the coordinates (200, 0) of the resized image.

![c-maintain_ratio with xc,yc coordinates](https://ik.imagekit.io/ikmedia/tr:w-200,h-400,xc-200,yc-0/docs_images/examples/example_food_3.jpg)

{% /linetab %}
{% /linetabs %}

## Maintain ratio crop strategy (no enlarge) - (c-maintain_ratio_no_enlarge)

This strategy works the same as the [maintain ratio crop strategy](#maintain-ratio-crop-strategy---c-maintain_ratio), but it never upscales the image. If the original image is smaller than the requested dimensions, it is returned as-is without any resizing. If the original image is larger than the requested dimensions, it is scaled down to fill the requested dimensions while preserving the aspect ratio, and the excess dimension is cropped — just like `c-maintain_ratio`.

This is useful when you want to fill a container with the image but never upscale small images.

{% callout style="info" %}
**Note:** This crop strategy is only supported for images.
{% /callout %}

{% linetabs %}
{% linetab title="Original image" %}
[https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg)

![Original Image](<https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg>)

{% /linetab %}

{% linetab title="c-maintain_ratio_no_enlarge (image larger than target)" %}
[https://ik.imagekit.io/ikmedia/tr:w-300,h-200,c-maintain_ratio_no_enlarge/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:w-300,h-200,c-maintain_ratio_no_enlarge/docs_images/examples/example_food_3.jpg)

The original image is larger than the requested 300x200 dimensions, so it is scaled down to fill the requested dimensions while maintaining the aspect ratio, and the excess is cropped — same as `c-maintain_ratio`.

![c-maintain_ratio_no_enlarge](<https://ik.imagekit.io/ikmedia/tr:w-300,h-200,c-maintain_ratio_no_enlarge/docs_images/examples/example_food_3.jpg>)

{% /linetab %}

{% linetab title="c-maintain_ratio_no_enlarge (image smaller than target)" %}
[https://ik.imagekit.io/ikmedia/tr:w-800,h-800,c-maintain_ratio_no_enlarge/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:w-800,h-800,c-maintain_ratio_no_enlarge/docs_images/examples/example_food_3.jpg)

The original image is smaller than the requested 800x800 dimensions, so it is returned as-is without any upscaling.

![c-maintain_ratio_no_enlarge (no upscale)](<https://ik.imagekit.io/ikmedia/tr:w-800,h-800,c-maintain_ratio_no_enlarge/docs_images/examples/example_food_3.jpg>)

{% /linetab %}
{% /linetabs %}

## Extract crop strategy - (cm-extract)

In this strategy, the output image's dimension (height and width) is exactly the same as requested, and the aspect ratio is preserved. 

Instead of trying to resize the image as we did in the maintain ratio strategy, we extract out a region of the requested dimension from the original image.

{% callout style="info" %}
**Note:** By default, ImageKit.io extracts the image from the center, but you can change this using the [focus](#focus---fo) parameter.
{% /callout %}

### Example - Center and relative focus

{% linetabs %}
{% linetab title="Original image" %}
[https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg)

![Original Image](<https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg>)

{% /linetab %}

{% linetab title="cm-extract(Default center extract)" %}
[https://ik.imagekit.io/ikmedia/tr:w-200,h-200,cm-extract/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:w-200,h-200,cm-extract/docs_images/examples/example_food_3.jpg)

![cm-extract(Default center extract)](<https://ik.imagekit.io/ikmedia/tr:w-200,h-200,cm-extract/docs_images/examples/example_food_3.jpg>)

The size of the image content has not changed at all from the original image, which means that no resizing has taken place. Instead, we have been able to extract out a 200x200 area from the original image. This is the regular center extract.

{% /linetab %}

{% linetab title="Relative focus" %}
In the relative method, you can use the focus (fo) parameter to specify that the extract should be done from, let's say, the bottom-right of the original image.

Valid relative values for fo parameters are - `center`, `top`, `left`, `bottom`, `right`, `top_left`, `top_right`, `bottom_left` and `bottom_right`.

Example URL - [https://ik.imagekit.io/ikmedia/tr:w-300,h-300,cm-extract,fo-bottom_right/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:w-300,h-300,cm-extract,fo-bottom_right/docs_images/examples/example_food_3.jpg)

This is the extract done with focus on the bottom right of the original image.

![focus](<https://ik.imagekit.io/ikmedia/tr:w-300,h-300,cm-extract,fo-bottom_right/docs_images/examples/example_food_3.jpg>)

{% /linetab %}
{% /linetabs %}

### Example - Focus using cropped image coordinates

{% linetabs %}
{% linetab title="Focus using X, Y Coordinates" %}
In the coordinate method of focus, we use the parameters x and y to determine the position of the top-left corner from where the extract would begin.

You can also provide arithmetic expressions such as iw_mul_0.4 or ih_mul_0.4 as values for these parameters. This will first calculate the value of the expression and then use those values for extraction. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).

Example URL - [https://ik.imagekit.io/ikmedia/tr:w-300,h-300,cm-extract,x-100,y-300/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:w-300,h-300,cm-extract,x-100,y-300/docs_images/examples/example_food_3.jpg)

The extract is made starting from (100,300) point on the original image.

![extract](<https://ik.imagekit.io/ikmedia/tr:w-300,h-300,cm-extract,x-100,y-300/docs_images/examples/example_food_3.jpg>)

{% /linetab %}

{% linetab title="Focus using center coordinates xc, yc" %}

In the center coordinate method of focus, we use the parameters `xc` and `yc` to determine the position of the center of the image that would be extracted.

You can also provide arithmetic expressions such as `iw_div_3` or `ih_div_2` as values for these parameters. This will first calculate the value of the expression and then use those values for extraction. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).

Example URL - [https://ik.imagekit.io/ikmedia/tr:w-300,h-300,cm-extract,xc-300,yc-400/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:w-300,h-300,cm-extract,xc-300,yc-400/docs_images/examples/example_food_3.jpg)

The extract is made centered on (300, 500) points on the original image.

![extract](<https://ik.imagekit.io/ikmedia/tr:w-300,h-300,cm-extract,xc-300,yc-400/docs_images/examples/example_food_3.jpg>)

This crop mode is really useful when you want to crop the image on the basis of the focal point of your resultant image.

An important point to note about the center coordinate crop mode is that if either the height or width dimension of the cropped image as per the given center coordinates goes beyond the bounds of the original image, the crop will fail.

So, we suggest ensuring that you are using the correct height and width dimensions when cropping images using center coordinates.

{% /linetab %}
{% /linetabs %}

### Examples - Object-aware cropping (cm-extract)

Instead of specifying the `x`, `y`, `xc` or `yc` coordinates to focus on a particular area, you can also set the `fo` value to an object from the [supported list](#supported-object-list), which will intelligently detect `xc` and `yc` values as the center of the provided object and extract the image with the given width and height. Learn more about object-aware cropping [here](#object-aware-cropping---fo-object-name). This focus mode can be combined with the `zoom` transformation to control how much to zoom in/out while cropping. Read more about it [here](#with-and-cm-extract).

{% linetabs %}
{% linetab title="Original" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg)

![Original 1920x1280 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg)
{% /linetab %}

{% linetab title="cm-extract (smart crop extract)" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=w-600,h-400,fo-car,cm-extract](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=w-600,h-400,fo-car,cm-extract)

![600x400 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=w-600,h-400,fo-car,cm-extract)

Here, we have intelligently detected the `xc`and `yc` values as the central coordinates of the car and then extracted out an area of 600x400 from that center.
{% /linetab %}
{% /linetabs %}

You may also provide a list of objects to the `fo` parameter if you are unsure about the exact object type. Read more about it [here](#providing-multiple-object---fo--).

### Example - Focus using custom coordinates

Instead of specifying the `x`, `y`, `xc` or `xy` coordinates to focus on a particular area, you can also specify the focus area in an image while uploading the image or from the media library and then use fo-custom transformation in the image URL. ImageKit will then utilize the custom crop area specified with the image for all crop operations. This custom focus mode works for both the [extract crop](#extract-crop-strategy---cm-extract) and the default [maintain ratio crop](#maintain-ratio-crop-strategy---c-maintain_ratio) strategy.

{% linetabs %}
{% linetab title="Original image" %}
[https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg)

![Original Image](<https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg>)

{% /linetab %}

{% linetab title="Focus using custom coordinates" %}
[https://ik.imagekit.io/ikmedia/tr:w-500,h-100,cm-extract,fo-custom/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:w-500,h-100,cm-extract,fo-custom/docs_images/examples/example_food_3.jpg)

A 500x100px thumbnail with cm-extract crop strategy and fo-custom.

![cm-extract with fo-custom](<https://ik.imagekit.io/ikmedia/tr:w-500,h-100,cm-extract,fo-custom/docs_images/examples/example_food_3.jpg>)

{% /linetab %}
{% /linetabs %}

### Unexpected behavior with auto rotation

ImageKit.io can be configured to auto-rotate images based on the `Orientation` value in the image metadata. This could result in unexpected behavior when using `cm-extract`. In that case, you will have to adjust the values of `x` and `y` to accommodate for the oriented image.

## Pad extract crop strategy - (cm-pad_extract)

The pad extract crop strategy is an extension of the [extract crop](#extract-crop-strategy---cm-extract) strategy. In the extract crop strategy, we were extracting out a smaller area from a larger image. Now, there can be a scenario where the original image is small and we want to extract out a larger area (which is practically not possible without padding). So, the pad extract mode adds a solid colored padding around the image to match the exact size requested.

This transformation is specified using the value `cm-pad_extract` transformation parameter in the URL.

{% linetabs %}
{% linetab title="Original image" %}
[https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg)

![Original Image](<https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg>)

{% /linetab %}

{% linetab title="cm-pad_extract" %}
[https://ik.imagekit.io/ikmedia/tr:w-800,h-800,cm-pad_extract,bg-F3F3F3/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:w-800,h-800,cm-pad_extract,bg-F3F3F3/docs_images/examples/example_food_3.jpg)

The original image was 600x600, but this image is an 800x800 image.

![cm-pad_extract](<https://ik.imagekit.io/ikmedia/tr:w-800,h-800,cm-pad_extract,bg-F3F3F3/docs_images/examples/example_food_3.jpg>)

{% /linetab %}
{% /linetabs %}

## Pad extract crop strategy (no shrink) - (cm-pad_extract_no_shrink)

This strategy is similar to the [pad extract crop strategy](#pad-extract-crop-strategy---cm-pad_extract), but it never downscales or extracts the image. If the requested dimensions are larger than the original image, padding is added to fill the canvas to the requested size. If the requested dimensions are smaller than the original image, the original image is returned as-is — no downscaling or extraction takes place.

This is useful when you want to ensure an image always fills a minimum canvas size, adding padding only if necessary.

{% callout style="info" %}
**Note:** This crop strategy is only supported for images.
{% /callout %}

{% linetabs %}
{% linetab title="Original image" %}
[https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg)

![Original Image](<https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg>)

{% /linetab %}

{% linetab title="cm-pad_extract_no_shrink (target larger than original)" %}
[https://ik.imagekit.io/ikmedia/tr:w-800,h-800,cm-pad_extract_no_shrink,bg-F3F3F3/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:w-800,h-800,cm-pad_extract_no_shrink,bg-F3F3F3/docs_images/examples/example_food_3.jpg)

The requested dimensions (800x800) are larger than the original image, so padding is added around the original image to reach the requested canvas size.

![cm-pad_extract_no_shrink](<https://ik.imagekit.io/ikmedia/tr:w-800,h-800,cm-pad_extract_no_shrink,bg-F3F3F3/docs_images/examples/example_food_3.jpg>)

For the sake of clarity, we have made the padding background grey in color (`#F3F3F3`) using the [background parameter (`bg`)](/effects-and-enhancements#background---bg) in the URL.
{% /linetab %}

{% linetab title="cm-pad_extract_no_shrink (target smaller than original)" %}
[https://ik.imagekit.io/ikmedia/tr:w-300,h-200,cm-pad_extract_no_shrink/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:w-300,h-200,cm-pad_extract_no_shrink/docs_images/examples/example_food_3.jpg)

The requested dimensions (300x200) are smaller than the original image, so the original image is returned as-is without any downscaling or extraction.

![cm-pad_extract_no_shrink (no shrink)](<https://ik.imagekit.io/ikmedia/tr:w-300,h-200,cm-pad_extract_no_shrink/docs_images/examples/example_food_3.jpg>)

{% /linetab %}
{% /linetabs %}

## Focus - (fo)

This parameter can be used along with [pad resize](#pad-resize-crop-strategy---cm-pad_resize), [maintain ratio](#maintain-ratio-crop-strategy---c-maintain_ratio), or [extract crop](#extract-crop-strategy---cm-extract) to change the behavior of padding or cropping. Learn more from the different examples shown in respective sections.

This parameter can have the following values depending on where it is being used:

1. `left`, `right`, `top`, `bottom` can be to control the position of padding when used with pad resize. Learn from [examples](#example---all-padding-on-one-side).

2. `fo-custom` can be used to define a specific focus area when used with [maintain ratio](#maintain-ratio-crop-strategy---c-maintain_ratio) and [extract crop](#extract-crop-strategy---cm-extract).

3. `center`, `top`, `left`, `bottom`, `right`, `top_left`, `top_right`, `bottom_left` and `bottom_right` can be used to define relative cropping during extract crop. Learn from [examples](#example---center-and-relative-focus).

Apart from the above, the fo parameter also has additional options that intelligently detect the most important part of an image to create thumbnails, i.e., `auto` and `face`. Let's see them in action:

## Auto smart cropping - (fo-auto)

In this mode, ImageKit.io automatically determines the most important part of the image and preserves it in the output thumbnail. This is enabled by passing the `fo-auto` parameter in the URL transformation parameters.

{% linetabs %}
{% linetab title="Original image" %}
[https://ik.imagekit.io/ikmedia/docs_images/examples/Smart_crop_example.jpg](https://ik.imagekit.io/ikmedia/docs_images/examples/Smart_crop_example.jpg)

For example, in the image below, the child is the main subject, and he is slightly towards the right from the center of the image.

![Original Image](<https://ik.imagekit.io/ikmedia/docs_images/examples/Smart_crop_example.jpg>)

{% /linetab %}

{% linetab title="Regular cropping" %}
[https://ik.imagekit.io/ikmedia/tr:w-200,h-300/docs_images/examples/Smart_crop_example.jpg](https://ik.imagekit.io/ikmedia/tr:w-200,h-300/docs_images/examples/Smart_crop_example.jpg)

If we use regular resize and the default crop strategy, we get the following result, where the main subject is off the center. This is definitely not a great thumb image to have.

![Regular Cropping](<https://ik.imagekit.io/ikmedia/tr:w-200,h-300/docs_images/examples/Smart_crop_example.jpg>)

{% /linetab %}

{% linetab title="Smart crop (fo-auto)" %}
[https://ik.imagekit.io/ikmedia/tr:w-200,h-300,fo-auto/docs_images/examples/Smart_crop_example.jpg](https://ik.imagekit.io/ikmedia/tr:w-200,h-300,fo-auto/docs_images/examples/Smart_crop_example.jpg)

With smart crop auto mode, this is what the final result looks like. The main subject is right in the center of the final thumbnail.

![Smart crop (fo-auto)](<https://ik.imagekit.io/ikmedia/tr:w-200,h-300,fo-auto/docs_images/examples/Smart_crop_example.jpg>)

{% /linetab %}
{% /linetabs %}

## Face cropping - (fo-face)

In face crop, the crop works more like the extract crop strategy, but instead of focusing on the center of the image, it finds out the face (or multiple faces) in the image and focuses around that. 

This gives you perfect thumbnails with just the subject's face that make up for good profile pictures.

This mode is enabled using the `'fo-face'` parameter in the URL transformation parameters.

{% linetabs %}
{% linetab title="Original image" %}
[https://ik.imagekit.io/ikmedia/docs_images/examples/example_portrait_1.jpg](https://ik.imagekit.io/ikmedia/docs_images/examples/example_portrait_1.jpg)

![Original Image](<https://ik.imagekit.io/ikmedia/docs_images/examples/example_portrait_1.jpg>)

{% /linetab %}

{% linetab title="Face crop (fo-face)" %}
[https://ik.imagekit.io/ikmedia/tr:w-150,h-150,fo-face/docs_images/examples/example_portrait_1.jpg](https://ik.imagekit.io/ikmedia/tr:w-150,h-150,fo-face/docs_images/examples/example_portrait_1.jpg?updatedAt=1703135626910)

![Face crop (fo-face)](<https://ik.imagekit.io/ikmedia/tr:w-150,h-150,fo-face/docs_images/examples/example_portrait_1.jpg?updatedAt=1703135626910>)

{% /linetab %}
{% /linetabs %}

{% callout style="info" %}
**Note:** Smart crop may not give accurate results for some images. There is a trade-off between speed (needed for real-time transformations) and accuracy.
{% /callout %}

## Object-aware cropping - (fo-object name)

To automatically provide high focus to a particular object while cropping, you can set the `fo` value to an object from the [supported list](#supported-object-list). This allows for intelligent cropping of the image based on the specific objects detected within it.

It can be used along with [maintain ratio](#examples---object-aware-cropping-maintain-ratio) or [extract crop](#examples---object-aware-cropping-cm-extract) to intelligently crop or extract parts of the image as needed. Learn more from the different examples shown in respective sections.

We can also choose not to provide dimensions and deliver an image that is tightly cropped to the object.

### Tightly crop object

To deliver an image that is tightly cropped to the object, provide `fo-<object name>` without specifying `height` and `width` dimensions. This will return an image that contains only the given object.


We can also specify `aspect ratio` along with the `fo-<object name>` focus option without providing `height` and `width`. This keeps the object in focus but may include more of the image to fit the specified `aspect ratio`.

It can also accept a `zoom` parameter to include more background or reduce it, as explained [here](#with-tightly-cropped-object).

{% linetabs %}
{% linetab title="Original" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg)

![Original 1920x1280 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg)
{% /linetab %}

{% linetab title="Tightly cropped image" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-car](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-car)

![982x301 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-car)

The output is an image containing just the car.
{% /linetab %}

{% linetab title="Tightly cropped image with aspect ratio" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-car,ar-2_1](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-car,ar-2_1)

![982x491 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-car,ar-2_1)

The output is an image containing only the car, plus the additional `height` needed to maintain an `aspect ratio` of 2.
{% /linetab %}
{% /linetabs %}

We can also crop out a particular object of interest out of multiple different objects present in an image.

{% linetabs %}
{% linetab title="Original" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg)

![Original 600x336 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg)
{% /linetab %}

{% linetab title="Cropping dog" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg?tr=fo-dog](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg?tr=fo-dog)

![292x322 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg?tr=fo-dog)

The output is an image containing just the dog.
{% /linetab %}

{% linetab title="Cropping cat" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg?tr=fo-cat](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg?tr=fo-cat)

![119x169 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg?tr=fo-cat)

The output is an image containing just the cat.
{% /linetab %}

{% linetab title="Cropping dog with aspect ratio" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg?tr=fo-dog,ar-1_1](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg?tr=fo-dog,ar-1_1)

![322x322 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg?tr=fo-dog,ar-1_1)

The output is a square image containing the dog by adding extra `width` as required.
{% /linetab %}
{% /linetabs %}

### Providing multiple object - (fo-`<Object1>_<Object2>`)

You can also provide multiple objects from a [list](#supported-object-list) of supported objects to the `fo` parameter. The image will be cropped according to the position of the first object found. It can be helpful when the exact object type is unknown, but you have a general idea of which object types it might belong to.

{% linetabs %}
{% linetab title="Original" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg)

![Original 1920x1280 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg)
{% /linetab %}
{% linetab title="Tightly Cropped image" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-truck_car_train](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-truck_car_train)

![982x301 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-truck_car_train)

Here, we crop out the car as the first object `truck` is not present in the image.
{% /linetab %}
{% linetab title="Tightly Cropped image with aspect ratio" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-truck_car_train,ar-2_1](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-truck_car_train,ar-2_1)

![982x491 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-truck_car_train,ar-2_1)

We crop out the first detected object `car` from the image with a `2:1` aspect ratio.
{% /linetab %}

{% linetab title="Using c-maintain_ratio" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-truck_car_train,w-400,h-400](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-truck_car_train,w-400,h-400)

![400x400 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-truck_car_train,w-400,h-400)

We resize the image using `c-maintain_ratio` crop strategy. Learn more about it [here](#examples---object-aware-cropping-maintain-ratio).
{% /linetab %}

{% linetab title="Using cm-extract" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-truck_car_train,w-600,h-400,cm-extract](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-truck_car_train,w-600,h-400,cm-extract)

![600x400 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-truck_car_train,w-600,h-400,cm-extract)

We crop out the first detected object `car` from an image using `cm-extract`mode. Learn more about it [here](#examples---object-aware-cropping-cm-extract).
{% /linetab %}
{% /linetabs %}

If multiple objects from the focus list are present in the image, cropping will be performed based on the first matching object found.

{% linetabs %}
{% linetab title="Original" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg)

![Original 600x336 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg)
{% /linetab %}

{% linetab title="Cropping dog" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg?tr=fo-dog_cat](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg?tr=fo-dog_cat)

![292x322 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg?tr=fo-dog_cat)

Since `dog` is the first object in the given list, the image is cropped based on the position of the dog.
{% /linetab %}

{% linetab title="Cropping cat" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg?tr=fo-cat_dog](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg?tr=fo-cat_dog)

![119x169 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg?tr=fo-cat_dog)

Since `cat` is the first object in the given list, the image is cropped based on the position of the cat.
{% /linetab %}
{% /linetabs %}




### Supported object list
We currently support all the objects included in the `COCO` classes. The object list is mentioned below:

| COCO Classes |
|--------------|
| person       |
| bicycle      |
| car          |
| motorcycle   |
| airplane     |
| bus          |
| train        |
| truck        |
| boat         |
| trafficLight |
| fireHydrant  |
| stopSign     |
| parkingMeter |
| bench        |
| bird         |
| cat          |
| dog          |
| horse        |
| sheep        |
| cow          |
| elephant     |
| bear         |
| zebra        |
| giraffe      |
| backpack     |
| umbrella     |
| handbag      |
| tie          |
| suitcase     |
| frisbee      |
| skis         |
| snowboard    |
| sportsBall   |
| kite         |
| baseballBat  |
| baseballGlove|
| skateboard   |
| surfboard    |
| tennisRacket |
| bottle       |
| wineGlass    |
| cup          |
| fork         |
| knife        |
| spoon        |
| bowl         |
| banana       |
| apple        |
| sandwich     |
| orange       |
| broccoli     |
| carrot       |
| hotDog       |
| pizza        |
| donut        |
| cake         |
| chair        |
| couch        |
| pottedPlant  |
| bed          |
| diningTable  |
| toilet       |
| tv           |
| laptop       |
| mouse        |
| remote       |
| keyboard     |
| cellPhone    |
| microwave    |
| oven         |
| toaster      |
| sink         |
| refrigerator |
| book         |
| clock        |
| vase         |
| scissors     |
| teddyBear    |
| hairDrier    |
| toothbrush   |


## Zoom - (z)

This parameter accepts a number that determines how much to zoom in or out of the cropped area. It must be used along with [fo-face](#face-cropping---fo-face) or [fo-<object_name>](#object-aware-cropping---fo-object-name). A value less than 1.0 zooms out to include more background surrounding the object, whereas a value larger than 1.0 zooms in to exclude more background surrounding the object.

Possible Values -  `0 < z < 1` (zoom out); `z > 1` (zoom in); `z-1`

### With fo-face

{% linetabs %}
{% linetab title="Original image" %}
[https://ik.imagekit.io/ikmedia/docs_images/examples/example_portrait_1.jpg](https://ik.imagekit.io/ikmedia/docs_images/examples/example_portrait_1.jpg)

![Original Image](<https://ik.imagekit.io/ikmedia/docs_images/examples/example_portrait_1.jpg>)

{% /linetab %}

{% linetab title="Face crop (fo-face)" %}
[https://ik.imagekit.io/ikmedia/tr:w-150,h-150,fo-face/docs_images/examples/example_portrait_1.jpg](https://ik.imagekit.io/ikmedia/tr:w-150,h-150,fo-face/docs_images/examples/example_portrait_1.jpg?updatedAt=1703135626910)

Since no value of zoom is mentioned hence by default `zoom=1`.


![Face crop (fo-face)](<https://ik.imagekit.io/ikmedia/tr:w-150,h-150,fo-face/docs_images/examples/example_portrait_1.jpg?updatedAt=1703135626910>)

{% /linetab %}

{% linetab title="Zoom=2.0" %}
[https://ik.imagekit.io/ikmedia/tr:w-150,h-150,fo-face,z-2.0/docs_images/examples/example_portrait_1.jpg](https://ik.imagekit.io/ikmedia/tr:w-150,h-150,fo-face,z-2.0/docs_images/examples/example_portrait_1.jpg?updatedAt=1703135626910)

For `z=2.0`, a thumbnail is generated zoomed in on the face with a zoom amount of 200%, excluding more background surrounding the face.

![200px wide](<https://ik.imagekit.io/ikmedia/tr:w-150,h-150,fo-face,z-2.0/docs_images/examples/example_portrait_1.jpg?updatedAt=1703135626910>)

{% /linetab %}

{% linetab title="Zoom=0.5" %}
[https://ik.imagekit.io/ikmedia/tr:w-150,h-150,fo-face,z-0.5/docs_images/examples/example_portrait_1.jpg](https://ik.imagekit.io/ikmedia/tr:w-150,h-150,fo-face,z-0.5/docs_images/examples/example_portrait_1.jpg?updatedAt=1703135626910)

For `z=0.5`, a thumbnail is generated zoomed out to 50% before cropping, including more of the background surrounding the face.

![Face crop (fo-face)](<https://ik.imagekit.io/ikmedia/tr:w-150,h-150,fo-face,z-0.5/docs_images/examples/example_portrait_1.jpg?updatedAt=1703135626910>)

{% /linetab %}
{% /linetabs %}

### With `fo-<object>` and default crop mode (c-maintain_ratio)
When no `zoom` value is provided, the behavior defaults to simple [object aware cropping](#examples---object-aware-cropping-maintain-ratio), where only one dimension of the image is cropped. However, when `zoom=1` is specified, it can crop the image on both dimensions to focus on the object as much as possible.

{% linetabs %}
{% linetab title="Original" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg)

![Original 1920x1280 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg)
{% /linetab %}

{% linetab title="Smart crop (fo-car)" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=w-400,h-400,fo-car](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=w-400,h-400,fo-car)

![400x400 smart cropped image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=w-400,h-400,fo-car)

In the above image, rather than cropping equally from both the left and right, only the left portion was cropped to ensure the object in focus is centered. Learn more about object-aware cropping [here](#object-aware-cropping---fo-object-name).
{% /linetab %}

{% linetab title="Zoom=1" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=w-400,h-400,z-1,fo-car](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=w-400,h-400,z-1,fo-car)

![400x400 smart cropped image with zoom=1](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=w-400,h-400,z-1,fo-car)

In the above image, the entire car has been preserved, and additional background has been added vertically to maintain the original aspect ratio of the image.
{% /linetab %}


{% linetab title="Zoom=0.6" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=w-400,h-400,z-0.6,fo-car](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=w-400,h-400,z-0.6,fo-car)

![400x400 smart cropped image with zoom=0.6](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=w-400,h-400,z-0.6,fo-car)

The car image has been zoomed out to include more of the background.
{% /linetab %}

{% linetab title="Zoom=1.4" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=w-400,h-400,z-1.4,fo-car](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=w-400,h-400,z-1.4,fo-car)

![400x400 smart cropped image with zoom=1.4](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=w-400,h-400,z-1.4,fo-car)

The car image has been zoomed in to exclude background and focus more on the car.
{% /linetab %}

{% /linetabs %}



### With `fo-<object>` and cm-extract

{% linetabs %}
{% linetab title="Original" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg)

![Original 1920x1280 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg)
{% /linetab %}

{% linetab title="Smart crop extract with default zoom" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=w-600,h-400,fo-car,cm-extract](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=w-600,h-400,fo-car,cm-extract)

![600x400 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=w-600,h-400,fo-car,cm-extract)

Here, we have intelligently detected the `xc`and `yc` values as the central coordinates of the car and then extracted out an area of 600x400 from that center. Here, by default `zoom=1`.
{% /linetab %}
{% linetab title="Zoom=0.6" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=w-600,h-400,fo-car,z-0.6,cm-extract](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=w-600,h-400,fo-car,z-0.6,cm-extract)

![600x400 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=w-600,h-400,fo-car,z-0.6,cm-extract)

The image has been zoomed out to include more of the background.
{% /linetab %}

{% linetab title="Zoom=1.4" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=w-600,h-400,fo-car,z-1.4,cm-extract](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=w-600,h-400,fo-car,z-1.4,cm-extract)

![600x400 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=w-600,h-400,fo-car,z-1.4,cm-extract)

The image has been zoomed in to exclude the background and focus more on the object.
{% /linetab %}
{% /linetabs %}

### With tightly cropped object

Zoom can also be used with [tightly crop object](#tightly-crop-object).

{% linetabs %}
{% linetab title="Original" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg)

![Original 1920x1280 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg)
{% /linetab %}

{% linetab title="Tightly cropped image with default zoom" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-car](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-car)

![982x301 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-car)

The output is an image containing just the car. Here, by default `zoom=1`.
{% /linetab %}

{% linetab title="Zoom=0.6" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-car,z-0.6](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-car,z-0.6)

![982x301 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-car,z-0.6)

The output is a zoomed out image of the car.
{% /linetab %}

{% linetab title="Zoom=1.4" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-car,z-1.4](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-car,z-1.4)

![982x301 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-car,z-1.4)

The output is a zoomed in image of the car.
{% /linetab %}

{% /linetabs %}

{% linetabs %}
{% linetab title="With aspect ratio and default zoom" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-car,ar-2_1](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-car,ar-2_1)

![982x491 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-car,ar-2_1)

The output is an image containing only the car, plus the additional `height` needed to maintain an `aspect ratio` of 2. Here, by default `zoom=1`.
{% /linetab %}

{% linetab title="Zoom=0.6"%}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-car,ar-2_1,z-0.6](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-car,ar-2_1,z-0.6)

![982x491 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-car,ar-2_1,z-0.6)

The output is a zoomed out image of the car with `ar-2_1`.
{% /linetab %}

{% linetab title="Zoom=1.4" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-car,ar-2_1,z-1.4](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-car,ar-2_1,z-1.4)

![982x491 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=fo-car,ar-2_1,z-1.4)

The output is a zoomed in image of the car with `ar-2_1`.
{% /linetab %}
{% /linetabs %}

## DPR - (dpr)

Used to specify the device pixel ratio that is used to calculate the dimensions of the output image. Extremely helpful when creating image transformations for devices with a high device pixel ratio (DPR > 1), like the iPhone or high-end Android devices.

The `dpr` parameter can only be used when either the height or width of the desired output image is specified.

If the output image's height or width after considering the specified DPR is less than 1px or greater than 5000px, the value of DPR is not considered and the height or width used in the URL is used.

**Possible values** - `0.1`  to `5`.

Alternatively, you can specify the `auto` value for this parameter (`dpr-auto`). Doing so will instruct ImageKit to read the `dpr` value from the [Sec-CH-DPR Client Hint](https://imagekit.io/responsive-images/#sec-ch-dpr) request header. Learn more about client hints [here](/image-transformation#client-hints).

### DPR in chained transformations

By default, the DPR multiplication factor is applied to dimension parameters (height and width) at every step in a chain of transformations. This causes incorrect intermediate sizes in chained transformations.

To correct this behavior, you can enable the **Apply DPR in final transformation step only** setting. When enabled, DPR scaling is only applied in the final step of chained transformations, ensuring that only the final output dimensions are correctly resized.

This setting is available in the [ImageKit dashboard](https://imagekit.io/dashboard/settings/images) under the **Advanced** section.

{% callout style="info" %}
**Testing on individual URLs:** You can override this setting on a per-URL basis using the query parameter `?ik-overrideFlag=dprLastStepOnly_true` to enable it or `?ik-overrideFlag=dprLastStepOnly_false` to disable it, without changing the global setting.
{% /callout %}


---

# Source: /add-overlays-on-images

---
title: Add overlays on images
description: A comprehensive guide on adding images and text on top of a base image using ImageKit.
---

ImageKit enables you to creatively enhance your images by adding dynamic overlays using [layers](/transformations#overlay-using-layers). You can overlay images, text, or solid color blocks on your base image with precise control over positioning and appearance.

## What you can do with overlays

**Layer multiple elements** - Combine [images](#add-images-over-image), [text](#add-text-over-image), and [solid color blocks](#add-solid-color-blocks-over-image) to create watermarks, badges, captions, and complex compositions. Each layer can be positioned using absolute coordinates, relative positions, or [arithmetic expressions](/arithmetic-expressions-in-transformations).

**Transform independently** - Apply different transformations to your base image and overlays. Resize, crop, add effects, adjust colors, or apply enhancements to each layer separately before compositing them together.

**Advanced blending** - Go beyond basic overlays with [layer modes](#layer-modes) that control how layers blend together. Create darkening effects with multiply mode, distortion effects with displacement maps, or transparency masks with cutout and cutter modes.

**Build complex layouts** - [Nest layers](#nesting-of-image-layers) up to 3 levels deep to create sophisticated designs with multiple overlay elements positioned relative to each other. You can also [nest text and image layers inside a canvas](#nest-text-and-image-layers-inside-canvas) to build self-contained cards and badges.

Review the [limits on resource-intensive transformations](/image-transformation#expensive-transformation-limits) before deploying overlay features in production.

## Add images over image
You can add an image over a base image using the following syntax.

```markup
         URL endpoint         Base image            Image layer
┌──────────────────────────┐┌────────────┐    ┌──────────────────────┐
https://ik.imagekit.io/demo/base-image.jpg?tr=l-image,i-logo.png,l-end
```

In the above example, we use the image `logo.png` present at the root of the account's media library as a layer on `base-image.jpg`.

To use an image from your media library, set the value of either the `i` or `ie` parameter based on the characters in the image path:
* Use the `i-` parameter if the path contains only alphanumeric characters, "@", "-", or "_". In this case, simply pass the path as-is. eg. `i-simple-alpha@numeric_string.jpg`
* If the path contains any other characters, it's recommended to use the `ie-` parameter. In this case, base64-encode the path first, then percent-encode the result.

For example, let's add the [ImageKit logo](https://ik.imagekit.io/demo/logo-white_SJwqB4Nfe.png) on a sample image.

[https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,l-end/medium_cafe_B1iTdD0C.jpg)

You can also control the position of the image overlay using these [positional parameters](/transformations#position-of-layer).

{% callout style="info" %}
To overlay images stored within a specific folder of your media library, use the complete image path where slashes (`/`) are replaced with `@@`. 

For example, if the overlay image is at \
`https://ik.imagekit.io/demo/path/to/overlay.png`, then it can be used as an overlay like: \
`https://ik.imagekit.io/demo/base-image.jpg?tr=l-image,i-path@@to@@overlay.png,l-end`
{% /callout %}

You can also use an HTTP(S) URL of an image. ImageKit will fetch the image from the URL, and use it as the layer. Since URLs will always contain special characters, make sure to use `ie-` as described above.

For example, let's create the same result as above but using the [complete URL](https://ik.imagekit.io/demo/logo-white_SJwqB4Nfe.png) for the ImageKit logo image.

[https://ik.imagekit.io/demo/tr:l-image,ie-aHR0cHM6Ly9pay5pbWFnZWtpdC5pby9kZW1vL2xvZ28td2hpdGVfU0p3cUI0TmZlLnBuZwo%3D,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,ie-aHR0cHM6Ly9pay5pbWFnZWtpdC5pby9kZW1vL2xvZ28td2hpdGVfU0p3cUI0TmZlLnBuZwo%3D,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,ie-aHR0cHM6Ly9pay5pbWFnZWtpdC5pby9kZW1vL2xvZ28td2hpdGVfU0p3cUI0TmZlLnBuZwo%3D,l-end/medium_cafe_B1iTdD0C.jpg)

## Control position of image overlay

You can control image layer position using the `lx`, `ly`, `lxc`, `lyc`, and `lap` parameters. If the `lx`, `ly`, `lxc`, or `lyc` values exceed the dimensions of the input image, the values are adjusted to fit within the image. To change the direction, negative values are also supported by prefixing the value with 'N'.

The `lx` and `ly` parameters position the layer using its top-left corner as the reference point. While the `lxc` and `lyc` parameters position the layer using its center as the reference point.

The `lap` (layer anchor point) parameter sets the anchor point on the base image from which the offset is calculated. By default, the anchor point is `top_left`. Possible values are: `top`, `left`, `right`, `bottom`, `top_left`, `top_right`, `bottom_left`, `bottom_right`, and `center`.

You can also use [arithmetic expressions](/arithmetic-expressions-in-transformations) in `lx`, `ly`, `lxc`, and `lyc` to better control the position of the overlay. Learn more about [positional parameters](/transformations#position-of-layer) in layers.

{% linetabs %}
{% linetab title="Default center overlay" %}
URL - [https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="LX=35" %}
URL - [https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,lx-35,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,lx-35,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,lx-35,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="LYC=50" %}
URL - [https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,lyc-50,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,lyc-50,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,lyc-50,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="LX with LAP" %}
URL - [https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,lx-N50,lap-right,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,lx-N50,lap-right,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,lx-N50,lap-right,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="LX=N35 (Negative value)" %}
URL - [https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,lx-N35,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,lx-N35,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,lx-N35,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% /linetabs %}

{% linetabs %}
{% linetab title="LX=bw_mul_0.2,LY=bh_mul_0.4" %}
Use the following URL to position the image 20% from the top-left corner in the `x` direction and 40% in the `y` direction.

[https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,lx-bw_mul_0.2,ly-bh_mul_0.4,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,lx-bw_mul_0.2,ly-bh_mul_0.4,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,lx-bw_mul_0.2,ly-bh_mul_0.4,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="LY=bh_mul_0.8" %}
Use the following URL to position the image near the bottom-left corner.
URL - [https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,ly-bh_mul_0.8,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,ly-bh_mul_0.8,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,ly-bh_mul_0.8,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="20% from top and at center" %}
Use the following URL to position the image 20% from top and at center. Note the [sequence of operator](/arithmetic-expressions-in-transformations#calculation-sequence-for-multiple-operators)  used in `lx-bw_div_2_sub_iw_div_2`.

[https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,ly-bh_mul_0.2,lx-bw_div_2_sub_iw_div_2,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,ly-bh_mul_0.2,lx-bw_div_2_sub_iw_div_2,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,ly-bh_mul_0.2,lx-bw_div_2_sub_iw_div_2,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% /linetabs %}

## Apply transformation on image overlay

Inside an image layer, you can apply [these supported transformations](#list-of-supported-image-transformations-in-image-layers) to the image overlay before it is placed on the base image. You can [chain the transformations](/transformations#chained-transformations) one after the other to achieve the desired outcome.

For example, let's resize the overlay image to 400x400 and add a yellow background to fill the image layer's background.

URL - [https://ik.imagekit.io/demo/tr:l-image,i-women-dress.jpeg,h-400,w-400,cm-pad_resize,bg-yellow,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-women-dress.jpeg,h-400,w-400,cm-pad_resize,bg-yellow,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-women-dress.jpeg,h-400,w-400,cm-pad_resize,bg-yellow,l-end/medium_cafe_B1iTdD0C.jpg)

You can also apply additional transformations, such as `e-grayscale`, to modify the overlay image. Here's an example of turning the overlay image into a grayscale version.

URL - [https://ik.imagekit.io/demo/tr:l-image,i-women-dress.jpeg,h-400,w-400,e-grayscale,cm-pad_resize,bg-yellow,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-women-dress.jpeg,h-400,w-400,e-grayscale,cm-pad_resize,bg-yellow,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-women-dress.jpeg,h-400,w-400,e-grayscale,cm-pad_resize,bg-yellow,l-end/medium_cafe_B1iTdD0C.jpg)

You can also use [arithmetic expressions](/arithmetic-expressions-in-transformations) to resize the overlay image relative to the base image. 

{% linetabs %}
{% linetab title="H=bh_div_2,W=iw_div_2" %}
Use the following URL to resize the overlaid image to half of the base image in height and width.

[https://ik.imagekit.io/demo/tr:l-image,i-women-dress.jpeg,h-bh_div_2,w-iw_div_2,cm-pad_resize,bg-yellow,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-women-dress.jpeg,h-bh_div_2,w-iw_div_2,cm-pad_resize,bg-yellow,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-women-dress.jpeg,h-bh_div_2,w-iw_div_2,cm-pad_resize,bg-yellow,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="H=bh,W=iw_div_2" %}
Use the following URL to resize the overlaid image to have a height equal to the base image and a width of 50 percent of the base image and place it on the left side.
URL - [https://ik.imagekit.io/demo/tr:l-image,i-women-dress.jpeg,h-bh,w-iw_div_2,bg-yellow,lx-0,ly-0,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-women-dress.jpeg,h-bh,w-iw_div_2,bg-yellow,lx-0,ly-0,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-women-dress.jpeg,h-bh,w-iw_div_2,bg-yellow,lx-0,ly-0,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="Nested image layers" %}
You can use expression parameters to create nested layer structures as shown below.

[https://ik.imagekit.io/demo/tr:l-image,i-women-dress.jpeg,h-bh_div_2,w-bw_div_2,cm-pad_resize,bg-yellow:l-image,i-women-dress.jpeg,cm-pad_resize,h-bh_div_2,w-bw_div_2,bg-red,l-end,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-women-dress.jpeg,h-bh_div_2,w-bw_div_2,cm-pad_resize,bg-yellow:l-image,i-women-dress.jpeg,cm-pad_resize,h-bh_div_2,w-bw_div_2,bg-red,l-end,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-women-dress.jpeg,h-bh_div_2,w-bw_div_2,cm-pad_resize,bg-yellow:l-image,i-women-dress.jpeg,cm-pad_resize,h-bh_div_2,w-bw_div_2,bg-red,l-end,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="Multiple image layers" %}
You can use expression parameters to create appropriate multiple layer patterns.

[https://ik.imagekit.io/demo/tr:l-image,i-women-dress.jpeg,h-bh_div_2,w-bw_div_2,cm-pad_resize,t-false:lx-0,ly-bh_div_2_sub_ch_div_2,bg-yellow,l-end:l-image,i-women-dress.jpeg,cm-pad_resize,t-false,h-bh_div_2,w-bw_div_2,bg-red:lx-bw_div_2,ly-bh_div_2_sub_ch_div_2,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-women-dress.jpeg,h-bh_div_2,w-bw_div_2,cm-pad_resize,t-false:lx-0,ly-bh_div_2_sub_ch_div_2,bg-yellow,l-end:l-image,i-women-dress.jpeg,cm-pad_resize,t-false,h-bh_div_2,w-bw_div_2,bg-red:lx-bw_div_2,ly-bh_div_2_sub_ch_div_2,l-end/medium_cafe_B1iTdD0C.jpg)

**Note-** `t-false` is added to ensure the layer image is not automatically trimmed.

![](https://ik.imagekit.io/demo/tr:l-image,i-women-dress.jpeg,h-bh_div_2,w-bw_div_2,cm-pad_resize,t-false:lx-0,ly-bh_div_2_sub_ch_div_2,bg-yellow,l-end:l-image,i-women-dress.jpeg,cm-pad_resize,t-false,h-bh_div_2,w-bw_div_2,bg-red:lx-bw_div_2,ly-bh_div_2_sub_ch_div_2,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% /linetabs %}

### List of supported image transformations in image layers

| Parameter                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [w](/image-resize-and-crop#width---w)                                        | Width of the overlay image. It can also accept arithmetic expressions such as `iw_div_2`, or `bw_sub_cw`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).                                                                                                                                                                                                                                                                               |
| [h](/image-resize-and-crop#height---h)                                       | Height of the overlay image. It can also accept arithmetic expressions such as `ih_div_2`, or `bh_mul_0.8`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).                                                                                                                                                                                                                                                                             |
| [ar](/image-resize-and-crop#aspect-ratio---ar)                               | Aspect ratio of the overlay image. It can also accept arithmetic expressions such as `iar_div_2`, or `bar`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).                                                                                                                                                                                                                                                                             |
| [c](/image-resize-and-crop#crop-crop-modes--focus)                           | Cropping method. Accepts `force`, `at_max`, and `at_least`.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| [cm](/image-resize-and-crop#crop-crop-modes--focus)                          | Crop mode. Supports `extract` and `pad_resize`.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [fo](/image-resize-and-crop#focus---fo)                                      | Relative focus area used during cropping. Accepts `face`, `custom`, `center`, `top`, `left`, `bottom`, `right`, `top_left`, `top_right`, `bottom_left`, and `bottom_right`. It also supports [object-aware cropping](/image-resize-and-crop#object-aware-cropping---fo-object-name).                                                                                                                                                                                                                                                                                                         |
| [z](/image-resize-and-crop#zoom---z)                                         | It determines how much to zoom in or out of the cropped area. It must be used along with `fo-face`. A value less than `1.0` zooms out to include more background surrounding the face, whereas a value larger than `1.0` zooms in to exclude more background surrounding the face. Possible values include any number between `0` to `1` for zoom out, and greater than `1` for zoom in. Its default value is `1.0`.                                                                |
| [b](/effects-and-enhancements#border---b)                                       | It adds a border to the overlay image. It accepts two parameters - the width of the border and the color of the border in format `b-<border-width>-<hex code>`. It can also accept arithmetic expressions such as `bh_mod_5_red`, or `bw_mul_0.05_FF00FF`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).                                                                                                                              |
| [o](/effects-and-enhancements#opacity---o)                                      | It is used to specify the opacity level of the output image. It accepts numerical values ranging from 0 to 100, where 0 would produce a completely transparent image, and 100 would have no effect.                                                                                                                                                                                                                                                                                 |
| [bg](/effects-and-enhancements#background---bg)                                 | It is used to specify the background color to the overlay image. For a solid color background, its values can be an RGB Hex Code (e.g. `FF0000`), or an RGBA Code (e.g. `FFAABB50`), or a color name (e.g. `red`). If you specify an 8-character background, the last two characters must be a number between 00 and 99, which is used to indicate the opacity level of the background. `00` represents an opacity level of `0.00`, `01` represents an opacity level of `0.01`, and so on. For a blurred background, refer to [blurred background](/effects-and-enhancements#blurred-background). For using the dominant color as background, refer to [dominant color background](/effects-and-enhancements#dominant-color-background). For a gradient background, refer to [gradient background](/effects-and-enhancements#gradient-background).                               |
| [r](/effects-and-enhancements#radius---r)                                       | It is used to control the radius of the corner. To get a circle or oval shape, set the value to `max`.                                                                                                                                                                                                                                                                                                                                                                              |
| [rt](/effects-and-enhancements#rotate---rt)                                     | It is used to specify the degree by which the overlay image must be rotated.                                                                                                                                                                                                                                                                                                                                                                                                        |
| [fl](/effects-and-enhancements#flip---fl) | It is used to flip/mirror the overlay image horizontally, vertically, or in both directions.
| [t](/effects-and-enhancements#trim-edges---t)                                   | By default, ImageKit.io trims the overlay image before overlaying it on the base image. Trimming removes similar colored pixels from the edges. To prevent the default trimming from happening, use `t-false`. **Possible values** include `true`, `false`, and integer values between `1` and `99` that specify the threshold level for considering a particular pixel as "background".                                                                                          |
| [dpr](/image-resize-and-crop#dpr---dpr)                                      | It is used to specify the device pixel ratio that is used to calculate the dimensions of the overlay image. It can only be used when either the height or width of the desired output image is specified. The possible values are `0.1` to `5`, or `auto`.                                                                                                                                                                                                                          |
| [q](/image-optimization#quality---q)                                      | It is used to specify the quality of the output image for lossy formats like JPEG, WebP, and AVIF. A large quality number indicates a larger output image size with high quality. A small quality number indicates a smaller output image size with lower quality. It can be a whole number between `1` and `100`. The default value is `80`.                                                                                                                                       |
| [bl](/effects-and-enhancements#blur---bl)                                       | It is used to specify the Gaussian blur that must be applied to an image. The value of `bl` specifies the radius of the Gaussian Blur that is to be applied. The higher the value, the larger the radius of the Gaussian Blur. Accepts integers between `1` and `100`.                                                                                                                                                                                                                  |
| [x](/image-resize-and-crop#example---focus-using-cropped-image-coordinates)  | It is used along with [cm-extract](/image-resize-and-crop#extract-crop-strategy---cm-extract) to specify the `X` coordinate of the top-left point where the extract must begin. Possible values are integers, or an arithmetic expression such as `iw_div_2`, or `bh_sub_100`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).                                                                                    |
| [y](/image-resize-and-crop#example---focus-using-cropped-image-coordinates)  | It is used along with [cm-extract](/image-resize-and-crop#extract-crop-strategy---cm-extract) to specify the `Y` coordinate of the top-left point where the extract must begin. Possible values are integers, or an arithmetic expression such as `ih_div_2`, or `bw_sub_150`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).                                                                                    |
| [xc](/image-resize-and-crop#example---focus-using-cropped-image-coordinates) | It is used along with [cm-extract](/image-resize-and-crop#extract-crop-strategy---cm-extract) to specify the `X` coordinate of the center point of the image to be extracted. Possible values are integers, or an arithmetic expression such as `iw_div_3`, or `ih_div_4`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).                                                                                        |
| [yc](/image-resize-and-crop#example---focus-using-cropped-image-coordinates) | It is used along with [cm-extract](/image-resize-and-crop#extract-crop-strategy---cm-extract) to specify the `Y` coordinate of the center point of the image to be extracted. Possible values are integers, or an arithmetic expression such as `iw_div_3`, or `ih_div_4`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).                                                                                          |
| [e-grayscale](/effects-and-enhancements#grayscale---e-grayscale)                | It is used to turn an image to a grayscale version.                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [e-colorize](/effects-and-enhancements#colorize---e-colorize)                   | It is used to apply a color tint to the overlay image. The color and intensity of the tint can be varied using the following parameters - `co` and `in`. e.g. `e-colorize-co-<color>_in-<intensity>` (or simply `e-colorize` to let the tint take on default values). The `co` parameter accepts standard color names (e.g. `blue`) and RGB hex codes (e.g. `FF0000`), with a default of `gray`. The `in` parameter accepts values between `0` and `100`, with a default of `35`. Learn more about the colorize effect and its parameters [here](/effects-and-enhancements#colorize---e-colorize). |
| [e-contrast](/effects-and-enhancements#e-contrast---e-contrast)                                    | It is used to automatically enhance the contrast of the image by using the full intensity values that a particular image format allows. This means that the lighter sections of an image become even lighter and the darker sections become even brighter, thereby enhancing the contrast.                                                                                                                                                                                           |
| [e-sharpen](/effects-and-enhancements#e-sharpen---e-sharpen)                                       | It is used to sharpen the input image, useful when highlighting the edges and finer details within an image. If just the `e-sharpen` parameter is used, then a default sharpening is performed on the input image. This can be controlled by specifying a number that restricts the extent of sharpening performed, like `e-sharpen-<number>`.                                                                                                                                      |
| [e-usm](/effects-and-enhancements#unsharp-mask---e-usm)                                            | It is used to apply and control unsharp masks on your images. The amount of sharpening can be varied using 4 parameters - `radius`, `sigma`, `amount`, and `threshold`. This results in perceptually better images compared to using `e-sharpen`. Only positive floating points are allowed for these 4 parameters. e.g. `e-usm-<radius>-<sigma>-<amount>-<threshold>`                                                                                                              |
| [e-shadow](/effects-and-enhancements#shadow---e-shadow)                                            | It is used to apply a shadow effect on the input image. The strength, blur, and geometrical positioning of the shadow can be varied using the following parameters - `st`, `bl`, `x` and `y`. e.g. `e-shadow-st-<value>_bl-<value>_x-<value>_y-<value>` (or simply `e-shadow` to let the shadow take on default values). Learn more about the shadow effect and its parameters [here](/effects-and-enhancements#shadow---e-shadow).                                              |
| [e-gradient](/effects-and-enhancements#gradient---e-gradient)                                      | It is used to add a linear gradient overlay over an input image. The direction, from color, to color, and the stop point of the gradient can be varied using the following parameters - `ld`, `from`, `to` and `sp`. e.g. `e-gradient-<linear-direction>_<from-color>_<to-color>_<stop-point>` (or simply `e-gradient` to let the gradient take on default values). Learn more about the gradient effect and its parameters [here](/effects-and-enhancements#gradient---e-gradient). |
| [e-distort](/effects-and-enhancements#distort---e-distort)                                         | It is used to distort the shape of the overlay image. Supports perspective distortion using `e-distort-p-<x1>_<y1>_<x2>_<y2>_<x3>_<y3>_<x4>_<y4>` where you provide new coordinates for the four corners starting clockwise from top-left. Also supports arc distortion using `e-distort-a-<degrees>` to curve the image upwards (positive values) or downwards (negative values). Learn more about the distort effect [here](/effects-and-enhancements#distort---e-distort).   |

## Nesting of image layers

A layer can have nested layers up to 3 levels. 

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

In the following example, we overlay the resized `women-dress.jpeg` with a red border on the bottom left corner of the base image and then add the `imagekit.io` logo on the top right corner of the `women-dress.jpeg` image. [`lfo`](/transformations#position-of-layer) parameter is used to control the position of layer in relative terms.

URL - [https://ik.imagekit.io/demo/tr:l-image,i-women-dress.jpeg,h-400,b-10_red,lfo-bottom_left,l-image,i-logo-white_SJwqB4Nfe.png,w-150,lfo-top_right,l-end,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-women-dress.jpeg,h-400,b-10_red,lfo-bottom_left,l-image,i-logo-white_SJwqB4Nfe.png,w-150,lfo-top_right,l-end,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-women-dress.jpeg,h-400,b-10_red,lfo-bottom_left,l-image,i-logo-white_SJwqB4Nfe.png,w-150,lfo-top_right,l-end,l-end/medium_cafe_B1iTdD0C.jpg)

## Add text over image

You can add any text string over a base image using the following syntax. 

```markup
         URL endpoint         Base image           Text layer
┌──────────────────────────┐┌────────────┐    ┌──────────────────┐
https://ik.imagekit.io/demo/base-image.jpg?tr=l-text,i-hello,l-end
```

In the above example, the string "hello" is overlaid on base-image.jpg.

Set the value of either the `i` or `ie` parameter based on the characters in the text string:
* Use the `i-` parameter if the string contains only alphanumeric characters, "@", "-", or "_". In this case, simply pass the string as-is. eg. `i-simple-alpha@numeric_string`
* If the string contains any other characters, it's recommended to use the `ie-` parameter. In this case, base64-encode the string first, then percent-encode the result.

For example, to overlay the text `hello` on top of `base-image.jpg`, use the following URL:

```markup
         URL endpoint         Base image                   Text layer
┌──────────────────────────┐┌────────────┐    ┌──────────────────┐
https://ik.imagekit.io/demo/base-image.jpg?tr=l-text,i-hello,l-end
```

For a text string like `20% off discount`, use the following URL:

```markup
         URL endpoint         Base image                   Text layer
┌──────────────────────────┐┌────────────┐    ┌──────────────────────────────────┐
https://ik.imagekit.io/demo/base-image.jpg?tr=l-text,ie-MjAlIG9mZiBkaXNjb3VudA%3D%3D,l-end
```

Here, `MjAlIG9mZiBkaXNjb3VudA%3D%3D` is the base64-encoded string for `20% off discount`, which is then percent-encoded.

In JavaScript, you can generate this value using:

```javascript
encodeURIComponent(btoa("20% off discount"))
```

You can also control the position of the text overlay using these [positional parameters](/transformations#position-of-layer).

{% callout style="info" %}
**Notes:**
1. Plain text input longer than 2000 characters will be truncated.
2. Base64 encoded text input longer than 2500 characters will be truncated.
{% /callout %}

{% callout style="warning" %}
**Text layer dimension limit** \
If the text layer takes up more than 16,383 pixels horizontally or vertically, then the request will error out.
{% /callout %}

## Control position of text overlay

You can control text layer position using the `lx`, `ly`, `lxc`, `lyc`, and `lap` parameters. To change the direction, negative values are also supported by prefixing the value with 'N'.

The `lx` and `ly` parameters position the layer using its top-left corner as the reference point. While the `lxc` and `lyc` parameters position the layer using its center as the reference point.

The `lap` (layer anchor point) parameter sets the anchor point on the base image from which the offset is calculated. By default, the anchor point is `top_left`. Possible values are: `top`, `left`, `right`, `bottom`, `top_left`, `top_right`, `bottom_left`, `bottom_right`, and `center`.

You can also use [arithmetic expressions](/arithmetic-expressions-in-transformations) in `lx`, `ly`, `lxc`, and `lyc` to better control the position of the overlay. Learn more about [positional parameters](/transformations#position-of-layer) in layers.

{% linetabs %}
{% linetab title="Default center overlay" %}
URL - [https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="LX=35" %}
URL - [https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,lx-35,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,lx-35,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,lx-35,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="LX=N35 (Negative value)" %}
URL - [https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,lx-N35,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,lx-N35,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,lx-N35,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="LYC=N100 (Negative value)" %}
URL - [https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,lyc-N100,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,lyc-N100,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,lyc-N100,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="LX, LY and LAP" %}
URL - [https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,lx-N25,ly-25,lap-top_right,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,lx-N25,ly-25,lap-top_right,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,lx-N25,ly-25,lap-top_right,l-end/medium_cafe_B1iTdD0C.jpgg)
{% /linetab %}

{% /linetabs %}

{% linetabs %}
{% linetab title="LX=bw_mul_0.1,LY=bh_mul_0.1" %}
Use the following URL to position the text 10% from the top-left corner in the `x` direction and 10% in the `y` direction.

[https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,lx-bw_mul_0.1,ly-bh_mul_0.1,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,lx-bw_mul_0.1,ly-bh_mul_0.1,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,lx-bw_mul_0.1,ly-bh_mul_0.1,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="LY=bh_mul_0.8" %}
Use the following URL to position the text near the bottom-left corner.

[https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,ly-bh_mul_0.8,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,ly-bh_mul_0.8,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,ly-bh_mul_0.8,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="Multiple text layers" %}
Use the following URL to position multiple text layers appropriately. Here, we have also controlled the layer's width with the help of expressions.
 
[https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy1,fs-45,ly-bh_mul_0.2,w-bh_div_2,bg-yellow,l-end:l-text,i-overlay%20made%20easy2,fs-45,w-bh_div_2,lx-bw_div_2,ly-bh_mul_0.2,bg-orange,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy1,fs-45,ly-bh_mul_0.2,w-bh_div_2,bg-yellow,l-end:l-text,i-overlay%20made%20easy2,fs-45,w-bh_div_2,lx-bw_div_2,ly-bh_mul_0.2,bg-orange,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy1,fs-45,ly-bh_mul_0.2,w-bh_div_2,bg-yellow,l-end:l-text,i-overlay%20made%20easy2,fs-45,w-bh_div_2,lx-bw_div_2,ly-bh_mul_0.2,bg-orange,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% /linetabs %}

## Apply transformation on text overlay

You can control the width, font size, font family, color, inner alignment, padding, transparency level, typography, background color, corner radius, rotation, and line height of the text overlay using [these supported transformations](#list-of-supported-text-transformations-in-text-layers) parameters.

For example, let's add a white background with padding and a bigger font size.

You can add padding to the text overlay using the `pa` parameter. The padding can be controlled individually for each side using the CSS shorthand notation.

{% linetabs %}
{% linetab title="pa=10" %}
URL - [https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,bg-white,pa-10,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,bg-white,pa-10,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,bg-white,pa-10,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="pa=40 and w=300" %}
URL - [https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,bg-white,pa-10,w-300,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,bg-white,pa-10,w-300,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,bg-white,pa-10,w-300,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="lh=20 and w=150" %}
URL - [https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,w-150,fs-45,bg-white,lh-20,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,w-150,fs-45,bg-white,lh-20,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,w-150,fs-45,bg-white,lh-20,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="pa=25_50_75_100" %}
URL - [https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,bg-white,pa-25_50_75_100,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,bg-white,pa-25_50_75_100,l-end/medium_cafe_B1iTdD0C.jpg)

* Top padding is 25
* Right padding is 50
* Bottom padding is 75
* Left padding is 100

![](https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,bg-white,pa-25_50_75_100,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="pa=25_75_60" %}
URL - [https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,bg-white,pa-25_75_60,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,bg-white,pa-25_75_60,l-end/medium_cafe_B1iTdD0C.jpg)

* Top padding is 25
* Right and left paddings are 75
* Bottom padding is 60

![](https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,bg-white,pa-25_75_60,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="pa=25_75" %}
URL - [https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,bg-white,pa-25_75,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,bg-white,pa-25_75,l-end/medium_cafe_B1iTdD0C.jpg)

* Top and bottom paddings are 25
* Right and left paddings are 75

![](https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,bg-white,pa-25_75,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}
{% /linetabs %}

## Change font family in text overlay

You can change the font family in the text overlay using the `ff` parameter. You can use the [standard fonts](#supported-text-font-list) available in ImageKit or upload your custom font file to use it in text overlays.

To use a custom font in text overlays, upload the font file in your media library and pass its path in the `ff` parameter in a text layer.

For example, `Lacquer-Regular_nGqtVsBJT.ttf` is a custom font file uploaded to the root of the media library and accessible at the URL `https://ik.imagekit.io/demo/Lacquer-Regular_nGqtVsBJT.ttf`.

URL - [https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,ff-Lacquer-Regular_nGqtVsBJT.ttf,co-yellow,fs-45,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,ff-Lacquer-Regular_nGqtVsBJT.ttf,co-yellow,fs-45,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,ff-Lacquer-Regular_nGqtVsBJT.ttf,co-yellow,fs-45,l-end/medium_cafe_B1iTdD0C.jpg)

If your custom font file is in a nested folder, then replace the slashes `/`in the path with `@@`. For example, a font file available at path `/font-folder/font-subfolder/my-custom-font.ttf` will be used as follows:

```markup
https://ik.imagekit.io/demo/tr:l-text,i-Hello%20World,ff-font-folder@@font-subfolder@@my-custom-font.ttf,fs-72,co-FFF000,l-end/default-image.jpg
```

## Non-English character support

You can overlay text in any language with custom fonts, for example.

URL - [https://ik.imagekit.io/ikmedia/tr:w-600,h-600:l-text,i-इमेजकिट के साथ,ff-fonts@@Poppins-Regular_Q15GrYWmL.ttf,fs-42,ia-left,pa-10,ly-N100,bg-FFFFFF75,co-145FDD,l-end:l-text,i-दुनिया के कोने-कोने में लोगों तक पहुंचें,pa-5,ly-N35,lx-300,fs-28,ia-right,ff-fonts@@Poppins-Regular_Q15GrYWmL.ttf,bg-FFFFFF75,l-end/girl_in_white.jpg](https://ik.imagekit.io/ikmedia/tr:w-600,h-600:l-text,i-%E0%A4%87%E0%A4%AE%E0%A5%87%E0%A4%9C%E0%A4%95%E0%A4%BF%E0%A4%9F%20%E0%A4%95%E0%A5%87%20%E0%A4%B8%E0%A4%BE%E0%A4%A5,ff-fonts@@Poppins-Regular_Q15GrYWmL.ttf,fs-42,ia-left,pa-10,ly-N100,bg-FFFFFF75,co-145FDD,l-end:l-text,i-%E0%A4%A6%E0%A5%81%E0%A4%A8%E0%A4%BF%E0%A4%AF%E0%A4%BE%20%E0%A4%95%E0%A5%87%20%E0%A4%95%E0%A5%8B%E0%A4%A8%E0%A5%87-%E0%A4%95%E0%A5%8B%E0%A4%A8%E0%A5%87%20%E0%A4%AE%E0%A5%87%E0%A4%82%20%E0%A4%B2%E0%A5%8B%E0%A4%97%E0%A5%8B%E0%A4%82%20%E0%A4%A4%E0%A4%95%20%E0%A4%AA%E0%A4%B9%E0%A5%81%E0%A4%82%E0%A4%9A%E0%A5%87%E0%A4%82,pa-5,ly-N35,lx-300,fs-28,ia-right,ff-fonts@@Poppins-Regular_Q15GrYWmL.ttf,bg-FFFFFF75,l-end/girl_in_white.jpg)

![](https://ik.imagekit.io/ikmedia/tr:w-600,h-600:l-text,i-%E0%A4%87%E0%A4%AE%E0%A5%87%E0%A4%9C%E0%A4%95%E0%A4%BF%E0%A4%9F%20%E0%A4%95%E0%A5%87%20%E0%A4%B8%E0%A4%BE%E0%A4%A5,ff-fonts@@Poppins-Regular_Q15GrYWmL.ttf,fs-42,ia-left,pa-10,ly-N100,bg-FFFFFF75,co-145FDD,l-end:l-text,i-%E0%A4%A6%E0%A5%81%E0%A4%A8%E0%A4%BF%E0%A4%AF%E0%A4%BE%20%E0%A4%95%E0%A5%87%20%E0%A4%95%E0%A5%8B%E0%A4%A8%E0%A5%87-%E0%A4%95%E0%A5%8B%E0%A4%A8%E0%A5%87%20%E0%A4%AE%E0%A5%87%E0%A4%82%20%E0%A4%B2%E0%A5%8B%E0%A4%97%E0%A5%8B%E0%A4%82%20%E0%A4%A4%E0%A4%95%20%E0%A4%AA%E0%A4%B9%E0%A5%81%E0%A4%82%E0%A4%9A%E0%A5%87%E0%A4%82,pa-5,ly-N35,lx-300,fs-28,ia-right,ff-fonts@@Poppins-Regular_Q15GrYWmL.ttf,bg-FFFFFF75,l-end/girl_in_white.jpg)

### List of supported text transformations in text layers

| Parameter | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| w         | The maximum width (in pixels) of the overlaid text on the image. The text is wrapped so that any words in a line that go beyond the given width are sent to the next line. The height of the text box is calculated automatically based on the total number of lines. It can also accept arithmetic expressions such as `bw_mul_0.2`, or `bh_div_2`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).                                                     |
| fs        | It is used to specify the font size. It can also accept arithmetic expressions such as `bw_mul_0.2`, or `bh_div_20`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).                                                                                                                                                                                                                                                                                     |
| ff        | It is used to specify the font of the overlaid text on the image. You can choose [any font from this list](#supported-text-font-list) or use a [custom font](#change-font-family-in-text-overlay).                                                                                                                                                                                                                                                          |
| co        | It is used to specify the color and transparency of the overlaid text on the image. It accepts RGB Hex Codes (e.g. `FF0000`), or RGBA Codes (e.g. `FFAABB50`), or color names (e.g. `red`). If you specify an 8-character background, the last two characters must be a number between `00` and `99`, which indicate the opacity level of the background. `00` represents an opacity level of `0.00`, `01` represents an opacity level of `0.01`, and so on.                                         |
| ia        | Inner alignment. Accepts `left`, `right`, and `center`. The default value is `center`.                                                                                                                                                                                                                                                                                                                                                                                                               |
| pa        | It is used to specify the padding around the overlaid text on the image. Supports any positive integer or a set of positive integers separated by underscores. The set of integers follows CSS shorthand order for determining the padding along each side of the overlay. e.g. `10`, `10_20`, `10_20_30` or `10_20_30_40`. It can also accept arithmetic expressions such as `bw_mod_5`, or `bw_div_20`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations). |
| al        | It is used to specify the transparency level of the overlaid text layer. Supports integers from `1` to `9`.                                                                                                                                                                                                                                                                                                                                                                                          |
| tg        | Typography. Supports bold `b`, italics `i`, `strikethrough`, or a combination of these. eg. `b_i`, `b_i_strikethrough` |
| bg        | It is used to specify the background color in RGB Hex Code (e.g. `FF0000`) or an RGBA Code (e.g. `FFAABB50`), or a color name (e.g. `red`). If you specify an 8-character background, the last two characters must be a number between `00` and `99`, which indicate the opacity level of the background. `00` represents an opacity level of `0.00`, `01` represents an opacity level of `0.01`, and so on.                                                                                         |
| r         | It is used to control the radius of the corner. To get a circle or oval shape, set the value to `max`. |
 rt| It is used to specify the degree by which the overlay text must be rotated. It accepts any number e.g. `45`, or `180` for a clockwise rotation, or any number preceded with `N` e.g. `N45`, or `N180`  for counter-clockwise rotation.
|fl| It is used to flip/mirror the text horizontally, vertically, or in both directions. eg. `fl-h`, `fl-v`, or `fl-h_v`.
| lh         | It is used to specify the line height(spacing) of the text. It will come into effect only if the text wraps over multiple lines. Accepts integer values representing line height in points. It can also accept arithmetic expressions such as `bw_mul_0.2`, or `bh_div_20`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).                                                                                                                                                                                                                                                                                                                                                                                             |

## Add solid color blocks over image
You can add a solid color block over a base image using the following example.

### Syntax for solid color block overlay

Use `i-ik_canvas` with the `bg` parameter to add a solid color block overlay on an image.

```markup
https://ik.imagekit.io/demo/base-image.jpg?tr=l-image,i-ik_canvas,bg-FF0000,w-300,h-100,l-end
```

{% linetabs %}
{% linetab title="Basic solid block" %}

For example, let's add a solid red color box on an image.

URL - [https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,bg-FF0000,w-300,h-100,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,bg-FF0000,w-300,h-100,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,bg-FF0000,w-300,h-100,l-end/medium_cafe_B1iTdD0C.jpg)

You can also control the position of the solid color overlay using `lx` and `ly` parameters. Learn more about [positional parameters](/transformations#position-of-layer).

{% /linetab %}

{% linetab title="Graident effect" %}

URL - [https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,bg-FF0000,w-300,h-100,e-gradient-from-lightskyblue_to-mintcream,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,bg-FF0000,w-300,h-100,e-gradient-from-lightskyblue_to-mintcream,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,bg-FF0000,w-300,h-100,e-gradient-from-lightskyblue_to-mintcream,l-end/medium_cafe_B1iTdD0C.jpg)

{% /linetab %}
{% /linetabs %}

## Control position of solid color overlay

You can control solid color layer position using the `lx`, `ly`, `lxc`, `lyc`, and `lap` parameters. To change the direction, negative values are also supported by prefixing the value with 'N'.

The `lx` and `ly` parameters position the layer using its top-left corner as the reference point. While the `lxc` and `lyc` parameters position the layer using its center as the reference point.

The `lap` (layer anchor point) parameter sets the anchor point on the base image from which the offset is calculated. By default, the anchor point is `top_left`. Possible values are: `top`, `left`, `right`, `bottom`, `top_left`, `top_right`, `bottom_left`, `bottom_right`, and `center`.

You can also use [arithmetic expressions](/arithmetic-expressions-in-transformations) in `lx`, `ly`, `lxc`, and `lyc` to better control the position of the overlay. Learn more about [positional parameters](/transformations#position-of-layer) in layers.

{% linetabs %}

{% linetab title="LX=35" %}
URL - [https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-200,h-200,bg-yellow,lx-35,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-200,h-200,bg-yellow,lx-35,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-200,h-200,bg-yellow,lx-35,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="LXC=135" %}
URL - [https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-200,h-200,bg-yellow,lxc-135,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-200,h-200,bg-yellow,lxc-135,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-200,h-200,bg-yellow,lxc-135,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="LX=N35 (Negative value)" %}
URL - [https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-200,h-200,bg-yellow,lx-N35,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-200,h-200,bg-yellow,lx-N35,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-200,h-200,bg-yellow,lx-N35,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="LXC, LYC and LAP" %}
URL - [https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-200,h-200,bg-yellow,lxc-135,lyc-N150,lap-bottom,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-200,h-200,bg-yellow,lxc-135,lyc-N150,lap-bottom,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-200,h-200,bg-yellow,lxc-135,lyc-N150,lap-bottom,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="LY=bh_mul_0.8" %}
Use the following URL to position the text near the bottom-left corner.

[https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-200,h-200,bg-yellow,ly-bh_mul_0.8,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-200,h-200,bg-yellow,ly-bh_mul_0.8,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-200,h-200,bg-yellow,ly-bh_mul_0.8,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="Multiple solid layers" %}
Use the following URL to position multiple solid layers appropriately. Here, we have also controlled the layer's width with the help of expressions.
 
[https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,ly-bh_mul_0.2,h-200,w-bh_div_2,bg-yellow,l-end:l-image,i-ik_canvas,w-bh_div_2,h-200,lx-bw_div_2,ly-bh_mul_0.2,bg-orange,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,ly-bh_mul_0.2,h-200,w-bh_div_2,bg-yellow,l-end:l-image,i-ik_canvas,w-bh_div_2,h-200,lx-bw_div_2,ly-bh_mul_0.2,bg-orange,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,ly-bh_mul_0.2,h-200,w-bh_div_2,bg-yellow,l-end:l-image,i-ik_canvas,w-bh_div_2,h-200,lx-bw_div_2,ly-bh_mul_0.2,bg-orange,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% /linetabs %}

## Apply transformation on solid color overlay

The following transformation parameters are supported on the solid color block overlay inside a layer.

| Parameter                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| w                                                                  | Width of solid color block. It can also accept arithmetic expressions such as `bw_div_2`, or `bw_mul_0.8`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).                                                                                                                                                                                                          |
| h                                                                  | Height of solid color block. It can also accept arithmetic expressions such as `bh_div_2`, or `bh_mul_0.8`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).                                                                                                                                                                                                         |
| [bg](/effects-and-enhancements#background---bg) | It is used to specify the color of the block in RGB Hex Code (e.g. `FF0000`), or an RGBA Code (e.g. `FFAABB50`), or a color name (e.g. `red`). If you specify an 8-character background, the last two characters must be a number between `00` and `99`, which indicates the opacity level of the background. `00` represents an opacity level of `0.00`, `01` represents an opacity level of `0.01`, and so on. |
| al                                                                 | It is used to specify the transparency level of the overlaid solid color layer. Supports integers from `1` to `9`.                                                                                                                                                                                                                                                                                              |
| [r](/effects-and-enhancements#radius---r)       | It is used to control the radius of the corner. To get a circle or oval shape, set the value to `max`.                                                                                                                                                                                                                                                                                                          |
| [e-gradient](/effects-and-enhancements#gradient---e-gradient)                                      | It is used to add a linear gradient overlay over an input image. The direction, from color, to color, and the stop point of the gradient can be varied using the following parameters - `ld`, `from`, `to` and `sp`. e.g. `e-gradient-<linear-direction>_<from-color>_<to-color>_<stop-point>` (or simply `e-gradient` to let the gradient take on default values). Learn more about the gradient effect and its parameters [here](/effects-and-enhancements#gradient---e-gradient). |

{% callout style="info" %}
If both `bg` and `al` are set in a single transformation and `bg` has an alpha component, then that value is used to set solid color background transparency. Otherwise, `al` value is used. If `bg` is set to a standard color name (e.g. `blue`), then the `al` value is ignored.
{% /callout %}

## Nest text and image layers inside canvas

A canvas layer (`i-ik_canvas`) can contain nested text and image child layers. This lets you build self-contained compositions — for example, a colored card with a heading and a product photo — all in a single overlay that can then be positioned on the base image.

Child layers are placed relative to the canvas, not the base image. Use `lfo` (relative focus) or `lx`/`ly`/`lxc`/`lyc`/`lap` (absolute coordinates) to position children within the canvas.

```markup
                                    Canvas layer with nested children
┌──────────────────────────────────────────────────────────────────────────────────────────┐
l-image,i-ik_canvas,w-600,h-200,bg-FF0000,r-20,l-text,i-Hello_World,fs-36,lfo-center,l-end,l-end
                                             └──────────────────┬─────────────────────┘
                                                  Nested text child inside the canvas
```

### Nested text layer in canvas

{% linetabs %}
{% linetab title="Text centered" %}
URL - [https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-120,bg-00FFFF,l-text,i-Centered_Text,fs-24,lfo-center,l-end,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-120,bg-00FFFF,l-text,i-Centered_Text,fs-24,lfo-center,l-end,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-120,bg-00FFFF,l-text,i-Centered_Text,fs-24,lfo-center,l-end,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="Text with lx, ly" %}
URL - [https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-120,bg-00FF00,l-text,i-Positioned,lx-50,ly-30,l-end,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-120,bg-00FF00,l-text,i-Positioned,lx-50,ly-30,l-end,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-120,bg-00FF00,l-text,i-Positioned,lx-50,ly-30,l-end,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="Multiple text layers" %}
URL - [https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-120,bg-FF0000,l-text,i-Top,lfo-top,l-end:l-text,i-Bottom,lfo-bottom,l-end,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-120,bg-FF0000,l-text,i-Top,lfo-top,l-end:l-text,i-Bottom,lfo-bottom,l-end,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-120,bg-FF0000,l-text,i-Top,lfo-top,l-end:l-text,i-Bottom,lfo-bottom,l-end,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}
{% /linetabs %}

### Nested image layer in canvas

{% linetabs %}
{% linetab title="Image centered" %}
URL - [https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-400,bg-FF0000,l-image,i-example_food_3.jpg,w-200,h-150,lfo-center,l-end,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-400,bg-FF0000,l-image,i-example_food_3.jpg,w-200,h-150,lfo-center,l-end,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-400,bg-FF0000,l-image,i-example_food_3.jpg,w-200,h-150,lfo-center,l-end,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="Image with lx, ly" %}
URL - [https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-400,bg-FFFF00,l-image,i-example_food_3.jpg,w-200,h-150,lx-100,ly-80,l-end,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-400,bg-FFFF00,l-image,i-example_food_3.jpg,w-200,h-150,lx-100,ly-80,l-end,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-400,bg-FFFF00,l-image,i-example_food_3.jpg,w-200,h-150,lx-100,ly-80,l-end,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="Multiple image layers" %}
URL - [https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-400,bg-CCCCCC,l-image,i-example_food_3.jpg,w-150,h-100,lfo-top_left,l-end:l-image,i-example_food_3.jpg,w-150,h-100,lfo-bottom_right,l-end,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-400,bg-CCCCCC,l-image,i-example_food_3.jpg,w-150,h-100,lfo-top_left,l-end:l-image,i-example_food_3.jpg,w-150,h-100,lfo-bottom_right,l-end,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-400,bg-CCCCCC,l-image,i-example_food_3.jpg,w-150,h-100,lfo-top_left,l-end:l-image,i-example_food_3.jpg,w-150,h-100,lfo-bottom_right,l-end,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}
{% /linetabs %}

### Mixed text and image layers in canvas

{% linetabs %}
{% linetab title="Image + text caption" %}
URL - [https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-400,bg-FF0000,l-image,i-example_food_3.jpg,w-200,h-150,lfo-center,l-end:l-text,i-Caption,fs-24,co-FFFFFF,lfo-bottom,l-end,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-400,bg-FF0000,l-image,i-example_food_3.jpg,w-200,h-150,lfo-center,l-end:l-text,i-Caption,fs-24,co-FFFFFF,lfo-bottom,l-end,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-400,bg-FF0000,l-image,i-example_food_3.jpg,w-200,h-150,lfo-center,l-end:l-text,i-Caption,fs-24,co-FFFFFF,lfo-bottom,l-end,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="Text header + image" %}
URL - [https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-400,bg-333333,l-text,i-Header,fs-28,co-FFFFFF,lfo-top,l-end:l-image,i-example_food_3.jpg,w-200,h-150,lfo-bottom,l-end,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-400,bg-333333,l-text,i-Header,fs-28,co-FFFFFF,lfo-top,l-end:l-image,i-example_food_3.jpg,w-200,h-150,lfo-bottom,l-end,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-400,bg-333333,l-text,i-Header,fs-28,co-FFFFFF,lfo-top,l-end:l-image,i-example_food_3.jpg,w-200,h-150,lfo-bottom,l-end,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}
{% /linetabs %}

### Canvas with rounded corners, transparency, or gradient

{% linetabs %}
{% linetab title="Rounded canvas with text" %}
URL - [https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-120,bg-FF0000,r-20,l-text,i-Rounded,lfo-center,l-end,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-120,bg-FF0000,r-20,l-text,i-Rounded,lfo-center,l-end,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-120,bg-FF0000,r-20,l-text,i-Rounded,lfo-center,l-end,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="Semi-transparent canvas with text" %}
URL - [https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-120,bg-FF000080,l-text,i-Transparent,co-FFFFFF,lfo-center,l-end,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-120,bg-FF000080,l-text,i-Transparent,co-FFFFFF,lfo-center,l-end,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-120,bg-FF000080,l-text,i-Transparent,co-FFFFFF,lfo-center,l-end,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="Circular canvas with text" %}
URL - [https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-400,h-400,bg-FF00FF,r-max,l-text,i-Circle,co-FFFFFF,lfo-center,l-end,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-400,h-400,bg-FF00FF,r-max,l-text,i-Circle,co-FFFFFF,lfo-center,l-end,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-400,h-400,bg-FF00FF,r-max,l-text,i-Circle,co-FFFFFF,lfo-center,l-end,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}

{% linetab title="Gradient canvas with text" %}
URL - [https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-120,bg-FF0000,e-gradient-from-00FF00_to-0000FF,l-text,i-Gradient_Text,lfo-center,l-end,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-120,bg-FF0000,e-gradient-from-00FF00_to-0000FF,l-text,i-Gradient_Text,lfo-center,l-end,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,w-500,h-120,bg-FF0000,e-gradient-from-00FF00_to-0000FF,l-text,i-Gradient_Text,lfo-center,l-end,l-end/medium_cafe_B1iTdD0C.jpg)
{% /linetab %}
{% /linetabs %}

## Supported text font list

ImageKit.io currently supports the following fonts out of the box.

| Font         | Support for Bold |  Support for Italics |  Support for Strikethrough |
| ------------ | ---------------- | -------------------- | -------------------------- |
| AbrilFatFace | No               | No                   | Yes                        |
| Amaranth     | Yes              | Yes                  | Yes                        |
| Arvo         | Yes              | Yes                  | Yes                        |
| Audiowide    | No               | No                   | Yes                        |
| Chivo        | Yes              | Yes                  | Yes                        |
| Crimson Text | Yes              | Yes                  | Yes                        |
| exo          | Yes              | Yes                  | Yes                        |
| Fredoka One  | No               | No                   | Yes                        |
| Gravitas One | No               | No                   | Yes                        |
| Kanit        | Yes              | Yes                  | Yes                        |
| Lato         | Yes              | Yes                  | Yes                        |
| Lobster      | No               | No                   | Yes                        |
| Lora         | Yes              | Yes                  | Yes                        |
| Monoton      | No               | No                   | Yes                        |
| Montserrat   | Yes              | Yes                  | Yes                        |
| PT Mono      | No               | No                   | Yes                        |
| PT_Serif     | Yes              | Yes                  | Yes                        |
| Open Sans    | Yes              | Yes                  | Yes                        |
| Roboto       | Yes              | Yes                  | Yes                        |
| Old Standard | Yes              | Yes                  | Yes                        |
| Ubuntu       | Yes              | Yes                  | Yes                        |
| Vollkorn     | Yes              | Yes                  | Yes                        |

Besides this you can use any custom font by uploading the font file in your media library and passing its path in the `ff` parameter in a text layer. See custom font example [here](#change-font-family-in-text-overlay).

## Layer modes

By default, layers completely cover the base image beneath them. Layer modes change this behavior by controlling how the layer blends with the base image, enabling sophisticated visual effects like darkening, distortion, transparency masking, and shape cutting.

Four layer modes are available: **multiply** (darkening effect), **displacement** (pixel distortion using a map), **cutout** (inverse transparency mask), and **cutter** (shape mask). Each mode is demonstrated below with examples.

### Displacement

This layer mode uses a displacement map as the layer input to create a displacement of the pixels in the base image. The displacement map's pixel values control the extent and direction of displacement of the pixels in the base image. Either the `x` or `y` transformation parameter is required within the layer for this layer mode to work. A combination of the `x`/`y` values and the red/green channel values of the input image pixels dictate how a pixel will get displaced.

The displacement works as follows: the red channel of the displacement map controls horizontal displacement, while the green channel controls vertical displacement. For each pixel in the base image, the corresponding pixel in the displacement map is examined. The red channel value (ranging from 0-255) determines how far the pixel moves horizontally, and the green channel value determines vertical movement. A channel value of 128 represents no displacement, values below 128 cause displacement in the negative direction (left or up), and values above 128 cause displacement in the positive direction (right or down). The `x` and `y` parameters control the maximum possible magnitude of the displacement — higher values result in more dramatic displacement effects.

Syntax - `l-image,i-<displacement_map.jpg>,lm-displace,x-<num>,y-<num>,l-end`

{% linetabs %}

{% linetab title="Base image" %}

URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg)

![](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg)

{% /linetab %}

{% linetab title="Displaced image" %}

URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=l-image,i-radialize.jpeg,lm-displace,y-100,l-end](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=l-image,i-radialize.jpeg,lm-displace,y-100,l-end)

![](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=l-image,i-radialize.jpeg,lm-displace,y-100,l-end)

{% /linetab %}

{% /linetabs %}

### Multiply

This layer mode applies the multiply blend mode to combine the two images where the pixel values of both the images are multiplied with each other to produce a new set of values. The layer area in the output will be darker than both the base image or the layer image. For text layers, the layer image is the image generated by the given text with the transformations applied on it.

Syntax -
* Image layer: `l-image,i-<layer_image.jpg>,lm-multiply,l-end`
* Text layer: `l-text,i-<string of text>,lm-multiply,l-end`

{% linetabs %}

{% linetab title="Base image" %}

URL - [https://ik.imagekit.io/demo/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/medium_cafe_B1iTdD0C.jpg)

{% /linetab %}

{% linetab title="Text layer using multiply" %}

URL - [https://ik.imagekit.io/demo/tr:l-text,i-TEXT,fs-80,lm-multiply,co-cyan,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-text,i-TEXT,fs-80,lm-multiply,co-cyan,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-text,i-TEXT,fs-80,lm-multiply,co-cyan,l-end/medium_cafe_B1iTdD0C.jpg)

{% /linetab %}

{% linetab title="Text layer without multiply" %}

URL - [https://ik.imagekit.io/demo/tr:l-text,i-TEXT,fs-80,co-cyan,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-text,i-TEXT,fs-80,co-cyan,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-text,i-TEXT,fs-80,co-cyan,l-end/medium_cafe_B1iTdD0C.jpg)

{% /linetab %}

{% /linetabs %}

### Cutout

This layer mode creates a "cutout" in the base image using the transparency values in the layer image. In the place of pixels where the layer image is opaque, the output will have transparency, and in the place of pixels where the layer image is transparent, the output will have the pixels from the base image unchanged. For text layers, the layer image is the image generated by the given text with the transformations applied on it.

Syntax -
* Image layer: `l-image,i-<layer_image.jpg>,lm-cutout,l-end`
* Text layer: `l-text,i-<string of text>,lm-cutout,l-end`

Example URL - [https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,lm-cutout,l-end:bg-indigo/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,lm-cutout,l-end:bg-indigo/medium_cafe_B1iTdD0C.jpg)

Using `bg-indigo` to show transparency effect clearly.

![](https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,lm-cutout,l-end:bg-indigo/medium_cafe_B1iTdD0C.jpg)

### Cutter

This layer mode creates transparency in the areas where the layer image is also transparent, while keeping the areas where the layer image is opaque unchanged. The dimensions of the output image will match those of the layer image. For text layers, the layer image is the image generated by the given text with the transformations applied on it.

Syntax -
* Image layer: `l-image,i-<layer_image.jpg>,lm-cutter,l-end`
* Text layer: `l-text,i-<string of text>,lm-cutter,l-end`

Example URL - [https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,lm-cutter,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,lm-cutter,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,lm-cutter,l-end/medium_cafe_B1iTdD0C.jpg)


---

# Source: /ai-transformations

---
title: AI Transformations (beta)
description: Learn how to remove or change background, drop shadow around objects, generate images from text, upscale images, and more with AI transformations.
---

ImageKit provides easy-to-use URL-based transformation parameters to perform various AI transformations on images. These transformations are powered by AI models and can be used to perform tasks like background removal, drop shadow, retouching, upscaling, object-aware cropping, generating an image via a text prompt, generating variations of an image, etc.

For example, to remove the background from an image, you can use the `tr=e-removedotbg` transformation parameter in the URL. Here is an example URL:

```
https://ik.imagekit.io/ikmedia/blue-bmw.jpg?tr=e-removedotbg
```

## Limitations and considerations

1. Except `fo-face`, `fo-auto` and object-aware cropping, all AI transformations are currently in beta.
2. AI transformations typically take longer to process compared to basic transformations. The response time can range from a few seconds to a minute, depending on the complexity of the transformation. If the transformation takes longer, ImageKit may return an intermediate HTML response with the message `The asset is currently being prepared` and a `200` status code. In this case, a special response header `is-intermediate-response:true` is included. You can use this header to identify intermediate responses and handle them appropriately.
3. Only one such async operation will be allowed in a single transformation in a chain of transformations. If you want to apply multiple AI transformations, you can [chain them together](/transformations#chained-transformations) using a colon (:) separator. \
  `tr:e-removedotbg,h-100:e-dropshadow` - ✅  (e-dropshadow is separated by a colon) \
  `tr:e-removedotbg,h-200,e-dropshadow` - ❌  (e-dropshadow is separated by a comma)
1. If a request fails due to any reason, the error response on the corresponding URL is cached for a short duration. You should wait for a few minutes before ImageKit accepts and initiates a new request on the same URL. [Learn about](/transformations#troubleshooting-invalid-transformation) error troubleshooting.
2. Most of these transformations cannot be used inside [layers](/transformations#overlay-using-layers), with the exception of `e-removedotbg`, and `e-dropshadow`.
3. The outputs of AI transformations are cached forever to prevent redundant utilization of your extension credits. [Purging](/cdn-caching-and-purging#purging-the-cache) the cache for a URL will still delete all cache entries for that URL. Also, changing any of the image settings via your dashboard (default quality, auto-format, device-based resize, auto-rotation, chroma subsampling, preserve metadata, PNG compression) may invalidate existing cache entries.
4. The [Restrict Unsigned URLs](/media-delivery-basic-security#restrict-unsigned-urls) setting can be toggled on or off specifically for AI transformations. It will be turned off by default so you can easily try these transformations out. However, we strongly recommend turning it on for production use cases to prevent unauthorized access to your AI transformations.

## Pricing

Using AI transformations consumes extension units. Different AI transformations consume different amounts of extension units as per your pricing plan.

You can access the [full list of extensions and the extension units they consume](/docs/how-pricing-works#extension-units-pricing) here.

{% callout style="info" %}
**Maximum limit on extension usage** \
There is a maximum limit on how many extension units you can consume in a month. For free plans, the limit is [650 units](https://imagekit.io/plans/). For paid plans, refer to the [subscription details](https://imagekit.io/dashboard/billing/subscriptions) in the dashboard.
{% /callout %}

## Background removal (e-removedotbg)

Remove the background from an image using the `e-removedotbg` transformation parameter.

You can use `e-removedotbg` inside image overlay layers in image requests.

Syntax: `e-removedotbg`

Here is an example [URL](https://ik.imagekit.io/ikmedia/blue-bmw.jpg?tr=e-removedotbg).

{% compareimages caption="Remove background" first="https://ik.imagekit.io/ikmedia/blue-bmw.jpg" second="https://ik.imagekit.io/ikmedia/blue-bmw.jpg?tr=e-removedotbg" /%}

You can also use the `e-removedotbg` transformation parameter in chained transformations. For example, to add a drop shadow after removing the background, you can chain transformations like this:

{% compareimages caption="Remove background and add a drop shadow" first="https://ik.imagekit.io/ikmedia/blue-bmw.jpg" second="https://ik.imagekit.io/ikmedia/blue-bmw.jpg?tr=e-removedotbg:e-dropshadow" /%}

## ImageKit background removal (e-bgremove)

Remove the background from an image using the `e-bgremove` transformation parameter. Using `e-bgremove` is very cost efficient **(around 1/10-th the price)** compared to the `e-removedotbg` transformation.

You can use `e-bgremove` inside image overlay layers in image requests.

Syntax: `e-bgremove`

Here is an example [URL](https://ik.imagekit.io/ikmedia/blue-bmw.jpg?tr=e-bgremove).

{% compareimages caption="Remove background" first="https://ik.imagekit.io/ikmedia/blue-bmw.jpg" second="https://ik.imagekit.io/ikmedia/blue-bmw.jpg?tr=e-bgremove" /%}

You can also use the `e-bgremove` transformation parameter in chained transformations. For example, to add a drop shadow after removing the background, you can chain transformations like this:

{% compareimages caption="Remove background and add a drop shadow" first="https://ik.imagekit.io/ikmedia/blue-bmw.jpg" second="https://ik.imagekit.io/ikmedia/blue-bmw.jpg?tr=e-bgremove:e-dropshadow" /%}

## Change background (e-changebg)

Easily transform the background of an image by providing a descriptive text prompt.

Syntax - Use one of the following formats to apply the transformation:

- **Direct Text Prompt:**  
  `e-changebg-prompt-${text}`  
- **Base64 URL-Encoded Text Prompt:**  
  `e-changebg-prompte-${urlencoded_base64_encoded_text}`

### Using a Text Prompt
   To replace the background with a snowy scene add `tr=e-changebg-prompt-snow road` to the [URL](https://ik.imagekit.io/ikmedia/ferrari.jpg?tr=e-changebg-prompt-snow%20road).

   {% compareimages caption="Add a snow road background" first="https://ik.imagekit.io/ikmedia/ferrari.jpg" second="https://ik.imagekit.io/ikmedia/ferrari.jpg?tr=e-changebg-prompt-snow%20road" /%}

### Using a Base64 URL-Encoded String
   For more advanced usage, you can use a Base64 URL-encoded string to describe the background. For example, to set the background to a racing track:

   > `cmFjaW5nIHRyYWNr` is the Base64 URL-encoded representation of the text `racing track`.

   {% compareimages caption="Add a racing track background" first="https://ik.imagekit.io/ikmedia/ferrari.jpg" second="https://ik.imagekit.io/ikmedia/ferrari.jpg?tr=e-changebg-prompte-cmFjaW5nIHRyYWNr" /%}


{% callout style="info" %}
**Note** \
We’ve partnered with [Photoroom](https://photoroom.com) to bring you seamless background-changing capabilities.
[![;nozoom;noborder;width=150](https://ik.imagekit.io/ikmedia/photoroom-logo.png?tr=r-20)](https://photoroom.com)
{% /callout %}

### Customizing Size and Position

You can also adjust the size and position of the subject in the foreground while changing the background. Here's an example using a [shampoo bottle image](https://ik.imagekit.io/ikmedia/shampoo.jpg).

1. **Resizing and Repositioning**  
   First, resize the image and place the subject in the top-right corner of the canvas with a neutral background color (`#CCCCCC`):

   ![Placed shampoo bottle on top right](<https://ik.imagekit.io/ikmedia/shampoo.jpg?tr=h-200:w-1200,h-200,cm-pad_resize,fo-right,bg-CCCCCC:w-1200,h-600,cm-pad_resize,bg-CCCCCC,fo-top>)

2. **Changing the Background**  
   Next, replace the neutral background with a more engaging scene, like a bathroom, to enhance the visual appeal. Add `e-changebg-prompt-bathroom` to the [URL](https://ik.imagekit.io/ikmedia/shampoo.jpg?tr=h-200:w-1200,h-200,cm-pad_resize,fo-right,bg-CCCCCC:w-1200,h-600,cm-pad_resize,bg-CCCCCC,fo-top:e-changebg-prompt-bathroom).

   ![Put the bottle in a bathroom](<https://ik.imagekit.io/ikmedia/shampoo.jpg?tr=h-200:w-1200,h-200,cm-pad_resize,fo-right,bg-CCCCCC:w-1200,h-600,cm-pad_resize,bg-CCCCCC,fo-top:e-changebg-prompt-bathroom>)

## Edit image (e-edit)

Modify the contents of an image using the `e-edit` transformation by providing a descriptive text prompt. The output image dimensions will be 1024x1024 if the input image is square. Otherwise, the output image dimensions will be one of 1536x1024 or 1024x1536, depending on which side is longer in the input image. To fit the image into one of those two exact dimensions, the shorter side of the input image will be padded with appropriate content seamlessly.

Syntax - Use one of the following formats to apply the transformation:

- **Direct Text Prompt:**  
  `e-edit-prompt-${text}`  
- **Base64 URL-Encoded Text Prompt:**  
  `e-edit-prompte-${urlencoded_base64_encoded_text}`

### Using a text prompt
  Let's add `tr=e-edit-prompt-add some flair to this plain cake` to this image of a cake:

  {% compareimages caption="Add some flair to this plain cake" first="https://ik.imagekit.io/ikmedia/docs_images/examples/cake.png" second="https://ik.imagekit.io/ikmedia/docs_images/examples/cake.png?tr=e-edit-prompt-add%20some%20flair%20to%20this%20plain%20cake" /%}

### Using a base64-encoded text prompt
  Use this method if your prompt text contains special characters like `/`, `:`, `,`. Let's base64-encode the prompt "make the seawater blue" and add it to this image of a beach. Remember to also percent-encode the base64 string. The final transformation string will be `tr=e-edit-prompte-bWFrZSB0aGUgc2Vhd2F0ZXIgYmx1ZQo%3D`.

  {% compareimages caption="Make the seawater blue" first="https://ik.imagekit.io/ikmedia/docs_images/examples/beach2.webp" second="https://ik.imagekit.io/ikmedia/docs_images/examples/beach2.webp?tr=e-edit-prompte-bWFrZSB0aGUgc2Vhd2F0ZXIgYmx1ZQo%3D" /%}

## Generative fill (bg-genfill)

`bg-genfill` transformation extends an image beyond its original boundaries, allowing you to add new visual elements in an image while preserving the original image content.

Syntax: `bg-genfill[:-prompt-${text}]` or `bg-genfill[:-prompte-${urlencoded_base64_encoded_text}]`

It must be used with `height`, `width`, and either the [`pad_resize`](/image-resize-and-crop#pad-resize-crop-strategy---cm-pad_resize) or [`pad_extract`](/image-resize-and-crop#pad-extract-crop-strategy---cm-pad_extract) crop strategy.

Here is an example URL:

{% linetabs %}
{% linetab title="Extend width to 1000px" %}
[https://ik.imagekit.io/ikmedia/footwear.jpg?tr=bg-genfill,w-1000,h-960,cm-pad_resize](https://ik.imagekit.io/ikmedia/footwear.jpg?tr=bg-genfill,w-1000,h-960,cm-pad_resize)

![Generative fill](https://ik.imagekit.io/ikmedia/footwear.jpg?tr=bg-genfill,w-1000,h-960,cm-pad_resize)

{% /linetab %}

{% linetab title="Original 640px wide image" %}
[https://ik.imagekit.io/ikmedia/footwear.jpg](https://ik.imagekit.io/ikmedia/footwear.jpg)

![Original 640px wide image](<https://ik.imagekit.io/ikmedia/footwear.jpg>)

{% /linetab %}
{% /linetabs %}

You can also provide a text prompt to control the generative fill. 

[https://ik.imagekit.io/ikmedia/footwear.jpg?tr=bg-genfill-prompt-flowers,w-1000,h-960,cm-pad_resize](https://ik.imagekit.io/ikmedia/footwear.jpg?tr=bg-genfill-prompt-flowers,w-1000,h-960,cm-pad_resize)

![Generative fill](https://ik.imagekit.io/ikmedia/footwear.jpg?tr=bg-genfill-prompt-flowers,w-1000,h-960,cm-pad_resize)

## AI drop shadow (e-dropshadow)

Add a drop shadow around an object in an image using the `e-dropshadow` transformation parameter. You can control the direction, elevation, and saturation of the light source.

Syntax: `e-dropshadow[:-az-${0-360}][:_el-${0-90}][:_st-${0-100}]`

- **`az` (Azimuth)**: This represents the angle of the light source. A value of `0` or `360` indicates the light is directly behind the object. The default value is `215`, which creates a natural shadow effect.
- **`el` (Elevation)**: This refers to the elevation angle of the light source above the ground. The default value is `45`. Lowering this value results in a larger, more diffused shadow.
- **`st` (Saturation)**: This controls the intensity of the shadow. Higher values produce a more intense or darker shadow. The default value for the `st` parameter is `60`.

{% callout style="info" %}
**Note** \
To apply a drop shadow, the image must have a transparent background. Use the `e-removedotbg` transformation to remove the background before adding the drop shadow with chained transformations. For example: `tr=e-removedotbg:e-dropshadow`.
{% /callout %}

Examples:

{% linetabs %}
{% linetab title="AI drop shadow" %}

[https://ik.imagekit.io/demo/lipstick_1M.png?tr=e-dropshadow](https://ik.imagekit.io/demo/lipstick_1M.png?tr=e-dropshadow)

![AI drop shadow](https://ik.imagekit.io/demo/lipstick_1M.png?tr=e-dropshadow)

{% /linetab %}

{% linetab title="Change light source direction" %}

[https://ik.imagekit.io/demo/lipstick_1M.png?tr=e-dropshadow-az-45](https://ik.imagekit.io/demo/lipstick_1M.png?tr=e-dropshadow-az-45)

![Change AI drop shadow light source direction](https://ik.imagekit.io/demo/lipstick_1M.png?tr=e-dropshadow-az-45)

{% /linetab %}

{% linetab title="Normal shadow effect" %}

[https://ik.imagekit.io/demo/lipstick_1M.png?tr=e-shadow](https://ik.imagekit.io/demo/lipstick_1M.png?tr=e-shadow)

Using [`e-shadow`](/effects-and-enhancements#shadow---e-shadow) parameter.

![Non-AI shadow effect](https://ik.imagekit.io/demo/lipstick_1M.png?tr=e-shadow)

{% /linetab %}

{% linetab title="Original product image" %}

[https://ik.imagekit.io/demo/lipstick_1M.png](https://ik.imagekit.io/demo/lipstick_1M.png)

![Original product image](https://ik.imagekit.io/demo/lipstick_1M.png)
{% /linetab %}

{% /linetabs %}

## Retouch (e-retouch)

Improve the quality of an image using the `e-retouch` transformation parameter. The input image's resolution must be less than 16 MP.

Syntax: `e-retouch`

Here is an example [URL](https://ik.imagekit.io/ikmedia/low-quality.jpg?tr=e-retouch).

{% compareimages caption="Improved quality" first="https://ik.imagekit.io/ikmedia/low-quality.jpg" second="https://ik.imagekit.io/ikmedia/low-quality.jpg?tr=e-retouch"  /%}

## Upscale (e-upscale)

Increase the resolution of an image using the `e-upscale` transformation parameter. The input image's resolution must be less than 16 MP. The output image's resolution will be 16 MP.

Syntax: `e-upscale`

Here is an example URL:

{% linetabs %}
{% linetab title="Upscaled to 2500px" %}

[https://ik.imagekit.io/ikmedia/low-res-demo.jpg?tr=e-upscale](https://ik.imagekit.io/ikmedia/low-res-demo.jpg?tr=e-upscale)

![Upscaled image](https://ik.imagekit.io/ikmedia/low-res-demo.jpg?tr=e-upscale)

{% /linetab %}

{% linetab title="Original 275px wide" %}

[https://ik.imagekit.io/ikmedia/low-res-demo.jpg](https://ik.imagekit.io/ikmedia/low-res-demo.jpg)

![Original 275px wide](https://ik.imagekit.io/ikmedia/low-res-demo.jpg)

{% /linetab %}
{% /linetabs %}


## Generate image via text prompt

You can generate an image based on a text prompt. The text prompt can simply describe the image you want to generate.

Syntax: `{URL_ENDPOINT}/ik-genimg[:-prompt-${text}]/...filepath.../filename.extension`

Here `filepath` and `filename.extension` is up to you to decide. Once the image is generated, it will be accessible at the provided path. Changing the text prompt on the same path will not generate a new image. To generate another image, either purge the cache for this path, change the `filepath` or `filename`, or append a random query parameter to the URL.

Examples:

{% linetabs %}

{% linetab title="A man eating a burger" %}

[https://ik.imagekit.io/ikmedia/ik-genimg-prompt-A man eating a burger/gen-burger-image.jpg](<https://ik.imagekit.io/ikmedia/ik-genimg-prompt-A man eating a burger/gen-burger-image.jpg>)

![A man eating a burger](<https://ik.imagekit.io/ikmedia/ik-genimg-prompt-A man eating a burger/gen-burger-image.jpg>)

{% /linetab %}

{% linetab title="Another version" %}

If you don't like the generated image, you can append a random query parameter to the URL or choose a different file path and name to generate a new image.

[https://ik.imagekit.io/ikmedia/ik-genimg-prompt-A man eating a burger/gen-burger-image.jpg?v=3](<https://ik.imagekit.io/ikmedia/ik-genimg-prompt-A man eating a burger/gen-burger-image.jpg?v=3>)

![A man eating a burger](<https://ik.imagekit.io/ikmedia/ik-genimg-prompt-A man eating a burger/gen-burger-image.jpg?v=3>)

{% /linetab %}


{% linetab title="A woman wearing a red top" %}

[https://ik.imagekit.io/ikmedia/ik-genimg-prompt-A woman wearing red top/gen-woman-red-top.jpg](<https://ik.imagekit.io/ikmedia/ik-genimg-prompt-A woman wearing red top/gen-woman-red-top.jpg>)

![A woman wearing a red top](<https://ik.imagekit.io/ikmedia/ik-genimg-prompt-A woman wearing red top/gen-woman-red-top.jpg>)

{% /linetab %}
{% /linetabs %}

You can use any other [image transformation](/image-transformation) parameter along with `ik-genimg` to modify the generated image further.

For example, remove the background from the generated image and resize it down to 500px width:

[https://ik.imagekit.io/ikmedia/ik-genimg-prompt-A man eating a burger/gen-burger-image.jpg?tr=e-removedotbg,w-500](<https://ik.imagekit.io/ikmedia/ik-genimg-prompt-A man eating a burger/gen-burger-image.jpg?tr=e-removedotbg,w-500>)

![Remove background and resize](<https://ik.imagekit.io/ikmedia/ik-genimg-prompt-A man eating a burger/gen-burger-image.jpg?tr=e-removedotbg,w-500>)

Let's add a text overlay layer on the generated image:

[https://ik.imagekit.io/ikmedia/ik-genimg-prompt-A%20woman%20wearing%20red%20top/gen-woman-red-top.jpg?tr=w-500,l-text,i-30%%20off,fs-45,lfo-top_left,pa-10,bg-white,l-end](<https://ik.imagekit.io/ikmedia/ik-genimg-prompt-A%20woman%20wearing%20red%20top/gen-woman-red-top.jpg?tr=w-500,l-text,i-30%%20off,fs-45,lfo-top_left,pa-10,bg-white,l-end>)

![Text overlay on generated image](<https://ik.imagekit.io/ikmedia/ik-genimg-prompt-A%20woman%20wearing%20red%20top/gen-woman-red-top.jpg?tr=w-500,l-text,i-30%%20off,fs-45,lfo-top_left,pa-10,bg-white,l-end>)

## Generate variations of an image (e-genvar)

If you have an image and want to generate variations of it, you can use the `e-genvar` transformation parameter. This will generate a new image with slight variations from the original image. The variations include changes in color, texture, and other visual elements. However, the model will try to preserve the structure and essence of the original image.

Syntax: `e-genvar`

Here is an example URL:

{% linetabs %}
{% linetab title="Variation" %}

[https://ik.imagekit.io/ikmedia/coffee-machine.jpg?tr=w-600,h-400:e-genvar](https://ik.imagekit.io/ikmedia/coffee-machine.jpg?tr=w-600,h-400:e-genvar)

![Variation](https://ik.imagekit.io/ikmedia/coffee-machine.jpg?tr=w-600,h-400:e-genvar)

{% /linetab %}

{% linetab title="Another variation" %}

If you don't like the variation, you can append a random query parameter to the URL to generate another variation.

[https://ik.imagekit.io/ikmedia/coffee-machine.jpg?tr=w-600,h-400:e-genvar&v=3](https://ik.imagekit.io/ikmedia/coffee-machine.jpg?tr=w-600,h-400:e-genvar&v=3)

![Another variation](https://ik.imagekit.io/ikmedia/coffee-machine.jpg?tr=w-600,h-400:e-genvar&v=3)

{% /linetab %}

{% linetab title="Original image" %}

[https://ik.imagekit.io/ikmedia/coffee-machine.jpg?tr=w-600,h-400](https://ik.imagekit.io/ikmedia/coffee-machine.jpg?tr=w-600,h-400)

![Original image](https://ik.imagekit.io/ikmedia/coffee-machine.jpg?tr=w-600,h-400)

{% /linetab %}
{% /linetabs %}

## Object aware cropping

For more details, refer to the [object-aware cropping documentation](/image-resize-and-crop#object-aware-cropping---fo-object-name).

We can also crop out a particular object of interest out of multiple different objects present in an image.

{% linetabs %}
{% linetab title="Original" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg)

![Original 600x336 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg)
{% /linetab %}

{% linetab title="Cropping dog" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg?tr=fo-dog](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg?tr=fo-dog)

![292x322 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg?tr=fo-dog)

The output is an image containing just the dog.
{% /linetab %}

{% linetab title="Cropping cat" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg?tr=fo-cat](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg?tr=fo-cat)

![119x169 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg?tr=fo-cat)

The output is an image containing just the cat.
{% /linetab %}

{% linetab title="Cropping dog with aspect ratio" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg?tr=fo-dog,ar-1_1](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg?tr=fo-dog,ar-1_1)

![322x322 image](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/catdog.jpeg?tr=fo-dog,ar-1_1)

The output is a square image containing the dog by adding extra `width` as required.
{% /linetab %}
{% /linetabs %}

## Face crop

Crop an image based on the detected face using the [`fo-face`](/image-resize-and-crop#face-cropping---fo-face) transformation parameter. Optionally, zoom in or out using the [`z`](/image-resize-and-crop#zoom---z) parameter.

[https://ik.imagekit.io/ikmedia/tr:w-150,h-150,fo-face/docs_images/examples/example_portrait_1.jpg](https://ik.imagekit.io/ikmedia/tr:w-150,h-150,fo-face/docs_images/examples/example_portrait_1.jpg?updatedAt=1703135626910)

![Face crop (fo-face)](<https://ik.imagekit.io/ikmedia/tr:w-150,h-150,fo-face/docs_images/examples/example_portrait_1.jpg?updatedAt=1703135626910>)

## Smart crop

Automatically focus on the most important part of an image using the [`fo-auto`](/image-resize-and-crop#auto-smart-cropping---fo-auto) transformation parameter.

[https://ik.imagekit.io/ikmedia/tr:w-200,h-300,fo-auto/docs_images/examples/Smart_crop_example.jpg](https://ik.imagekit.io/ikmedia/tr:w-200,h-300,fo-auto/docs_images/examples/Smart_crop_example.jpg)

This is what the final result looks like with smart crop auto mode. The main subject is right in the center of the final thumbnail.

![Smart crop (fo-auto)](<https://ik.imagekit.io/ikmedia/tr:w-200,h-300,fo-auto/docs_images/examples/Smart_crop_example.jpg>)


---

# Source: /effects-and-enhancements

---
title: Effects and Enhancements
description: Learn how to enhance images using ImageKit.io URL-based image transformation API.
---

## Contrast stretch - (e-contrast)

It is used to automatically enhance the contrast of the image by using the full intensity values that a particular image format allows. This means that the lighter sections of an image become even lighter and the darker sections become even brighter, thereby enhancing the contrast.

{% linetabs %}
{% linetab title="Original" %}
URL - [https://ik.imagekit.io/demo/tr:h-300/sample_image.jpg](https://ik.imagekit.io/demo/tr:h-300/sample_image.jpg)

![](https://ik.imagekit.io/demo/tr:h-300/sample_image.jpg)
{% /linetab %}

{% linetab title="With e-contrast" %}
URL - [https://ik.imagekit.io/demo/tr:h-300,e-contrast/sample_image.jpg](https://ik.imagekit.io/demo/tr:h-300,e-contrast/sample_image.jpg)

![](https://ik.imagekit.io/demo/tr:h-300,e-contrast/sample_image.jpg)
{% /linetab %}
{% /linetabs %}

## Sharpen - (e-sharpen)

It is used to sharpen the input image. It is useful when highlighting the edges and finer details within an image. 

Example usage - `e-sharpen-<number>`

If just the e-sharpen  parameter is used, then a default sharpening is performed on the input image. The default behavior can be controlled by specifying a number that restricts the extent of sharpening performed.

{% linetabs %}
{% linetab title="No sharpening" %}
URL - [https://ik.imagekit.io/demo/tr:h-300/sample_image.jpg](https://ik.imagekit.io/demo/tr:h-300/sample_image.jpg)

![](https://ik.imagekit.io/demo/tr:h-300/sample_image.jpg)
{% /linetab %}

{% linetab title="Default e-sharpen" %}
URL - [https://ik.imagekit.io/demo/tr:e-sharpen,h-300/sample_image.jpg](https://ik.imagekit.io/demo/tr:e-sharpen,h-300/sample_image.jpg)

![](https://ik.imagekit.io/demo/tr:e-sharpen,h-300/sample_image.jpg)
{% /linetab %}

{% linetab title="e-sharpen=10" %}
URL - [https://ik.imagekit.io/demo/tr:e-sharpen-10,h-300/sample_image.jpg](https://ik.imagekit.io/demo/tr:e-sharpen-10,h-300/sample_image.jpg)

![](https://ik.imagekit.io/demo/tr:e-sharpen-10,h-300/sample_image.jpg)
{% /linetab %}
{% /linetabs %}

## Unsharp mask - (e-usm)

[Unsharp Masking (USM)](https://en.wikipedia.org/wiki/Unsharp_masking) is an image sharpening technique. This transform allows you to apply and control unsharp masks on your images. 

Example usage - `e-usm-<radius>-<sigma>-<amount>-<threshold>`

The amount of sharpening can be varied using 4 parameters - `radius` , `sigma` , `amount` , and `threshold`. This results in perceptually better images compared to using [e-sharpen](#sharpen---e-sharpen). Only positive floating points are allowed for these 4 parameters.

{% linetabs %}
{% linetab title="Original image" %}
URL - [https://ik.imagekit.io/demo/tr:h-300/sample_image.jpg](https://ik.imagekit.io/demo/tr:h-300/sample_image.jpg)

![](https://ik.imagekit.io/demo/tr:h-300/sample_image.jpg)
{% /linetab %}

{% linetab title="radius=2, sigma=2, amount=0.8 and threshold=0.024" %}
URL - [https://ik.imagekit.io/demo/tr:h-300,e-usm-2-2-0.8-0.024/sample_image.jpg](https://ik.imagekit.io/demo/tr:h-300,e-usm-2-2-0.8-0.024/sample_image.jpg)

![](https://ik.imagekit.io/demo/tr:h-300,e-usm-2-2-0.8-0.024/sample_image.jpg)
{% /linetab %}
{% /linetabs %}

## Shadow - (e-shadow)

This feature adds a shadow under solid objects in an input image with a transparent background. 

The shadow is applied under the areas constituted by the non-transparent pixels in the input image. You can adjust the shadow's saturation, blur level, and positional offsets with the following parameters.

You can also try out the AI drop shadow transformation for more realistic shadows. Read more about it [here](/ai-transformations#ai-drop-shadow-e-dropshadow).

{% table %}
* **Parameter** {% width="40%" %}
* **Description** {% width="40%" %}
* **Range** {% width="40%" %}
* **Default value** {% width="40%" %}
---
* `Blur (bl)`
* Adjusts the blur level of the shadow. e.g. `e-shadow-bl-15`
* `0` to `15`
* `10`
---
* `Saturation (st)`
* Specifies the saturation level of the shadow. e.g. `e-shadow-st-40`
* `0` to `100`
* `30`
---
* `X Offset (x)`
* Sets the horizontal offset of the shadow by x% of the image width. e.g. `e-shadow-x-10`. Supports negative values by prefixing N: e.g. `e-shadow-x-N10`
* `0` to `100` or `N100`
* `2`
---
* `Y Offset (y)`
* Sets the vertical offset of the shadow by y% of the image height. e.g. `e-shadow-y-10`. Supports negative values by prefixing N:e.g., `e-shadow-y-N10`
* `0` to `100` or `N100`
* `2`
---
{% /table %}

Multiple parameters can be configured by appending them with an underscore (`_`). They will be applied independently of the order in which they are specified.

Example usage - `e-shadow-<blur>_<saturation>_<x-offset>_<y-offset>`, which would look like, `e-shadow-bl-15_st-40_x-10_y-N5`.

{% linetabs %}
{% linetab title="Default e-shadow" %}
URL - [https://ik.imagekit.io/demo/tr:e-shadow/lipstick_1M.png](https://ik.imagekit.io/demo/tr:e-shadow/lipstick_1M.png)

![](https://ik.imagekit.io/demo/tr:e-shadow/lipstick_1M.png)
{% /linetab %}

{% linetab title="blur=15, saturation=40, X offset=10 and Y offset=-5" %}
URL - [https://ik.imagekit.io/demo/tr:e-shadow-bl-15_st-40_x-10_y-N5/mirror_1M.png](https://ik.imagekit.io/demo/tr:e-shadow-bl-15_st-40_x-10_y-N5/mirror_1M.png)

![](https://ik.imagekit.io/demo/tr:e-shadow-bl-15_st-40_x-10_y-N5/mirror_1M.png)
{% /linetab %}
{% /linetabs %}

### Limits

Shadows can only be applied to images with a resolution of maximum 2MP. Images with resolutions outside this limit will return a "400 - Bad Request" error.

To add shadows on images larger than 2MP, you can resize the image in either the same chain or a chained transformation and then add the shadow. 

e.g. For a 3MP image, `e-shadow` would not work. But `w-500,e-shadow` or `w-500:e-shadow` would work.

We have an input image with dimensions 2216x1500 (3MP). Applying only the shadow transformation will return an error with status code 400: `https://ik.imagekit.io/demo/tr:e-shadow/lipstick_2M.png`. 

Resize the image as follows to apply a shadow successfully:

{% linetabs %}
{% linetab title="Resize and shadow: w-500,e-shadow" %}
URL - [https://ik.imagekit.io/demo/tr:w-500,e-shadow/lipstick_2M.png](https://ik.imagekit.io/demo/tr:w-500,e-shadow/lipstick_2M.png)

![](https://ik.imagekit.io/demo/tr:w-500,e-shadow/lipstick_2M.png)
{% /linetab %}

{% linetab title="Chained resize then shadow: w-500:e-shadow" %}
URL - [https://ik.imagekit.io/demo/tr:w-500:e-shadow/lipstick_2M.png](https://ik.imagekit.io/demo/tr:w-500:e-shadow/lipstick_2M.png)

![](https://ik.imagekit.io/demo/tr:w-500:e-shadow/lipstick_2M.png)
{% /linetab %}

{% linetab title="Original 3MP image (2216x1500)" %}
URL - [https://ik.imagekit.io/demo/lipstick_2M.png](https://ik.imagekit.io/demo/lipstick_2M.png)

![](https://ik.imagekit.io/demo/lipstick_2M.png)
{% /linetab %}

{% /linetabs %}

## Gradient - (e-gradient)

This is used to add a gradient overlay over an input image.

The gradient formed is a *linear gradient* containing two colors, and it can be customized with the following parameters:

{% table %}

* **Parameter** {% width="15%" %}
* **Description** {% width="35%" %}
* **Value Type**
* **Range**
* **Default Value**

---

* Linear Direction \
 `(ld)`
* **Optional** \
  Sets the direction vector of the linear gradient.
For enhanced control over the direction, this parameter also accepts an integer in the range `0-359`, which specifies the angle (in degrees) when measured over standard x-y axes with a pivot passing through the geometrical center of the image. For example, `0` would mean top, `45` would mean top_right, `90` would mean right etc.
* `Number` or `String`
* **Number** - `0` to `359`
  
  **String** - `top`, `top_right`, `right`, `bottom_right`, `bottom`, `bottom_left`, `left`, `top_left`.
* `180` or `bottom`

---

* From Color \
    `(from)`
* **Optional** \
  It is used to specify a starting / first color for the gradient, i.e., the starting point of the gradient will have this color in its pure form.
RGBA Code (e.g., FFAABB50) is a color representation model where the first six characters must be the RGB Hex Code, and the last two characters must be a number between 00 and 99, which indicates the opacity level. For example, 00 represents an opacity level of 0.00, 01 represents an opacity level of 0.01, and so on.
* `String`
* An [SVG recognized color](https://www.w3.org/TR/SVG11/types.html#ColorKeywords) keyword name eg. `aqua`;
  
  or a RGB Hex Code, e.g. `FF0000`;

  or a RGBA Hex Code, e.g. `FF000040`;
* `FFFFFF`

---

* To Color \
    `(to)`
* **Optional** \
    It is used to specify the second color for the gradient and will be blended with the from color depending on the ld and sp configurations.
RGBA Code (e.g., FFAABB50) is a color representation model where the first six characters must be the RGB Hex Code, and the last two characters must be a number between 00 and 99, which indicates the opacity level. For example, 00 represents an opacity level of 0.00, 01 represents an opacity level of 0.01, and so on.
* `String`
* An [SVG recognized color](https://www.w3.org/TR/SVG11/types.html#ColorKeywords) keyword name eg. `aqua`;
  
  or a RGB Hex Code, e.g. `FF0000`;

  or a RGBA Hex Code, e.g. `FF000040`;

* `00000000`

---

* Stop Point \
  `(sp)`
* **Optional** \
  It is used to dictate where the breakpoint should be made between the from color and the to color. In simpler words, it is the point (along the direction vector of the gradient) at which the color achieves its pure form, i.e., no blending with the from color.
  
  When the number is less than or equal to 1, i.e., a floating point, it would be treated as a percentage value. For example, 0.25 means 25%, 0.1 means 10% and so on.
  
  When the number is greater than 1, it would be treated as an absolute value (in pixels). For example, 100 would mean 100px, and so on.
* `Number` or `String`
* **Number** - A floating point number between 0.01 and 0.99 or an integer greater than or equal to 1.
  
  **String** - An arithmetic expression like ih_div_2. Read more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).

* `1`

{% /table %}

Multiple parameters can be configured by appending them with an underscore (`_`). They will be applied independently of the order in which they are specified.

Example usage - `e-gradient-<linear-direction>_<from-color>_<to-color>_<stop-point>`, which would look like, `e-gradient-ld-top_right_from-FF000040_to-00FF0040_sp-0.9`.

{% linetabs %}
{% linetab title="Original Image" %}
URL - [https://ik.imagekit.io/demo/tr:h-300/sample_image.jpg](https://ik.imagekit.io/demo/tr:h-300/sample_image.jpg)

![](https://ik.imagekit.io/demo/tr:h-300/sample_image.jpg)
{% /linetab %}

{% linetab title="Default e-gradient" %}
URL - [https://ik.imagekit.io/demo/tr:h-300,e-gradient/sample_image.jpg](https://ik.imagekit.io/demo/tr:h-300,e-gradient/sample_image.jpg)

![](https://ik.imagekit.io/demo/tr:h-300,e-gradient/sample_image.jpg)
{% /linetab %}

{% linetab title="linear-direction=45, from-color=FF000050, to-color=FFFFFF50, sp=0.5" %}
URL - [https://ik.imagekit.io/demo/tr:h-300,e-gradient-ld-45_from-FF000050_to-FFFFFF50_sp-0.5/sample_image.jpg](https://ik.imagekit.io/demo/tr:h-300,e-gradient-ld-45_from-FF000050_to-FFFFFF50_sp-0.5/sample_image.jpg)

![](https://ik.imagekit.io/demo/tr:h-300,e-gradient-ld-45_from-FF000050_to-FFFFFF50_sp-0.5/sample_image.jpg)
{% /linetab %}

{% linetab title="linear-direction=top, from-color=green, to-color=00FF0010, sp=1" %}
URL - [https://ik.imagekit.io/demo/tr:h-300,e-gradient-ld-top_from-green_to-00FF0010_sp-1/sample_image.jpg](https://ik.imagekit.io/demo/tr:h-300,e-gradient-ld-top_from-green_to-00FF0010_sp-1/sample_image.jpg)

![](https://ik.imagekit.io/demo/tr:h-300,e-gradient-ld-top_from-green_to-00FF0010_sp-1/sample_image.jpg)
{% /linetab %}
{% /linetabs %}

### Gradient as a background

For input images containing a solid object over a transparent background, gradient can also be applied as an underlay.

### Usage syntax

```markup
https://ik.imagekit.io/<imagekitId>/your-image.png?tr=e-gradient-from-red_to-white:l-image,i-your-image.png,t-false,l-end
```

### Examples

{% linetabs %}
{% linetab title="Original Image" %}
URL - [https://ik.imagekit.io/demo/tr:w-500/lipstick_2M.png](https://ik.imagekit.io/demo/tr:w-500/lipstick_2M.png)

![](https://ik.imagekit.io/demo/tr:w-500/lipstick_2M.png)
{% /linetab %}

{% linetab title="Gradient as a background" %}
URL - [https://ik.imagekit.io/demo/tr:e-gradient-from-lightskyblue_to-mintcream:l-image,i-lipstick_2M.png,t-false,l-end:w-500/lipstick_2M.png](https://ik.imagekit.io/demo/tr:e-gradient-from-lightskyblue_to-mintcream:l-image,i-lipstick_2M.png,t-false,l-end:w-500/lipstick_2M.png)

![](https://ik.imagekit.io/demo/tr:e-gradient-from-lightskyblue_to-mintcream:l-image,i-lipstick_2M.png,t-false,l-end:w-500/lipstick_2M.png)
{% /linetab %}
{% /linetabs %}

{% callout style="info" %}
If you experience a positional displacement between the original image and the overlay image, use `t-false` to disable default trimming of the overlay layer like `l-image,i-your-image.png,t-false,l-end`.
{% /callout %}

### Transformation of gradient block overlay

Following transformation parameters are supported on the gradient block overlay inside a layer.

| Parameter                                                                       | Description                                                                                                                                                                                              |
| ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| w                                                                               | Width of the gradient block. It can also accept arithmetic expressions such as `bw_div_2`, or `bw_mul_0.8`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).  |
| h                                                                               | Height of the gradient block. It can also accept arithmetic expressions such as `bh_div_2`, or `bh_mul_0.8`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations). |
| [r](#radius---r) | It is used to control the radius of the corner and accepts an integer value as the input.                                                                                                                |

If you're looking to add a solid color block overlay instead, read more about it [here](/add-overlays-on-images#add-solid-color-blocks-over-image).

### Examples

{% linetabs %}
{% linetab title="Original Image" %}
URL - [https://ik.imagekit.io/demo/tr:w-500/lipstick_2M.png](https://ik.imagekit.io/demo/tr:w-500/lipstick_2M.png)

![](https://ik.imagekit.io/demo/tr:w-500/lipstick_2M.png)
{% /linetab %}

{% linetab title="Gradient block over the image" %}
URL - [https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,e-gradient-from-F2559A_to-F27855_ld-top,w-bw,h-bh_div_10,ly-N0,l-end:w-500/lipstick_2M.png](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,e-gradient-from-F2559A_to-F27855_ld-top,w-bw,h-bh_div_10,ly-N0,l-end:w-500/lipstick_2M.png)

![](https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,e-gradient-from-F2559A_to-F27855_ld-top,w-bw,h-bh_div_10,ly-N0,l-end:w-500/lipstick_2M.png)
{% /linetab %}
{% /linetabs %}


## Grayscale - (e-grayscale)

Used to turn an image into a grayscale version.

{% linetabs %}
{% linetab title="Normal" %}
URL - [https://ik.imagekit.io/demo/tr:h-300/sample_image.jpg](https://ik.imagekit.io/demo/tr:h-300/sample_image.jpg)

![](https://ik.imagekit.io/demo/tr:h-300/sample_image.jpg)
{% /linetab %}

{% linetab title="Grayscale" %}
URL - [https://ik.imagekit.io/demo/tr:h-300,e-grayscale/sample_image.jpg](https://ik.imagekit.io/demo/tr:h-300,e-grayscale/sample_image.jpg)

![](https://ik.imagekit.io/demo/tr:h-300,e-grayscale/sample_image.jpg)
{% /linetab %}
{% /linetabs %}

## Distort - (e-distort)

This is used to distort the shape of an image in one of two ways:

### Perspective distortion

Use this to change the position of any of the four corners of the image.

Syntax: `e-distort-p-<x1>_<y1>_<x2>_<y2>_<x3>_<y3>_<x4>_<y4>`

You must provide the new coordinates of the four corners of the image, starting clockwise from top-left. For example, if the input image is 600x600 pixels in size, the transformation `e-distort-p-100_100_700_N100_600_600_0_600` will pull the top-left corner inwards and push the top-right corner outwards by 100 pixels. Negative values move a corner upwards and to the left of the corner's original position.

{% linetabs %}

{% linetab  title="Original Image" %}

URL - [https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg)

![](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg)

{% /linetab %}

{% linetab  title="Perspective distortion" %}

URL - [https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg?tr=e-distort-p-100_100_700_N100_600_600_0_600](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg?tr=e-distort-p-100_100_700_N100_600_600_0_600)

![](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg?tr=e-distort-p-100_100_700_N100_600_600_0_600)

{% /linetab %}

{% /linetabs %}

### Arc distortion

Use this to curve the image upwards or downwards. You can control the curvature with the degrees value. Positive values curve the image upwards, while negative values curve them downwards.

Syntax: `e-distort-a-<degrees>`

{% linetabs %}

{% linetab  title="Original image" %}

URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg)

![](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg)

{% /linetab %}

{% linetab  title="Positive arc distortion" %}

URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=e-distort-a-30](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=e-distort-a-30)

![](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=e-distort-a-30)

{% /linetab %}

{% linetab  title="Negative arc distortion" %}

URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=e-distort-a-N30](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=e-distort-a-N30)

![](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg?tr=e-distort-a-N30)

{% /linetab %}

{% /linetabs %}

## Colorize - (e-colorize)

The colorize transformation applies a color tint to the image.

Syntax - `e-colorize-co-<color>_in-<intensity>`

{% table %}
* **Parameter** {% width="25%" %}
* **Description** {% width="55%" %}
* **Default Value** {% width="20%" %}
---
* `co`
* Color to apply. Supports standard color names (e.g. `blue`) and RGB hex codes (e.g. `FF0000`).
* `gray`
---
* `in`
* Intensity of the color effect. \
  **Range:** `0` to `100`
* `35`
{% /table %}

Examples:

- `e-colorize-co-FF0000_in-15` → color: `FF0000`, intensity: `15`
- `e-colorize-co-blue` → color: `blue`, intensity: `35` (default intensity)
- `e-colorize-in-30` → color: `gray`, intensity: `30` (default color)

{% linetabs %}
{% linetab title="Original" %}
URL - [https://ik.imagekit.io/demo/tr:h-300/sample_image.jpg](https://ik.imagekit.io/demo/tr:h-300/sample_image.jpg)

![](https://ik.imagekit.io/demo/tr:h-300/sample_image.jpg)
{% /linetab %}

{% linetab title="Colorize FF0000 with 15% intensity" %}
URL - [https://ik.imagekit.io/demo/tr:h-300,e-colorize-co-FF0000_in-15/sample_image.jpg](https://ik.imagekit.io/demo/tr:h-300,e-colorize-co-FF0000_in-15/sample_image.jpg)

![](https://ik.imagekit.io/demo/tr:h-300,e-colorize-co-FF0000_in-15/sample_image.jpg)
{% /linetab %}

{% linetab title="Colorize Blue with default intensity" %}
URL - [https://ik.imagekit.io/demo/tr:h-300,e-colorize-co-blue/sample_image.jpg](https://ik.imagekit.io/demo/tr:h-300,e-colorize-co-blue/sample_image.jpg)

![](https://ik.imagekit.io/demo/tr:h-300,e-colorize-co-blue/sample_image.jpg)
{% /linetab %}

{% linetab title="Colorize Default color with 30% intensity" %}
URL - [https://ik.imagekit.io/demo/tr:h-300,e-colorize-in-30/sample_image.jpg](https://ik.imagekit.io/demo/tr:h-300,e-colorize-in-30/sample_image.jpg)

![](https://ik.imagekit.io/demo/tr:h-300,e-colorize-in-30/sample_image.jpg)
{% /linetab %}
{% /linetabs %}


## Blur - (bl)

Used to specify the Gaussian blur that must be applied to an image. The value of `bl` specifies the radius of the Gaussian Blur that is to be applied. Higher the value, the larger the radius of the Gaussian Blur. Possible values include integers between `1` and `100`.

{% linetabs %}
{% linetab title="Original" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg)

![](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg)
{% /linetab %}

{% linetab title="blur=10" %}
URL - [https://ik.imagekit.io/ikmedia/tr:bl-10/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:bl-10/docs_images/examples/example_food_3.jpg)

![](https://ik.imagekit.io/ikmedia/tr:bl-10/docs_images/examples/example_food_3.jpg)
{% /linetab %}
{% /linetabs %}

## Trim edges - (t)

Useful with images that have a solid or nearly solid background with the object in the center. This parameter trims the background from the image, leaving only the central object in the output image. 

Usage - `t-true|Number`.

**Possible values** include `true`  and integer values between `1`  and `99` that specify the threshold level for considering a particular pixel as "background".

{% linetabs %}
{% linetab title="Trim true" %}
URL - [https://ik.imagekit.io/demo/img/tr:t-true/trim_example_BkgQVu7oX.png](https://ik.imagekit.io/demo/img/tr:t-true/trim_example_BkgQVu7oX.png)

![](https://ik.imagekit.io/demo/img/tr:t-true/trim_example_BkgQVu7oX.png)
{% /linetab %}

{% linetab title="With trim equal to 5" %}
URL - [https://ik.imagekit.io/demo/img/tr:t-5/trim_example_BkgQVu7oX.png](https://ik.imagekit.io/demo/img/tr:t-5/trim_example_BkgQVu7oX.png)

Here some trimming does take place (you can notice that the grey circle in the background is getting cut off), but it is not as much as what happened when the value of trim was set to `true`.

![](https://ik.imagekit.io/demo/img/tr:t-5/trim_example_BkgQVu7oX.png)
{% /linetab %}

{% linetab title="With trim equal to 15" %}
URL - [https://ik.imagekit.io/demo/img/tr:t-15/trim_example_BkgQVu7oX.png](https://ik.imagekit.io/demo/img/tr:t-15/trim_example_BkgQVu7oX.png)

Here the amount of trimming is higher than what happened with trim set to `true`. This is because with a higher value specified for trim, more and more pixels are considered as similar and redundant and hence get removed.

![](https://ik.imagekit.io/demo/img/tr:t-15/trim_example_BkgQVu7oX.png)
{% /linetab %}
{% /linetabs %}

## Border - (b)

This adds a border to the image. It accepts two parameters - the width of the border and the color of the border.

Usage - `b-<border-width>-<hex code>`

The width is specified as a number which is equivalent to the border width in pixels. The color code is specified as a 6-character hex code RRGGBB.

You can also provide an arithmetic expression such as `ih_div_20_red`, or `cw_mul_0.05_FF00FF` as a value for this parameter. Doing so will first calculate the value of the width and then apply transformations using that value. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).

{% linetabs %}
{% linetab title="5px yellow border" %}
URL - [https://ik.imagekit.io/ikmedia/tr:w-300,b-5_FFF000/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:w-300,b-5_FFF000/docs_images/examples/example_food_3.jpg)

![](https://ik.imagekit.io/ikmedia/tr:w-300,b-5_FFF000/docs_images/examples/example_food_3.jpg)
{% /linetab %}

{% linetab title="20px red border" %}
URL - [https://ik.imagekit.io/ikmedia/tr:w-300,b-20_FF0000/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:w-300,b-20_FF0000/docs_images/examples/example_food_3.jpg)

![](https://ik.imagekit.io/ikmedia/tr:w-300,b-20_FF0000/docs_images/examples/example_food_3.jpg)
{% /linetab %}
{% /linetabs %}

## Rotate - (rt)

It is used to specify the degree by which the output image must be rotated or specifies the use of EXIF Orientation Tag for the rotation of image using the `auto` parameter.

**Possible values** - Any number for a clockwise rotation, or any number preceded with `N` for counter-clockwise rotation, and `auto`.

{% callout style="info" %}
Use `auto` if you want ImageKit.io to automatically rotate image based on EXIF orientation tag in image metadata.
{% /callout %}

{% linetabs %}
{% linetab title="rt=90" %}
URL - [https://ik.imagekit.io/ikmedia/tr:rt-90/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:rt-90/docs_images/examples/example_food_3.jpg)

![](https://ik.imagekit.io/ikmedia/tr:rt-90/docs_images/examples/example_food_3.jpg)
{% /linetab %}

{% linetab title="rt=N40" %}
URL - [https://ik.imagekit.io/ikmedia/tr:rt-N40/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:rt-N40/docs_images/examples/example_food_3.jpg)

![](https://ik.imagekit.io/ikmedia/tr:rt-N40/docs_images/examples/example_food_3.jpg)
{% /linetab %}
{% /linetabs %}

## Flip - (fl)

It is used to flip/mirror an image horizontally, vertically, or in both directions.

**Possible values** - `h` (horizontal), `v` (vertical), `h_v` (horizontal and vertical)

{% linetabs %}
{% linetab title="Original" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg)

![](https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/car.jpeg)
{% /linetab %}

{% linetab title="fl=h" %}
URL - [https://ik.imagekit.io/ikmedia/tr:fl-h/docs_images/features/image-transformations/car.jpeg](https://ik.imagekit.io/ikmedia/tr:fl-h/docs_images/features/image-transformations/car.jpeg)

![](https://ik.imagekit.io/ikmedia/tr:fl-h/docs_images/features/image-transformations/car.jpeg)
{% /linetab %}

{% linetab title="fl=h_v" %}
URL - [https://ik.imagekit.io/ikmedia/tr:fl-h_v/docs_images/features/image-transformations/car.jpeg](https://ik.imagekit.io/ikmedia/tr:fl-h_v/docs_images/features/image-transformations/car.jpeg)

![](https://ik.imagekit.io/ikmedia/tr:fl-h_v/docs_images/features/image-transformations/car.jpeg)
{% /linetab %}
{% /linetabs %}

## Radius - (r)

The `r` parameter is used to round the corners of an image. You can either apply a single radius value to all four corners or specify different radius values for each corner.

### Single radius for all corners

**Possible values** - Positive Integer and `max`.

`max` sets the radius to half the length of the shorter side of the image, resulting in perfectly rounded corners.

{% callout style="info" %}
For simpler cases, you can use radius in the same transformation as the height and width parameters. However, if you are using advanced cropping parameters, like crop (c) and crop mode (cm), then you should [chain](/transformations#chained-transformations) the radius transformation in a step after the resizing transformation.
{% /callout %}

{% linetabs %}
{% linetab title="r=20" %}
URL - [https://ik.imagekit.io/ikmedia/tr:r-20/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:r-20/docs_images/examples/example_food_3.jpg)

![](https://ik.imagekit.io/ikmedia/tr:r-20/docs_images/examples/example_food_3.jpg)
{% /linetab %}

{% linetab title="r=50" %}
URL - [https://ik.imagekit.io/ikmedia/tr:r-50/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:r-50/docs_images/examples/example_food_3.jpg)

![](https://ik.imagekit.io/ikmedia/tr:r-50/docs_images/examples/example_food_3.jpg)
{% /linetab %}

{% linetab title="r=max (Round)" %}
URL - [https://ik.imagekit.io/ikmedia/tr:r-max/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:r-max/docs_images/examples/example_food_3.jpg)

This is good for creating profile pictures.

![](https://ik.imagekit.io/ikmedia/tr:r-max/docs_images/examples/example_food_3.jpg)
{% /linetab %}
{% /linetabs %}

### Per corner radius

You can specify 4 underscore-separated values to set different radius values for each corner of the image. The order of the values should be top-left, top-right, bottom-right, and bottom-left.

**Syntax** - `r-<top-left>_<top-right>_<bottom-right>_<bottom-left>`

Four underscore-separated values, each can be any positive integer or max .

{% linetabs %}
{% linetab title="r-20_40_80_160" %}

URL - [https://ik.imagekit.io/demo/tr:r-20_40_80_160,bg-green/sample_image.jpg](https://ik.imagekit.io/demo/tr:r-20_40_80_160,bg-green/sample_image.jpg)

Different radius for each corner: top-left=20px, top-right=40px, bottom-right=80px, bottom-left=160px.

`bg-green` is used here to set background color behind the rounded corners.

![r-20_40_80_160](https://ik.imagekit.io/demo/tr:r-20_40_80_160,bg-green/sample_image.jpg)

{% /linetab %}
{% linetab title="r-max_50_max_50" %}

URL - [https://ik.imagekit.io/demo/tr:r-max_50_max_50/sample_image.jpg](https://ik.imagekit.io/demo/tr:r-max_50_max_50/sample_image.jpg)

Using `max` for top-left & bottom-right in this example.

Setting radius to `max` creates a perfectly circular corner by setting the radius to half the length of the shorter side of the image.

![r-max_50_max_50](https://ik.imagekit.io/demo/tr:r-max_50_max_50/sample_image.jpg)

{% /linetab %}
{% linetab title="r-0_300_0_300" %}

URL - [https://ik.imagekit.io/demo/tr:r-max_50_max_50/0_300_0_300.jpg](https://ik.imagekit.io/demo/tr:r-0_300_0_300/sample_image.jpg)

Setting radius to `0` for top-left & bottom-right and `300` for top-right & bottom-left.

![r-0_300_0_300](https://ik.imagekit.io/demo/tr:r-0_300_0_300/sample_image.jpg)

{% /linetab %}
{% /linetabs %}

{% callout style="info" %}
Per corner radius is only available for image transformations.

For video transformations, you can only set a single radius value for all corners.
{% /callout %}

## Background - (bg)

It is used to specify the background that can be used along with some cropping strategies while resizing an image, or simply to add a background to a transparent image. When choosing a background, you have four options:

* Add a [solid color background](#solid-color-background) with a hex code or color name.
* Add a [blurred version](#blurred-background) of the same image as the background.
* Add the most [dominant color](#dominant-color-background) in the borders of your image as the background.
* Add a [gradient](#gradient-background) with the most dominant colors picked from the image as the background.
* Expand the image boundaries using [generative fill](/ai-transformations#generative-fill-bg-genfill) (bg-genfill). Optionally, you can guide the expansion with a text prompt. The AI intelligently extends the original image, blending the new content seamlessly for a natural look.


### Solid color background

* RGB Hex code: A 6-digit hex code (eg. AAFF00, 0f0fac)
* RGBA Hex code: An 8-digit hex code. Last two characters must be a number between `00` and `99`, specifying the opacity level (eg. AAFF0040, 0f0fac75) 
* Color name: A standard color name in lowercase (eg. lightgreen, beige)

**Default value** - black (00000)

{% linetabs %}
{% linetab title="bg=272B38" %}
URL - [https://ik.imagekit.io/ikmedia/tr:h-700,w-700,cm-pad_extract,bg-272B38/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:h-700,w-700,cm-pad_extract,bg-272B38/docs_images/examples/example_food_3.jpg)

![](https://ik.imagekit.io/ikmedia/tr:h-700,w-700,cm-pad_extract,bg-272B38/docs_images/examples/example_food_3.jpg)
{% /linetab %}

{% linetab title="bg=A94D34" %}
URL - [https://ik.imagekit.io/ikmedia/tr:h-700,w-700,cm-pad_extract,bg-A94D34/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:h-700,w-700,cm-pad_extract,bg-A94D34/docs_images/examples/example_food_3.jpg)

![](https://ik.imagekit.io/ikmedia/tr:h-700,w-700,cm-pad_extract,bg-A94D34/docs_images/examples/example_food_3.jpg)
{% /linetab %}

{% linetab title="Add bg to transparent image" %}
URL - [https://ik.imagekit.io/demo/lipstick_1M.png?tr=bg-FADADD](https://ik.imagekit.io/demo/lipstick_1M.png?tr=bg-FADADD)

![](https://ik.imagekit.io/demo/lipstick_1M.png?tr=bg-FADADD)
{% /linetab %}

{% /linetabs %}

### Blurred background

Syntax: `blurred[_<BlurIntensity>][_<Brightness>]`

|      Parameter |                                  Value |                                                                                Description | Default |
| -------------: | -------------------------------------: | -----------------------------------------------------------------------------------------: | ------: |
| Blur intensity | `auto` or an integer from `0` to `100` |                                                                  Set the intensity of blur |  `auto` |
|     Brightness |           Integer from `N255` to `255` | Negative value to make background darker and positive value to make the background lighter |       0 |

Limitation: Blurred background can only be used with `cm-pad_resize`.

Blur intensity `auto` - The intensity of blur is automatically adjusted based on the provided height (h) & width (w) in the transformation.

{% linetabs %}
{% linetab title="bg=blurred" %}
URL - [https://ik.imagekit.io/ikmedia/tr:h-600,w-800,cm-pad_resize,bg-blurred/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:h-600,w-800,cm-pad_resize,bg-blurred/docs_images/examples/example_food_3.jpg)

![cm-pad_resize,bg-blurred](https://ik.imagekit.io/ikmedia/tr:h-600,w-800,cm-pad_resize,bg-blurred/docs_images/examples/example_food_3.jpg)
{% /linetab %}

{% linetab title="bg=blurred_25_N30" %}
URL - [https://ik.imagekit.io/ikmedia/tr:h-600,w-800,cm-pad_resize,bg-blurred_25_N30/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:h-600,w-800,cm-pad_resize,bg-blurred_25_N30/docs_images/examples/example_food_3.jpg)

Customize blur-intensity to `25` & brightness to `N30` (Make background darker).

![cm-pad_resize,bg-blurred_25_N30](https://ik.imagekit.io/ikmedia/tr:h-600,w-800,cm-pad_resize,bg-blurred_25_N30/docs_images/examples/example_food_3.jpg)
{% /linetab %}

{% linetab title="bg=blurred_auto_30" %}
URL - [https://ik.imagekit.io/ikmedia/tr:h-600,w-800,cm-pad_resize,bg-blurred_auto_30/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:h-600,w-800,cm-pad_resize,bg-blurred_auto_30/docs_images/examples/example_food_3.jpg)

Automatic blur-intensity & customize brightness to `30` (Make background lighter).

![cm-pad_resize,bg-blurred_auto_30](https://ik.imagekit.io/ikmedia/tr:h-600,w-800,cm-pad_resize,bg-blurred_auto_30/docs_images/examples/example_food_3.jpg)
{% /linetab %}
{% /linetabs %}

### Dominant color background

Syntax: `bg-dominant`

Limitation: This parameter ban be used only with `cm-pad_resize` and `cm-pad_extract`.

{% linetabs %}
{% linetab title="With pad_resize" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg?tr=cm-pad_resize,bg-dominant,w-1000,h-600](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg?tr=cm-pad_resize,bg-dominant,w-1000,h-600)

![cm-pad_resize,bg-dominant,w-1000,h-600](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg?tr=cm-pad_resize,bg-dominant,w-1000,h-600)
{% /linetab %}

{% linetab title="With pad_extract" %}
URL - [https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg?tr=cm-pad_extract,bg-dominant,w-800,h-800](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg?tr=cm-pad_extract,bg-dominant,w-800,h-800)

![cm-pad_extract,bg-dominant,w-800,h-800](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg?tr=cm-pad_extract,bg-dominant,w-800,h-800)
{% /linetab %}
{% /linetabs %}

### Gradient Background

#### Dominant Gradient Background

Most dominant colors from the image will be picked automatically to form the gradient.

Syntax: `bg-gradient_<mode>[_<paletteSize>]`

|      Parameter |                                  Value |                                                                                Description | Default |
| -------------: | -------------------------------------: | -----------------------------------------------------------------------------------------: | ------: |
| Mode | `dominant` | The most dominant colors from the image will be picked to form the gradient. | - |
| Palette Size | `2` or `4` | The number of colors that will be picked from the image to form the gradient. When this is 2, a linear horizontal gradient is formed. When this is 4, the four colors will be interpolated between the four corners.  | 2 |

**Note:** For gradient backgrounds with PNG images, you can also take a look at [Gradient as a background](#gradient-as-a-background) which uses the [e-gradient](#gradient---e-gradient) effect along with overlays to form a gradient background. This approach offers more customizations specific to the gradient formation.

{% linetabs %}
{% linetab title="With a PNG image" %}
URL - [https://ik.imagekit.io/demo/tr:bg-gradient_dominant/lipstick_1M.png](https://ik.imagekit.io/demo/tr:bg-gradient_dominant/lipstick_1M.png)

![bg-gradient_dominant](https://ik.imagekit.io/demo/tr:bg-gradient_dominant/lipstick_1M.png)
{% /linetab %}

{% linetab title="With pad_resize" %}
URL - [https://ik.imagekit.io/ikmedia/tr:cm-pad_resize,bg-gradient_dominant,w-600,h-800/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:cm-pad_resize,bg-gradient_dominant,w-600,h-800/docs_images/examples/example_food_3.jpg)

![cm-pad_resize,bg-gradient_dominant,w-600,h-800](https://ik.imagekit.io/ikmedia/tr:cm-pad_resize,bg-gradient_dominant,w-600,h-800/docs_images/examples/example_food_3.jpg)
{% /linetab %}

{% linetab title="With pad_extract (paletteSize = 4)" %}
URL - [https://ik.imagekit.io/ikmedia/tr:cm-pad_extract,bg-gradient_dominant_4,w-800,h-600/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:cm-pad_extract,bg-gradient_dominant_4,w-800,h-600/docs_images/examples/example_food_3.jpg)

![cm-pad_extract,bg-gradient_dominant_4,w-800,h-600](https://ik.imagekit.io/ikmedia/tr:cm-pad_extract,bg-gradient_dominant_4,w-800,h-600/docs_images/examples/example_food_3.jpg)
{% /linetab %}
{% /linetabs %}

**Limits**

Dominant gradient backgrounds can only be applied to images with a resolution of maximum 100MP. Images with resolutions outside this limit will return a "400 - Bad Request" error. For paletteSize = 4, the maximum resolution limit is 30MP.

## Opacity - (o)

It is used to specify the opacity level of the output image. A non-transparent image can be made semi-transparent by specifying an opacity level that is less than 100. An already transparent image is made more transparent based on the specified value. It accepts numerical values ranging from 0 to 100, where 0 would produce a completely transparent image, and 100 would have no effect. 

If a background (`bg`) color is specified along with opacity, then that color is blended with the resultant image, leading to a non-transparent (opaque) image, but with the `bg` color mixed in. Alpha component, if present in the `bg` value, will be ignored.

**Possible values** - Integer values from 0 to 100 (inclusive).

{% linetabs %}
{% linetab title="o-50" %}
URL - [https://ik.imagekit.io/ikmedia/tr:o-50/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:o-50/docs_images/examples/example_food_3.jpg)

![](https://ik.imagekit.io/ikmedia/tr:o-50/docs_images/examples/example_food_3.jpg)
{% /linetab %}

{% linetab title="o-50,bg-blue" %}
URL - [https://ik.imagekit.io/ikmedia/tr:o-50,bg-blue/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:o-50,bg-blue/docs_images/examples/example_food_3.jpg)

![](https://ik.imagekit.io/ikmedia/tr:o-50,bg-blue/docs_images/examples/example_food_3.jpg)
{% /linetab %}

{% linetab title="o-50,bg-0000FF30" %}
URL - [https://ik.imagekit.io/ikmedia/tr:o-50,bg-0000FF30/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:o-50,bg-0000FF30/docs_images/examples/example_food_3.jpg)

![](https://ik.imagekit.io/ikmedia/tr:o-50,bg-0000FF30/docs_images/examples/example_food_3.jpg)
{% /linetab %}
{% /linetabs %}

## Color Replace - (cr)

The color replace transformation allows you to recolor objects in images by mapping an input color and its similar shades to corresponding tones of a target output color. This transformation preserves the natural appearance of the image by maintaining the luminosity and chroma relationships, ensuring that highlights, shadows, and color depth are realistically adapted to the new color.

Syntax - `cr-<toColor>_<tolerance>_<fromColor>`


{% table %}
* **Parameter** {% width="25%" %}
* **Description** {% width="55%" %}
* **Default Value** {% width="20%" %}
---
* `toColor` (required)
* The HTML color name or RGB/A hex code of the target output color. This is the color that will replace the input color. Examples: `blue`, `red`, `FF0000`, `012548`
* \-
---
* `tolerance`
* The tolerance threshold representing a radius in the LAB color space from the input color. This defines the range of similar colors that should be replaced. Lower tolerance values result in more precise color replacement, while higher values replace a broader range of similar colors. 
**Range:** `0` to `100`
* `35`
---
* `fromColor`
* The HTML color name or RGB/A hex code of the base input color to map from. This is the color in the original image that you want to replace.  
When `fromColor` is not specified, ImageKit.io automatically detects and replaces the most prominent saturated color in the image.
* Most prominent high-saturation color in the image
{% /table %}

{% linetabs %}
{% linetab title="Original" %}
URL - [https://ikmedia.imagekit.io/docs_images/examples/example_color-replace.jpg](https://ikmedia.imagekit.io/docs_images/examples/example_color-replace.jpg?tr=w-600,h-600,c-at_max)

![](https://ikmedia.imagekit.io/docs_images/examples/example_color-replace.jpg?tr=w-600,h-600,c-at_max)
{% /linetab %}

{% linetab title="Color replace with default fromColor" %}
URL - [https://ikmedia.imagekit.io/docs_images/examples/example_color-replace.jpg?tr=cr-065465](https://ikmedia.imagekit.io/docs_images/examples/example_color-replace.jpg?tr=cr-065465)

![](https://ikmedia.imagekit.io/docs_images/examples/example_color-replace.jpg?tr=cr-065465,w-600,h-600,c-at_max)
{% /linetab %}

{% linetab title="Using a tolerance value" %}
URL - [https://ikmedia.imagekit.io/docs_images/examples/example_color-replace.jpg?tr=cr-065465_40](https://ikmedia.imagekit.io/docs_images/examples/example_color-replace.jpg?tr=cr-065465_40)

![](https://ikmedia.imagekit.io/docs_images/examples/example_color-replace.jpg?tr=cr-065465_40,w-600,h-600,c-at_max)
{% /linetab %}

{% linetab title="Using all 3 parameters" %}
URL - [https://ikmedia.imagekit.io/docs_images/examples/example_color-replace.jpg?tr=cr-012548_30_6C0E16](https://ikmedia.imagekit.io/docs_images/examples/example_color-replace.jpg?tr=cr-012548_30_6C0E16)

![](https://ikmedia.imagekit.io/docs_images/examples/example_color-replace.jpg?tr=cr-012548_30_6C0E16,w-600,h-600,c-at_max)
{% /linetab %}
{% /linetabs %}

{% callout style="info" %}
**Tip**: Start with the default tolerance value (35) and adjust as needed.
{% /callout %}


---

# Source: /vector-and-animated-images

---
title: Vector and Animated Images
description: Learn how to generate thumbnails from vector and animated images.
---

ImageKit can be used to generate thumbnails from PSD, AI, EPS, SVG, and animated GIF, APNG, and WebP images. This is useful when you want to generate thumbnails from vector images or animated images.


## SVG to raster format conversion

ImageKit.io allows you to convert SVG images to raster formats in two ways:

### Manual conversion
You can explicitly specify the desired raster format using the [format transformation parameter (f)](/image-optimization#format---f) in the image URL. For example: `f-png`, `f-jpg`, etc.

### Automatic conversion
When you enable the SVG rasterization setting in your dashboard, SVG images will be automatically converted to raster formats like PNG or JPEG. This automatic conversion only happens when format optimization is also enabled, either through [account settings](https://imagekit.io/dashboard/settings/images) or by using `f-auto` in the URL. By default, the SVG rasterization setting will be enabled in your dashboard.

{% callout style="info" %}
To apply image transformations such as resizing, adding overlays, etc., SVG images must be converted to raster formats.
{% /callout %}

{% linetabs %}
{% linetab title="Original SVG" %}
URL - [https://ik.imagekit.io/ikmedia/imagekitlogo.svg](https://ik.imagekit.io/ikmedia/imagekitlogo.svg)

![SVG image;width=100](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/imagekitlogo.svg)
{% /linetab %}

{% linetab title="Convert to PNG" %}
URL - [https://ik.imagekit.io/ikmedia/tr:f-png/imagekitlogo.svg](https://ik.imagekit.io/ikmedia/tr:f-png/imagekitlogo.svg)

![PNG conversion of imagekit logo;width=100](https://ik.imagekit.io/ikmedia/tr:f-png/imagekitlogo.svg)

The SVG image is transformed to PNG format. The transparency is preserved in PNG format by default.

The dimension of the raster output is determined by the [`viewBox` attribute](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/viewBox) of the SVG when no height or width is defined in the transformation. In this case, the dimension of the raster output is 158x33 pixels, since the `viewBox` attribute of the original SVG is set to `0 0 158 33`.
{% /linetab %}

{% linetab title="Convert to JPG format and apply pink background color" %}
URL - [https://ik.imagekit.io/ikmedia/tr:f-jpg,w-200,bg-pink/imagekitlogo.svg](https://ik.imagekit.io/ikmedia/tr:f-jpg,w-200,bg-pink/imagekitlogo.svg)

![JPG conversion of imagekit logo with pink background;width=100](https://ik.imagekit.io/ikmedia/tr:f-jpg,w-200,bg-pink/imagekitlogo.svg)

The SVG image is transformed into a JPG format with a width of 200 pixels and a pink background color added to it.
{% /linetab %}
{% /linetabs %}

## Get thumbnail from PSD, PDF, AI, EPS and animated files
Delivers the specified page, frame, or layer of a multi-page, multi-frame, or multi-layer, such as a PDF, animated image like GIF, or PSD. It needs to be used alongside the ik-thumbnail.jpg URL component.

`ik-thumbnail.jpg` needs to be added after the file resource URL, like this:

```markup
https://ik.imagekit.io/ikmedia/tr:pg-2/layout.psd/ik-thumbnail.jpg
````

**List of supported multi-page/frame/layer files formats**
* PDF
* PSD
* EPS
* AI
* GIF
* Animated Webp
* Animated PNG

{% callout style="info" %}
If the `pg` parameter is not provided and only `ik-thumbnail.jpg` is added after the file resource URL of the above-mentioned formats, then the first page, frame, or layer is extracted by default.
{% /callout %}

**Usage**

{% table %}
- **Syntax** {% width="25%" %}
- **Description** {% width="25%" %}
- **Value Type**
- **Usage Example**

---

- **pg-<number>**
- Delivers a single page or layer of a multi-page or multi-layer file (PDF, PSD), or a specified frame of an animated image like GIF.
- Number
- `pg-2`

---

- **pg-<range>** \
  (Applicable for PSD only)
- Delivers the specified range of pages or layers from a PSD file.
- Numbers separated by `-` (for range) or `_` (for multiple values)
- Used in the following ways:
  - Use underscore (`_`) to separate a list of multiple pages/layers: `pg-1_3_5`
  - Use hyphens (`-`) to indicate a page/layer range: `pg-2-4`
  - Use a hyphen with no ending number to indicate starting from a specified page/layer until the end: `pg-4-`

---

- **pg-name-<layer name(s)>** \
  (Applicable for PSD only)
- Delivers one or more named layers from a PSD file
- Strings enclosed in `"` separated by `_` (for multiple values)
- The name of the layer(s) to deliver enclosed in double quotes (`"`). Use underscore (`_`) to separate a list of layer names
  ```
  pg-name-"layer-name-1"_"layer-name-2"
  ```
  
{% /table %}


For example, let's take this [layout.psd](https://ik.imagekit.io/ikmedia/layout.psd) file with 5 layers.

![Layout.psd;width=300](https://ik.imagekit.io/ikmedia/docs_images/examples/layout-psd-layers.png?updatedAt=1716950823637)

Remember that ImageKit counting starts from `1` which is the whole thumbnail, and then `2` is the first layer from the bottom, `3` is the second layer from the bottom, and so on. That means:

* `layer-0` is the first layer from the bottom. And for ImageKit, it will be `2`.
* `layer-1` is the second layer from the bottom. And for ImageKit, it will be `3`.
* `layer-002` is the third layer from the bottom. And for ImageKit, it will be `4`. Or you can refer by name i.e. `layer-002`.
* `layer-003` is the fourth layer from the bottom. And for ImageKit, it will be `5`. Or you can refer by name i.e. `layer-003`.
* `layer-4` is the fifth layer from the bottom. And for ImageKit, it will be `6`.

Now, let's see how we can extract a single layer, a range of layers, and multiple layers from this PSD file.


{% linetabs %}

{% linetab title="Default thumbnail" %}
URL - [https://ik.imagekit.io/ikmedia/layout.psd/ik-thumbnail.jpg?tr=pg-1](https://ik.imagekit.io/ikmedia/layout.psd/ik-thumbnail.jpg?tr=pg-1)

It will combine all the layers and generate a thumbnail.

![](https://ik.imagekit.io/ikmedia/layout.psd/ik-thumbnail.jpg?tr=pg-1)
{% /linetab %}

{% linetab title="pg-2" %}
URL - [https://ik.imagekit.io/ikmedia/layout.psd/ik-thumbnail.jpg?tr=pg-2](https://ik.imagekit.io/ikmedia/layout.psd/ik-thumbnail.jpg?tr=pg-2)

Technically, the first layer from the bottom.

![](https://ik.imagekit.io/ikmedia/layout.psd/ik-thumbnail.jpg?tr=pg-2)
{% /linetab %}

{% linetab title="pg-3-4" %}
URL - [https://ik.imagekit.io/ikmedia/layout.psd/ik-thumbnail.jpg?tr=pg-3-4](https://ik.imagekit.io/ikmedia/layout.psd/ik-thumbnail.jpg?tr=pg-3-4)

2nd and 3rd layers combined using `3-4`.

![](https://ik.imagekit.io/ikmedia/layout.psd/ik-thumbnail.jpg?tr=pg-3-4)
{% /linetab %}

{% linetab title="pg-3-" %}
URL - [https://ik.imagekit.io/ikmedia/layout.psd/ik-thumbnail.jpg?tr=pg-3-](https://ik.imagekit.io/ikmedia/layout.psd/ik-thumbnail.jpg?tr=pg-3-)

All layers after the 2nd one.

![](https://ik.imagekit.io/ikmedia/layout.psd/ik-thumbnail.jpg?tr=pg-3-)
{% /linetab %}

{% linetab title="pg-2_3-4" %}
URL - [https://ik.imagekit.io/ikmedia/layout.psd/ik-thumbnail.jpg?tr=pg-2_3-4](https://ik.imagekit.io/ikmedia/layout.psd/ik-thumbnail.jpg?tr=pg-2_3-4)

1st layer using `2`, and then everything between 2nd and 3rd layer (inclusive) using `3-4`.

![](https://ik.imagekit.io/ikmedia/layout.psd/ik-thumbnail.jpg?tr=pg-2_3-4)
{% /linetab %}

{% linetab title="Using layer name" %}
URL - [https://ik.imagekit.io/ikmedia/layout.psd/ik-thumbnail.jpg?tr=pg-name-"layer-4"_"layer-002"](https://ik.imagekit.io/ikmedia/layout.psd/ik-thumbnail.jpg?tr=pg-name-"layer-4"_"layer-002")

Here, we are referring to layers by name - `layer-4` and `layer-002`.

![](<https://ik.imagekit.io/ikmedia/layout.psd/ik-thumbnail.jpg?tr=pg-name-"layer-4"_"layer-002">)
{% /linetab %}
{% /linetabs %}

**Usage In Overlays**

Adding `ik-thumbnail.jpg` after the file URL resource is not required in overlays.

URL - [https://ik.imagekit.io/ikmedia/tr:l-image,i-layout.psd,pg-3,h-200,w-200,l-end/medium\_cafe\_B1iTdD0C.jpg](https://ik.imagekit.io/ikmedia/tr:l-image,i-layout.psd,pg-3,h-200,w-200,l-end/medium\_cafe\_B1iTdD0C.jpg)

![](https://ik.imagekit.io/ikmedia/tr:l-image,i-layout.psd,pg-3,h-200,w-200,l-end/medium\_cafe\_B1iTdD0C.jpg)

{% callout style="info" %}
`pg` is not supported in [conditional transformations](/conditional-transformations).
{% /callout %}

## GIF to video

Converting GIF images to videos is a recommended practice because GIFs often have large file sizes due to the numerous frames they contain. Using videos instead of GIFs on websites or mobile apps offers several advantages, which are detailed in Google's documentation available [here](https://web.dev/articles/replace-gifs-with-videos).

This method helps optimize load times because videos typically have better compression and loading efficiency compared to GIFs. By reducing file size, download and rendering times are quicker, leading to an enhanced user experience. Developers can improve website and app performance by incorporating video files, resulting in smoother interactions and faster content delivery.

ImageKit.io allows you to convert your GIF images to Video files very easily and efficiently using the URL-based transformation parameter.

To convert a GIF image to a video file, add `ik-gif-video.mp4` after the GIF resource URL.

**Syntax**

```
https://ik.imagekit.io/ikmedia/docs_images/examples/gif-test.gif/ik-gif-video.mp4
```

{% linetabs %}
{% linetab title="GIF image" %}
[https://ik.imagekit.io/ikmedia/docs_images/examples/gif-test.gif](https://ik.imagekit.io/ikmedia/docs_images/examples/gif-test.gif)

![GIF Image - 1422 KB](<https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/Gif_example_OGDIAoHwf.png?updatedAt=1711948906457>)

{% /linetab %}
{% linetab title="GIF to video" %}
[https://ik.imagekit.io/ikmedia/docs_images/examples/gif-test.gif/ik-gif-video.mp4](https://ik.imagekit.io/ikmedia/docs_images/examples/gif-test.gif/ik-gif-video.mp4)

![Video file - 179 KB](<https://ik.imagekit.io/ikmedia/docs_images/features/image-transformations/Video_example_bsKycWOb0.png?updatedAt=1711948947338>)

{% /linetab %}
{% /linetabs %}

You can transform the final video using any [video transformation](/video-transformation) supported by ImageKit.io.


---

# Source: /conditional-transformations

---
title: Conditional Transformations
description: You can apply transformations conditionally based on certain properties of the input asset.
---

Transformations can be applied conditionally, i.e., only if certain properties of the input asset satisfy a given condition. To accomplish this, you can create `if-else` - like constructs within an asset URL.

The syntax to build and specify a conditional transformation block is:

`if-{condition},{transformations_on_true},if-else,{transformations_on_false},if-end`

For example, you can resize all landscape images to a certain width, say 200, while resizing portrait images to a width of 300. The value of the `ar` (aspect ratio) property of an image helps determine whether it has a landscape (> 1) or portrait (< 1) orientation.

```markup
                                    1       2             3                   
                                  ┌─────┐ ┌───┐         ┌───┐
https://ik.imagekit.io/demo/tr:if-ar_gt_1,w-200,if-else,w-300,if-end/default-image.jpg
```

1. **condition**: A condition based on a property of the image that evaluates to either true or false. It has the format `if-{property}_{operator}_{value}`. [Learn more](#how-to-specify-the-condition-part).
2. **transformations_on_true**: Transformations that are applied only if the preceding condition evaluates to true. This can be a [chain](/transformations#chained-transformations) of transformations as well.
2. **transformations_on_false** (optional): Transformations that are applied only if the preceding condition evaluates to false. This can be a [chain](/transformations#chained-transformations) of transformations as well. This part along with the preceding `if-else` are optional and can be skipped.

## How to specify the condition part
The `condition` part in the above syntax can be built using a predefined set of image properties, comparison operators, and logical operators. A singular condition follows the `{property}_{operator}_{value}` syntax. For example, `if-h_gt_100` evaluates to true if the height of the image is greater than 100.

You can combine multiple conditions using the `and` and `or` logical operators. For example, `if-h_gte_100_and_h_lte_400_or_ar_lt_4-3` evaluates to true only if the image height is between 100 and 400, or the aspect ratio is less than 4:3.

{% callout style="info" %}
`and` operator has precedence over `or` operator during condition evaluation.
{% /callout %}

### Supported properties

{% table %}
* **Property** {% width="30%" %}
* **Allowed values** {% width="40%" %}
* **Description** {% width="30%" %}
---
- **h**
- Numbers
- Height of the image at the current step in a chain of transforms. eg. 100, 200.55

---

- **w**
- Numbers
- Width of the image at the current step in a chain of transforms. eg. 100, 200.55

---

- **ar**
- Numbers, Fraction (aspect ratio of 4:3 can be specified as 4-3)
- Aspect ratio of the image at the current step in a chain of transforms. eg. 100, 200.55, 4-3

---

- **ih**
- Numbers
- Height of the original, untransformed image. eg. 100, 200.55

---

- **iw**
- Numbers
- Width of the original, untransformed image. eg. 100, 200.55

---

- **iar**
- Numbers
  
  Fraction (aspect ratio of 4:3 can be specified as 4-3)
- Aspect ratio of the original, untransformed image. eg. 100, 200.55, 4-3
  
{% /table %}


### Supported operators
| Operator | Description                                                                        |
| -------- | ---------------------------------------------------------------------------------- |
| eq       | `h_eq_100` evaluates to true if the image height is equal to 100.                  |
| ne       | `h_ne_100` evaluates to true if the image height is not equal to 100.              |
| gt       | `h_gt_100` evaluates to true if the image height is greater than 100 .             |
| gte      | `h_gte_100` evaluates to true if the image height is greater than or equal to 100. |
| lt       | `h_lt_100` evaluates to true if the image height is less than 100.                 |
| lte      | `h_lte_100` evaluates to true if the image height is less than or equal to 100.    |

## How to specify transformations
You can specify a set of any supported transformations, or a [chain](/transformations#chained-transformations) of transformations, in place of the `transformations_on_true` and `transformations_on_false` parts. The former will be applied if the condition evaluates to true. The latter will be applied if the condition evaluates to false. The `if-else` and the succeeding transformations are optional.

For example, `if-ar_gt_1,w-200,if-else,w-300,if-end` and `if-ar_gt_1,w-200,if-end` are both valid.

{% callout style="info" %}
Conditional transformations are not supported for gif files yet.
{% /callout %}

## Usage with chained transformations
An `if` block can be one of the steps in a [chain](/transformations#chained-transformations) of transformations. For example, in `h-200,c-pad_resize:if-h_eq_200,w-100,if-end:rt-90`, the if block is the second step in a chain of three steps. The height value that this block receives for evaluating the `h_eq_100` condition, will be 200 since the previous step in the chain resizes the image to a height of 200. Hence, the condition will evaluate to true.

{% callout style="warning" %}
A step containing an if block cannot contain any other comma-separated transform within that step. For example, `h-400:rt-90,if-h_eq_200,w-100,if-end:rt-90` or `h-400:if-h_eq_200,w-100,if-end,bl-10:rt-90` or `h-100,if-h_eq_200,w-100,if-end` are all invalid.
{% /callout %}


---

# Source: /video-transformation

---
title: Video Transformation
description: Learn how to transform videos using the ImageKit.io 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                                    
┌──────────────────────────┐┌────────────┐┌───────────────┐        
https://ik.imagekit.io/demo/tr:w-300,h-300/sample-video.mp4
```

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

`https://ik.imagekit.io/ikmedia/docs_images/examples/Videos/example_video_2.mp4`

{% linetabs %}

{% linetab title="Resized 300x300 video" %}
[https://ik.imagekit.io/ikmedia/tr:w-300,h-300/docs_images/examples/Videos/example_video_2.mp4](https://ik.imagekit.io/ikmedia/tr:w-300,h-300/docs_images/examples/Videos/example_video_2.mp4)

{% video src="https://ik.imagekit.io/ikmedia/tr:w-300,h-300/docs_images/examples/Videos/example_video_2.mp4" alt="Resized 300x300 video" /%}

{% /linetab %}

{% linetab title="First 6 seconds" %}
[https://ik.imagekit.io/ikmedia/tr:du-6/docs_images/examples/Videos/example_video_2.mp4](https://ik.imagekit.io/ikmedia/tr:du-6/docs_images/examples/Videos/example_video_2.mp4)

{% video src="https://ik.imagekit.io/ikmedia/tr:du-6/docs_images/examples/Videos/example_video_2.mp4" /%}

{% /linetab %}

{% /linetabs %}

## Video transformation overview

Overview of different video transformations available in ImageKit.

* [Basic video resizing and cropping](/video-resize-and-crop). Learn different crop modes to adapt videos for different layouts.
* Adding text and image overlays. [Learn more](/add-overlays-on-videos).
* Create thumbnails from videos. [Learn more](/create-video-thumbnails).
* Trim videos from a specific time for a specific duration. [Learn more](/trim-videos).
* Leverage [adaptive bitrate streaming](/adaptive-bitrate-streaming) for streaming long duration videos.

## Limits and supported video formats

Refer to [supported video formats](/transformations#supported-formats) for a list of video formats supported by ImageKit.io for transformations. Check out various [limits](/transformations#limits).

## Pricing
Every new video transformation that has never been done before will contribute toward video processing units using the below definition. You can [read more about how video processing units are consumed](/how-pricing-works#video-processing-units-pricing) based on output video codec, duration, and resolution here.

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

![Video polling attempts](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/video-polling-settings.png?tr=w-1600)

## Recommendations

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](/video-webhook-events) to get updates on asset transformations.

If you upload video files to ImageKit using the [upload API](/api-reference/upload-file/upload-file-v2), 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](/dam/pre-and-post-transformation-on-upload).

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


---

# Source: /video-resize-and-crop

---
title: Resize and Crop Videos
description: Learn how to resize and crop videos using the ImageKit.io URL-based transformation parameters.
---

## Width - (w)

Used to specify the width of the output video. Accepts integer value greater than 1.

You can also provide an arithmetic expression such as `iw_div_2`, `cw_mul_0.8`, or `ih` as a value for this parameter. Doing so will first calculate the value of the expression and then apply transformations using that value. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).

When you specify just width, the height is adjusted accordingly to maintain the aspect ratio.

{% linetabs %}
{% linetab title="Original (1280x720)" %}

[https://ik.imagekit.io/demo/sample-video.mp4](https://ik.imagekit.io/demo/sample-video.mp4)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4" alt="Original 1280x720 px video" /%}

{% /linetab %}
{% linetab title="Width 300px" %}

[https://ik.imagekit.io/demo/sample-video.mp4?tr=w-300](https://ik.imagekit.io/demo/sample-video.mp4?tr=w-300)

Notice that the height is automatically adjusted to maintain the aspect ratio.

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=w-300" alt="Width 300px video" /%}

{% /linetab %}

{% linetab title="Width iw_div_2" %}
To reduce the width to half, use the following URL.
[https://ik.imagekit.io/demo/sample-video.mp4?tr=w-iw_div_2](https://ik.imagekit.io/demo/sample-video.mp4?tr=w-iw_div_2)


{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=w-iw_div_2" alt="Width 640px (Half of original)" /%}

{% /linetab %}
{% /linetabs %}

## Height - (h)

Used to specify the height of the output video. Accepts integer value greater than 1.

You can also provide an arithmetic expression such as `ih_div_2`, `ch_mul_0.5`, or `ih` as a value for this parameter. Doing so will first calculate the value of the expression and then apply transformations using that value. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).

When you specify only height, the width is adjusted accordingly to maintain the aspect ratio.

{% linetabs %}
{% linetab title="Original (1280x720)" %}
[https://ik.imagekit.io/demo/sample-video.mp4](https://ik.imagekit.io/demo/sample-video.mp4)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4" alt="Original video" /%}

{% /linetab %}

{% linetab title="Height 300px" %}
[https://ik.imagekit.io/demo/sample-video.mp4?tr=h-300](https://ik.imagekit.io/demo/sample-video.mp4?tr=h-300)

Notice that the width is automatically adjusted to maintain the aspect ratio.

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=h-300" alt="Height 300px video" /%}

{% /linetab %}

{% linetab title="Height ih_mul_0.4" %}
To reduce the height to 40 percent of original, use the following URL.
[https://ik.imagekit.io/demo/sample-video.mp4?tr=h-ih_mul_0.4](https://ik.imagekit.io/demo/sample-video.mp4?tr=h-ih_mul_0.4)


{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=h-ih_mul_0.4" alt="Height 288px (40% of original)" /%}

{% /linetab %}
{% /linetabs %}

## Aspect ratio - (ar)

Used to specify the aspect ratio of the output video. It is the ratio of width to height of the output video. This parameter must be used along with either the [height(h)](#height---h) or [width(w)](#width---w) parameter but not both.

You can also provide an arithmetic expression such as `iar_div_2`, or `car_mul_0.75` as a value for this parameter. Doing so will first calculate the value of the expression and then apply transformations using that value. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).

Usage = `ar-<width>_<height>`

{% callout style="info" %}
If you specify both [height(h)](#height---h) and [width(w)](#width---w) in the URL along with [aspect ratio(ar)](#aspect-ratio---ar), then the aspect ratio is ignored.
{% /callout %}

{% linetabs %}
{% linetab title="Original (1280x720)" %}
URL - [https://ik.imagekit.io/demo/sample-video.mp4](https://ik.imagekit.io/demo/sample-video.mp4)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4" alt="Original video" /%}

{% /linetab %}

{% linetab title="width 400px and aspect ratio 4:1" %}
URL - [https://ik.imagekit.io/demo/sample-video.mp4?tr=ar-4_1,h-100](https://ik.imagekit.io/demo/sample-video.mp4?tr=ar-4_1,h-100)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=ar-4_1,h-100" alt="Width 400px and aspect ratio 4:1 video" /%}

{% /linetab %}

{% linetab title="Width 400px and aspect ratio iar_mul_2" %}
To double the aspect ratio with width 400px, use the following URL.
[https://ik.imagekit.io/demo/sample-video.mp4?tr=w-400,ar-iar_mul_2](https://ik.imagekit.io/demo/sample-video.mp4?tr=w-400,ar-iar_mul_2)


{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=w-400,ar-iar_mul_2" alt="width 400px and aspect ratio double of initial" /%}

{% /linetab %}
{% /linetabs %}

## Crop, Crop Modes, and Focus

If only, one of the [height(h)](#height---h) or [width(w)](#width---w) is specified, then ImageKit.io adjusts the other dimension accordingly to preserve aspect ratio and no cropping takes place.

But when you specify both [height(h)](#height---h) and [width(w)](#width---w) dimensions, you need to choose the right cropping strategy based on your website layout and desired output video.

{% callout style="info" %}

**Tip for choosing the right cropping strategy**

When choosing among different strategies for cropping, think in terms of your website layout and desired output video dimension.
{% /callout %}

* If you want to preserve the whole video content without any cropping and need the exact same dimensions (height and width) in the output as requested, choose either the [pad resize crop](#pad-resize-crop-strategy---cm-pad_resize) or [forced crop strategy](#forced-crop-strategy---c-force).
* If you want to preserve the whole video content without any cropping, but it is okay if one or both the dimensions (height or width) in the output are adjusted to preserve the aspect ratio. Then choose either the [max-size cropping](#max-size-cropping-strategy---c-at_max) or [min-size cropping](#min-size-cropping-strategy---c-at_least) strategy.
* If you need the exact same dimensions (height and width) in the output video as requested but it's okay to crop the video to preserve the aspect ratio. Then choose either the [maintain ratio crop](#maintain-ratio-crop-strategy---c-maintain_ratio) or the [extract crop](#extract-crop-strategy---cm-extract) strategy. You can combine the extract crop strategy with different [focus](#focus---fo) values to get the desired result.

## Pad resize crop strategy - (cm-pad_resize)

In the pad resize crop strategy, the output dimension (height and width) is the same as requested, no cropping takes place, and the aspect ratio is preserved. This is accomplished by adding padding around the video to get it to match the exact dimension as requested.

### Example - All padding on one side

In the examples above, we saw that when the video is padded using the [pad resize crop strategy](#pad-resize-crop-strategy---cm-pad_resize), the padding is equal on both sides of the video. However, there might be cases where we want all the padding to be added on only one side of the video. This can be done using the [focus (fo)](#focus---fo) parameter.

{% linetabs %}
{% linetab title="Default crop (400x200)" %}
[https://ik.imagekit.io/demo/sample-video.mp4?tr=w-400,h-200](https://ik.imagekit.io/demo/sample-video.mp4?tr=w-400,h-200)

The video is 400x200 but it is cropped from all sides to preserve the aspect ratio.

{%video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=w-400,h-200" alt="Default crop 400x200" /%}


{% /linetab %}

{% linetab title="cm-pad_resize (center focus)" %}
[https://ik.imagekit.io/demo/sample-video.mp4?tr=w-400,h-200,cm-pad_resize,bg-F3F3F3](https://ik.imagekit.io/demo/sample-video.mp4?tr=w-400,h-200,cm-pad_resize,bg-F3F3F3)

The video is exactly 400x200 and there is no cropping. Extra padding with [background color](#background-bg) F3F3F3 has been added to get 400x200 output dimensions.

{%video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=w-400,h-200,cm-pad_resize,bg-F3F3F3" alt="cm-pad_resize with center focus" /%}

{% /linetab %}

{% linetab title="cm-pad_resize with blurred background" %}
[https://ik.imagekit.io/demo/sample2.mp4?tr=w-400,h-200,cm-pad_resize,bg-blurred](https://ik.imagekit.io/demo/sample2.mp4?tr=w-400,h-200,cm-pad_resize,bg-blurred)

The video is exactly 400x200 and there is no cropping. The extra padding added consists of a [blurred background](#background-bg) made using the source video to get 400x200 output dimensions.

{%video src="https://ik.imagekit.io/demo/sample2.mp4?tr=w-400,h-200,cm-pad_resize,bg-blurred" alt="cm-pad_resize with blurred background" /%}

{% /linetab %}

{% linetab title="cm-pad_resize (left)" %}
You can also control the focus point using [fo parameter](#focus---fo) to move the actual content to one side using relative positioning.

We added the `fo-left`. Now, all the padding is on the right of the video.

{%video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=w-400,h-200,cm-pad_resize,fo-left" alt="cm-pad_resize with left focus" /%}
{% /linetab %}
{% /linetabs %}

## Forced crop strategy - (c-force)

In a forced crop strategy, the output video's dimension (height and width) is exactly the same as requested, no cropping takes place, but the aspect ratio is not preserved. It forcefully squeezes the original video to get it to fit completely within the output dimensions.

URL - [https://ik.imagekit.io/demo/sample-video.mp4?tr=w-200,h-200,c-force](https://ik.imagekit.io/demo/sample-video.mp4?tr=w-200,h-200,c-force)

Notice that the aspect ratio is changed and the video looks squeezed.

{%video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=w-200,h-200,c-force" alt="Forced crop 200x200" /%}

## Max-size cropping strategy - (c-at_max)

In the max-size crop strategy, the whole video content is preserved without any cropping, and the aspect ratio is preserved, but one of the dimensions (height or width) is adjusted.

The output video is less than or equal to the dimensions specified in the URL,i.e., at least one dimension will exactly match the output dimension requested, and the other dimension will be equal to or smaller than the corresponding output dimension requested.

URL - [https://ik.imagekit.io/demo/sample-video.mp4?tr=w-200,h-200,c-at_max](https://ik.imagekit.io/demo/sample-video.mp4?tr=w-200,h-200,c-at_max)

Notice that the aspect ratio is maintained, and there is no cropping. However, the height is reduced so that the video fits within a 200x200 container.

{%video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=w-200,h-200,c-at_max" alt="Max-size crop 200x200" /%}

{% callout style="info" %}
**Note:** For all new ImageKit accounts created after 13 October 2025, the `c-at_max` crop mode does **not** enlarge videos by default. To maintain backward compatibility for existing accounts, we’ve introduced the **“Allow upscaling with c-at_max”** setting.

- When this setting is **enabled**, `c-at_max` behaves like `c-at_max_enlarge`, allowing videos to scale beyond their original resolution while maintaining aspect ratio.
- When this setting is **disabled**, `c-at_max` will **not** enlarge videos beyond their original size.

Any changes to this setting will apply only to new transformations. Existing cached transformations will need a cache purge to reflect the update.
{% /callout %}

## Max-size-enlarge cropping strategy - (c-at_max_enlarge)

This strategy is similar to the [max-size cropping](#max-size-cropping-strategy---c-at_max) strategy, except it also allows a video to be enlarged beyond its original dimensions.

The output video is less than or equal to the dimensions specified in the URL, i.e., at least one dimension will exactly match the output dimension requested, and the other dimension will be equal to or smaller than the corresponding output dimension requested.

{% linetabs %}
{% linetab title="Original (426x240)" %}

URL - [https://ik.imagekit.io/demo/parrot.mp4](https://ik.imagekit.io/demo/parrot.mp4)

{%video src="https://ik.imagekit.io/demo/parrot.mp4" alt="Original (426x240)" /%}

{% /linetab %}
{% linetab title="c-at_max_enlarge" %}

URL - [https://ik.imagekit.io/demo/parrot.mp4?tr=w-1200,h-800,c-at_max_enlarge](https://ik.imagekit.io/demo/parrot.mp4?tr=w-1200,h-800,c-at_max_enlarge)

The aspect ratio is maintained, and there is no cropping. However, the video is enlarged to match the requested dimensions.

{%video src="https://ik.imagekit.io/demo/parrot.mp4?tr=w-1200,h-800,c-at_max_enlarge" alt="Max-size-enlarge crop 1200x800" /%}

{% /linetab %}
{% /linetabs %}

{% callout style="warning" %}
**Note:** The `c-at_max_enlarge` parameter allows videos to be scaled beyond their original dimensions, which may result in lower quality output. Use this parameter only when you specifically need to enlarge videos.
{% /callout %}

## Min-size cropping strategy - (c-at_least)

This strategy is similar to the [max-size cropping](#max-size-cropping-strategy---c-at_max) strategy, with the only difference being that, unlike the max-size strategy, the output video dimension is equal to or larger than the requested dimensions. One of the dimensions will be exactly the same as what is requested, while the other dimension will be equal to or larger than what is requested.

URL - [https://ik.imagekit.io/demo/sample-video.mp4?tr=w-200,h-200,c-at_least](https://ik.imagekit.io/demo/sample-video.mp4?tr=w-200,h-200,c-at_least)

Notice that the height is 200px as requested, but the width is more than 200px. The aspect ratio is maintained and there is no cropping.

{%video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=w-200,h-200,c-at_least" alt="Min-size crop 200x200" /%}

## Maintain ratio crop strategy - (c-maintain_ratio)

This is the default crop strategy. If no crop (`c`) or crop_mode (`cm`) is specified in the URL, `c-maintain_ratio` gets applied automatically.

In this strategy, the output video's dimensions (height and width) are the same as requested, and the aspect ratio is preserved. This is accomplished by resizing the video to the requested dimension and then cropping extra parts to get the desired height & width.

{% callout style="info" %}
By default, ImageKit.io crops the video from the center, but you can change this using the [focus parameter](#focus---fo).
{% /callout %}

{% linetabs %}
{% linetab title="Original" %}
URL - [https://ik.imagekit.io/demo/sample-video.mp4](https://ik.imagekit.io/demo/sample-video.mp4)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4" alt="Original video" /%}

{% /linetab %}

{% linetab title="w-400,h-300,c-maintain_ratio" %}
URL - [https://ik.imagekit.io/demo/sample-video.mp4?tr=w-400,h-300,c-maintain_ratio](https://ik.imagekit.io/demo/sample-video.mp4?tr=w-400,h-300,c-maintain_ratio)

[`w-400,h-300,c-maintain_ratio`](https://ik.imagekit.io/demo/sample-video.mp4?tr=w-400,h-300,c-maintain_ratio) is equivalent to [`w-400,h-300`](https://ik.imagekit.io/demo/sample-video.mp4?tr=w-400,h-300) because `maintain_ratio` is the default crop strategy.

Notice that the video's dimension matches 400x300, but the content is cropped from all edges, i.e., by default, ImageKit will extract the video from the center.

{%video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=w-400,h-300,c-maintain_ratio" alt="w-400,h-300,c-maintain_ratio" /%}
{% /linetab %}

{% linetab title="w-400,h-300,c-maintain_ratio,fo-left" %}
URL - [https://ik.imagekit.io/demo/sample-video.mp4?tr=w-400,h-300,c-maintain_ratio,fo-left](https://ik.imagekit.io/demo/sample-video.mp4?tr=w-400,h-300,c-maintain_ratio,fo-left)

Using the [focus (`fo`) parameter](#focus---fo), you can specify the side to crop from.

Here the video's dimension matches 400x300 and crops out the content on right side, because focus (`fo`) is set to `left`.

{%video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=w-400,h-300,c-maintain_ratio,fo-left" alt="w-400,h-300,c-maintain_ratio,fo-left" /%}

{% /linetab %}
{% /linetabs %}

## Extract crop strategy - (cm-extract)

In this strategy, the output video's dimension (height and width) is exactly the same as requested, and the aspect ratio is preserved. In this strategy, instead of trying to resize the video as we did in [maintain ratio](#maintain-ratio-crop-strategy---c-maintain_ratio) strategy, we extract out a region of the requested dimension from the original video.

{% callout style="info" %}
By default, ImageKit.io extracts the video from the center but you can change this using the [focus parameter](#focus---fo).
{% /callout %}

### Examples - Center and relative focus

{% linetabs %}
{% linetab title="Default center extract" %}
URL - [https://ik.imagekit.io/demo/sample-video.mp4?tr=h-300,w-300,cm-extract](https://ik.imagekit.io/demo/sample-video.mp4?tr=h-300,w-300,cm-extract)

A 300x300 part is extracted from the center of the original video.

{%video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=h-300,w-300,cm-extract" alt="Default center extract 300x300" /%}

{% /linetab %}

{% linetab title="Relative focus" %}
In the relative method, you can use the [focus (fo) parameter](#focus---fo) to specify that the extract should be done from, let's say, the bottom of the original video.

URL - [https://ik.imagekit.io/demo/sample-video.mp4?tr=h-300,w-300,cm-extract,fo-bottom](https://ik.imagekit.io/demo/sample-video.mp4?tr=h-300,w-300,cm-extract,fo-bottom)

{%video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=h-300,w-300,cm-extract,fo-bottom" alt="Relative focus extract 300x300" /%}

{% /linetab %}
{% /linetabs %}

## Focus - (fo)

This parameter can be used along with [pad resize](#pad-resize-crop-strategy---cm-pad_resize), [maintain ratio](#maintain-ratio-crop-strategy---c-maintain_ratio) or [extract crop](#extract-crop-strategy---cm-extract) to change the behavior of padding or cropping. Learn more from the different examples shown in respective sections.

This parameter can have the following values depending upon where it is being used:

1. `left`, `right`, `top`, `bottom` can be to control the position of padding when used with pad resize. [Learn from examples](#example---all-padding-on-one-side).
2. `center`, `top`, `left`, `bottom`, `right`, `top_left`, `top_right`, `bottom_left` and `bottom_right` can be used to define relative cropping during extract crop. [Learn from examples](#examples---center-and-relative-focus).

Beyond static positioning, the `fo` parameter also supports AI-powered smart cropping that can automatically detect and track subjects throughout your video. This includes automatic smart crop (`fo-auto`) for general content, face detection and tracking (`fo-face`), and object-aware cropping (`fo-<object>`) that can focus on specific objects like people, cars, or animals from our supported object list.

## Automatic smart crop - (fo-auto)

Automatically detects and tracks the most important objects in your video, ensuring they remain centered as the video progresses. This feature is ideal for creating engaging social media content from longer videos. When using `fo-auto`, you must specify both dimensions—either provide both `height` and `width`, or specify one dimension along with the `ar` (aspect ratio) parameter. The unspecified dimension will be calculated automatically to maintain the aspect ratio.

{% linetabs %}
{% linetab title="Original scene (960x506)" %}

URL - [https://ik.imagekit.io/demo/skateboarding.mp4](https://ik.imagekit.io/demo/skateboarding.mp4)

{%video src="https://ik.imagekit.io/demo/skateboarding.mp4?tr=f-auto" /%}

{% /linetab %}
{% linetab title="Smart crop to 3:4 aspect ratio" %}

URL - [https://ik.imagekit.io/demo/skateboarding.mp4?tr=fo-auto,w-300,ar-3_4](https://ik.imagekit.io/demo/skateboarding.mp4?tr=fo-auto,w-300,ar-3_4)

The AI automatically keeps the skateboarder in focus while converting to a vertical format, perfect for social media.

{%video src="https://ik.imagekit.io/demo/skateboarding.mp4?tr=fo-auto,w-300,ar-3_4" /%}

{% /linetab %}
{% linetab title="Extract exact dimensions" %}

URL - [https://ik.imagekit.io/demo/skateboarding.mp4?tr=fo-auto,w-480,h-360,cm-extract](https://ik.imagekit.io/demo/skateboarding.mp4?tr=fo-auto,w-480,h-360,cm-extract)

Extract a precise 480×360 section while keeping the action centered throughout the video.

{%video src="https://ik.imagekit.io/demo/skateboarding.mp4?tr=fo-auto,w-480,h-360,cm-extract" /%}

{% /linetab %}
{% /linetabs %}

## Face crop - (fo-face)

Detects and follows faces in your video, automatically keeping them centered and in focus. When multiple faces are present, it focuses on the most prominent one.

{% linetabs %}
{% linetab title="Original scene (1942x1024)" %}

URL - [https://ik.imagekit.io/demo/speak-phone.mp4](https://ik.imagekit.io/demo/speak-phone.mp4)

{%video src="https://ik.imagekit.io/demo/speak-phone.mp4?tr=f-auto" /%}

{% /linetab %}
{% linetab title="Auto-crop to face" %}

URL - [https://ik.imagekit.io/demo/speak-phone.mp4?tr=fo-face](https://ik.imagekit.io/demo/speak-phone.mp4?tr=fo-face)

Automatically determines the optimal crop size to keep the face in focus throughout the video.

{%video src="https://ik.imagekit.io/demo/speak-phone.mp4?tr=fo-face" /%}

{% /linetab %}
{% linetab title="Face crop with 9:16 aspect ratio" %}

URL - [https://ik.imagekit.io/demo/speak-phone.mp4?tr=fo-face,ar-9_16](https://ik.imagekit.io/demo/speak-phone.mp4?tr=fo-face,ar-9_16)

Perfect for creating vertical videos for mobile platforms while keeping the face centered.

{%video src="https://ik.imagekit.io/demo/speak-phone.mp4?tr=fo-face,ar-9_16" /%}

{% /linetab %}
{% linetab title="Extract specific dimensions" %}

URL - [https://ik.imagekit.io/demo/speak-phone.mp4?tr=fo-face,w-400,h-600,cm-extract](https://ik.imagekit.io/demo/speak-phone.mp4?tr=fo-face,w-400,h-600,cm-extract)

Extract a 400×600 portion while keeping the face optimally positioned.

{%video src="https://ik.imagekit.io/demo/speak-phone.mp4?tr=fo-face,w-400,h-600,cm-extract" /%}

{% /linetab %}
{% /linetabs %}

## Object-aware cropping - (fo-object name)

Focus on specific objects in your video by specifying any object from the [supported list](image-resize-and-crop#supported-object-list). The AI will track and keep the specified object in focus throughout the video.

{% linetabs %}
{% linetab title="Original scene (720x1280)" %}

URL - [https://ik.imagekit.io/demo/bench.mp4](https://ik.imagekit.io/demo/bench.mp4)

{%video src="https://ik.imagekit.io/demo/bench.mp4?tr=f-auto" /%}
{% /linetab %}
{% linetab title="Focus on dog" %}

URL - [https://ik.imagekit.io/demo/bench.mp4?tr=fo-dog](https://ik.imagekit.io/demo/bench.mp4?tr=fo-dog)

Intelligently crop the video to keep the dog in the view.

{%video src="https://ik.imagekit.io/demo/bench.mp4?tr=fo-dog" /%}
{% /linetab %}
{% linetab title="Focus on person" %}

URL - [https://ik.imagekit.io/demo/bench.mp4?tr=fo-person](https://ik.imagekit.io/demo/bench.mp4?tr=fo-person)

Intelligently crop the video to keep the person in the view.

{%video src="https://ik.imagekit.io/demo/bench.mp4?tr=fo-person" /%}
{% /linetab %}
{% /linetabs %}

{% callout style="info" %}
**Auto-sizing with smart crop:** When using face crop (`fo-face`) or object-aware cropping (`fo-<object>`), you can omit width and height parameters to let the AI automatically determine the optimal crop size. Use the `ar` parameter to specify your preferred aspect ratio, and the AI will adjust the crop area to match while keeping the subject in focus.
{% /callout %}

## Limitations and considerations for video smart crop

{% callout style="warning" %}
**Crop mode compatibility:** Video smart crop only works with `c-maintain_ratio` (default) and `cm-extract` crop modes. All other crop modes (defined with `c` or `cm`) are invalid.
{% /callout %}

1. Video smart crop is available when base asset is video and inside video overlays (`l-video`). However, video smart crop is not available when input video codec is `MPEG-1 Video` or `MPEG-2 Video`.
2. Video smart crop is not available when input of video layer (`l-video`) is a GIF file.
3. Video smart crop is not available for image overlays (`l-image`) in video transformations.
4. Smart crop can only be performed on a video once, and it must be the first step of the chained transformations. \
  `tr=b-10_red:fo-person` - ❌ \
  `tr=fo-person:b-10_red` - ✅ \
  If you use smart crop inside a video layer (`l-video`), it must also be the first step within that layer’s chained transformations.
5. You cannot use rotate (`rt`) in the same step as smart crop. \
  `tr=fo-person,rt-90` - ❌ \
  If you want to rotate a video after applying smart crop, use chained transformation (separate the parameters with a `:`). \
  `tr=fo-person:rt-90` - ✅ will first crop around the `person` in the video, and then rotate the result by 90 degrees.
6. Arithmetic expressions are completely unsupported anywhere in the transformation when video smart crop is used.

## Video smart crop pricing

Video smart crop incurs additional video processing units beyond the standard consumption. Refer to the [Special Operations section under video transformation pricing](/how-pricing-works#video-processing-units-pricing) for more information.


---

# Source: /add-overlays-on-videos

---
title: Add overlays on videos
description: A comprehensive guide that covers how you can add images, videos, text and subtitles as overlays on videos using ImageKit.
---

With ImageKit, you can add images, videos, text and subtitles over a video using [layers](/transformations#overlay-using-layers). Skip to the relevant section to understand with a quick example:

* [Add images over video](#add-images-over-video)
* [Add text over video](#add-text-over-video)
* [Add video over video](#add-video-over-video)
* [Add solid color blocks over video](#add-solid-color-blocks-over-video)
* [Nest text and image layers inside canvas](#nest-text-and-image-layers-inside-canvas)
* [Add subtitles over a video](#add-subtitles-over-a-video)


## Add images over video

You can add an image over a base video using the following syntax.

```markup
         URL endpoint          Base video              Image layer
┌──────────────────────────┐┌──────────────┐    ┌──────────────────────┐
https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-logo.png,l-end
```

This URL overlays the image `logo.png` at the root of the account's media library on the video `sample-video.mp4`:

To use an image from your media library, set the value of either the `i` or `ie` parameter based on the characters in the image path:
* Use the `i-` parameter if the path contains only alphanumeric characters, "@", "-", or "_". In this case, simply pass the path as-is. eg. `i-simple-alpha@numeric_string.mov`
* If the path contains any other characters, it's recommended to use the `ie-` parameter. In this case, base64-encode the path first, then percent-encode the result.

Input (`i` or `ie`) for `l-image` can be JPG, PNG, WEBP, TIFF, or GIF files.

You can also control the position of the image overlay using these [positional parameters](/transformations#position-of-layer).

For example, let's add the [ImageKit logo](https://ik.imagekit.io/demo/logo.png) over a base video.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-logo.png,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-logo.png,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-logo.png,l-end" alt="Add images over video" /%}

{% callout style="info" %}
**Notes**
1. To overlay videos stored within a specific folder of your media library, use the complete video path where slashes (`/`) are replaced with `@@`.
    For example, if the overlay image is at \
    `https://ik.imagekit.io/demo/path/to/overlay.jpg`, then it can be used as an overlay like: \
    `https://ik.imagekit.io/demo/base-video.mp4?tr=l-image,i-path@@to@@overlay.jpg,l-end`
2. When a GIF file is used in the image layer, the 1st frame of the GIF is used as a static image. For animated GIF, you can use [video layer](#add-video-over-video) (`l-video`).

3. Animated-WebP and animated-PNG (`apng`) are not supported in ImageKit's video API.
{% /callout %}

You can also use an HTTP(S) URL of an image. ImageKit will fetch the image from the URL, and use it as the layer. Since URLs will always contain special characters, make sure to use `ie-` as described above.

For example, let's create the same result as above but using the [complete URL](https://ik.imagekit.io/demo/logo.png) for the ImageKit logo image.

[https://ik.imagekit.io/demo/tr:l-image,ie-aHR0cHM6Ly9pay5pbWFnZWtpdC5pby9kZW1vL2xvZ28ucG5nCg%3D%3D,l-end/sample-video.mp4](https://ik.imagekit.io/demo/tr:l-image,ie-aHR0cHM6Ly9pay5pbWFnZWtpdC5pby9kZW1vL2xvZ28ucG5nCg%3D%3D,l-end/sample-video.mp4)

{% video src="https://ik.imagekit.io/demo/tr:l-image,ie-aHR0cHM6Ly9pay5pbWFnZWtpdC5pby9kZW1vL2xvZ28ucG5nCg%3D%3D,l-end/sample-video.mp4" /%}


## Control time & position of image overlay

You can control the image layer position using the `lx`, `ly` and `lfo` parameters. Learn more about [positional parameters](/transformations#position-of-layer) in layers. You can also use [arithmetic expressions](/arithmetic-expressions-in-transformations) in `lx` and `ly` to better control the position of the overlay.


{% linetabs %}
{% linetab title="lx-100,ly-200" %}

Use the URL below to align the image at `100px` from the top-left corner in the `x` direction and `200px` in the `y` direction relative to the base video.
[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lx-100,ly-200,i-logo.png,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lx-100,ly-200,i-logo.png,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lx-100,ly-200,i-logo.png,l-end" alt="Image aligned at 100px on 'X-axis' and 200px on 'Y-axis'" /%}

{% /linetab %}
{% linetab title="lx-bw_mul_0.5,ly-bh_mul_0.3" %}

Use the URL below to align the image 50 percent from the top-left corner in the `x`  direction and 30 percent in the `y` direction relative to the base video.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lx-bw_mul_0.5,ly-bh_mul_0.3,i-logo.png,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lx-bw_mul_0.5,ly-bh_mul_0.3,i-logo.png,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lx-bw_mul_0.5,ly-bh_mul_0.3,i-logo.png,l-end" alt="Image aligned at 50% on 'X-axis' and 30% on 'Y-axis'" /%}

{% /linetab %}

{% linetab title="lx-bw_sub_iw,ly-100" %}

To align the image at `100px` from the top in the `y` direction and towards the right, use the below URL.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lx-bw_sub_iw,ly-100,i-logo.png,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lx-bw_sub_iw,ly-100,i-logo.png,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lx-bw_sub_iw,ly-100,i-logo.png,l-end" alt="Image aligned at 100px on 'Y-axis' and towards right" /%}

{% /linetab %}
{% linetab title="lfo-left" %}

To align the logo to the left of the video use `lfo-left`.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lfo-left,i-logo.png,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lfo-left,i-logo.png,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lfo-left,i-logo.png,l-end" alt="Left align image layer" /%}


{% /linetab %}
{% /linetabs %}

You can also use `lso`, `leo`, and `ldu` to control the time at which the overlay should start, end, and the duration of the overlay. Additionally, you can use arithmetic expressions like `bdu_div_2` and `bdu_mul_0.2` as a value for these parameters to better control the timing of the overlay. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).

{% callout style="info" %}
Inside `image` layer only `bdu` is a valid expression variable.
{% /callout %}

{% linetabs %}
{% linetab title="lso-3,leo-8" %}

To add the logo at 3 seconds and remove it at 8 seconds use `lso-3,leo-8`.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lso-3,leo-8,i-logo.png,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lso-3,leo-8,i-logo.png,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lso-3,leo-8,i-logo.png,l-end" alt="Add image layer at 3 seconds and remove at 8 seconds" /%}

{% /linetab %}
{% linetab title="lso-bdu_mul_0.1,leo-bdu_mul_0.8" %}

Use `lso-bdu_mul_0.1,leo-bdu_mul_0.8` to add the logo at 10 percent of the duration from the start and remove it after 80 percent of the total duration.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lso-bdu_mul_0.1,leo-bdu_mul_0.8,i-logo.png,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lso-bdu_mul_0.1,leo-bdu_mul_0.8,i-logo.png,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lso-bdu_mul_0.1,leo-bdu_mul_0.8,i-logo.png,l-end" alt="Add image layer at 10% and remove at 80% duration" /%}

{% /linetab %}
{% linetab title="lso-bdu_mul_0.1,ldu-bdu_mul_0.4" %}

Use `lso-bdu_mul_0.1,ldu-bdu_mul_0.4` to add the logo at 10 percent of the duration from the start and keep it for the next 40 percent.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lso-bdu_mul_0.1,ldu-bdu_mul_0.4,i-logo.png,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lso-bdu_mul_0.1,ldu-bdu_mul_0.4,i-logo.png,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lso-bdu_mul_0.1,ldu-bdu_mul_0.4,i-logo.png,l-end" alt="Add image layer at 10% and remove at 50% duration" /%}

{% /linetab %}
{% /linetabs %}

## Apply transformations on image overlay

Inside an image layer on the base video, you can apply these [supported transformations](#list-of-transformations-supported-on-image-overlay) to the image overlay before it is placed on the base video. You can [chain the transformations](/transformations#chained-transformations) one after other to achieve the desired outcome.

Let's resize the logo image to 100px width by adding `w-100` inside the image layer.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-logo.png,w-100,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-logo.png,w-100,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-logo.png,w-100,l-end" alt="Resize image layer" /%}

### List of transformations supported on image overlay

| Parameter                                                                                                      | Description                  |
|----------------------------------------------------------------------------------------------------------------|------------------------------|
| [w](/image-resize-and-crop#width---w)                                 | Width of overlay image. It can also accept arithmetic expressions such as `bw_div_2`, or `bw_sub_cw`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).  |
| [h](/image-resize-and-crop#height---h)                                | Height of overlay image. It can also accept arithmetic expressions such as `bh_div_2`, or `bh_sub_cw`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations). |
| [ar](/image-resize-and-crop#aspect-ratio---ar)                        | Aspect ratio of overlay image. It can also accept arithmetic expressions such as `iar_div_2`, or `bar`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations). |
| [c](/image-resize-and-crop#crop-crop-modes--focus)               | Cropping method. Accepts `force`, `at_max`, and `at_least`. |
| [cm](/image-resize-and-crop#crop-crop-modes--focus)              | Crop mode. Supports `extract` and `pad_resize`. |
| [fo](/image-resize-and-crop#focus---fo)                               | Relative focus area used during cropping. Accepts `center`, `top`, `left`, `bottom`, `right`, `top_left`, `top_right`, `bottom_left` and `bottom_right`. |
| [b](/effects-and-enhancements#border---b)                                | This adds a border to the overlay image. It accepts two parameters - the width of the border and the color of the border in format `b-<border-width>-<hex code>`. It can also accept arithmetic expressions such as `ih_div_20_red`, or `cw_mul_0.05_FF0000`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations). |
| [bg](/effects-and-enhancements#background---bg)                    | It is used to specify the background color in RGB Hex Code (e.g. FF0000) or an RGBA Code (e.g. FFAABB50) that must be used for the image. If you specify an 8-character background, the last two characters must be a number between 00 and 99, which is used to indicate the opacity level of the background. `00` represents an opacity level of `0.00`, `01`  represents opacity level `0.01`, and so on. |
| [r](/effects-and-enhancements#radius---r)                                | It is used to control the radius of the corner. To get a circle or oval shape, set the value to `max`. |
| [rt](/effects-and-enhancements#rotate---rt)                                | It is used to specify the degree by which the overlay image must be rotated. |

## Add text over video

You can add any text string over a base video using the following syntax.

```markup
         URL endpoint          Base video            Text layer
┌──────────────────────────┐┌──────────────┐    ┌──────────────────┐
https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,i-hello,l-end
```

In the above example, the string "hello" is overlaid on sample-video.mp4.

Set the value of either the `i` or `ie` parameter based on the characters in the text string:
* Use the `i-` parameter if the string contains only alphanumeric characters, "@", "-", or "_". In this case, simply pass the string as-is. eg. `i-simple-alpha@numeric_string`
* If the string contains any other characters, it's recommended to use the `ie-` parameter. In this case, base64-encode the string first, then percent-encode the result.

For example, to overlay the text `hello` on top of `sample-video.mp4`, use the following URL:

```markup
         URL endpoint         Base image                   Text layer
┌──────────────────────────┐┌──────────────┐    ┌──────────────────┐
https://ik.imagekit.io/demo/smaple-video.mp4?tr=l-text,i-hello,l-end
```

For a text string like `20% off discount`, use the following URL:

```markup
         URL endpoint         Base image                   Text layer
┌──────────────────────────┐┌──────────────┐    ┌──────────────────────────────────┐
https://ik.imagekit.io/demo/smaple-video.mp4?tr=l-text,ie-MjAlIG9mZiBkaXNjb3VudA%3D%3D,l-end
```

Here, `MjAlIG9mZiBkaXNjb3VudA%3D%3D` is the base64-encoded string for `20% off discount`, which is then percent-encoded.

In JavaScript, you can generate this value using:

```javascript
encodeURIComponent(btoa("20% off discount"))
```

You can also control the position of the text overlay using these [positional parameters](/transformations#position-of-layer).

Let's add "Hello" text over a base video. We will also use `fs-100,co-red` to set the font size to 100 and color to red.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,i-hello,fs-100,co-red,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,i-hello,fs-100,co-red,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,i-hello,fs-100,co-red,l-end" alt="Add text over video" /%}

{% callout style="info" %}
**Notes:**
1. Plain text input longer than 2000 characters will be truncated.
2. Base64 encoded text input longer than 2500 characters will be truncated.
{% /callout %}

{% callout style="warning" %}
**Text layer dimension limit** \
If the text layer takes up more than 16,383 pixels horizontally or vertically, then the request will error out.
{% /callout %}

## Control time & position of text overlay

You can control text layer position using the `lx`, `ly` and `lfo` parameters. To change the direction, negative values are also supported by prefixing the value with 'N'. You can also use [arithmetic expressions](/arithmetic-expressions-in-transformations) in `lx` and `ly` to better control the position of the overlay.

Learn more about [positional parameters](/transformations#position-of-layer) in layers.

{% linetabs %}
{% linetab title="lx-100,ly-200" %}

Use the URL below to align the text at `100px` from the top-left corner in the `x` direction and `200px` in the `y` direction relative to the base video.
[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,lx-100,ly-200,i-hello,fs-100,co-red,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,lx-100,ly-200,i-hello,fs-100,co-red,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,lx-100,ly-200,i-hello,fs-100,co-red,l-end" alt="Text aligned at 100px on 'X-axis' and 200px on 'Y-axis'" /%}

{% /linetab %}
{% linetab title="lx-bw_mul_0.5,ly-bh_mul_0.3" %}

Use the URL below to align the text 50 percent from the top-left corner in the `x` direction and 30 percent in the `y` direction relative to the base video.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,lx-bw_mul_0.5,ly-bh_mul_0.3,i-hello,fs-100,co-red,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,lx-bw_mul_0.5,ly-bh_mul_0.3,i-hello,fs-100,co-red,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,lx-bw_mul_0.5,ly-bh_mul_0.3,i-hello,fs-100,co-red,l-end" alt="Text aligned at 50% on 'X-axis' and 30% from 'Y-axis'" /%}

{% /linetab %}

{% linetab title="lx-N0,ly-100" %}

To align the text at `100px` from the top in the `y` direction and towards the right, use the below URL.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,lx-N0,ly-100,i-hello,fs-100,co-red,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,lx-N0,ly-100,i-hello,fs-100,co-red,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,lx-N0,ly-100,i-hello,fs-100,co-red,l-end" alt="Text aligned at 100px on 'Y-axis' and towards right" /%}

{% /linetab %}
{% linetab title="lfo-left" %}

To align the text to the left of the video use `lfo-left`.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,lfo-left,i-hello,fs-100,co-red,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,lfo-left,i-hello,fs-100,co-red,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,lfo-left,i-hello,fs-100,co-red,l-end" alt="Left align text" /%}

{% /linetab %}
{% /linetabs %}

We can use `lso`, `leo`, and `ldu` to control the time at which the overlay should start, end, and the duration of the overlay. Additionally, you can use arithmetic expressions like `bdu_div_2` and `bdu_mul_0.2` as a value for these parameters to better control the timing of the overlay. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).

{% callout style="info" %}
Inside `text` layer only `bdu` is a valid expression variable.
{% /callout %}

{% linetabs %}
{% linetab title="lso-3,leo-8" %}

To add the text at 3 seconds and remove it at 8 seconds use `lso-3,leo-8`.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,lso-3,leo-8,i-hello,fs-100,co-red,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,lso-3,leo-8,i-hello,fs-100,co-red,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,lso-3,leo-8,i-hello,fs-100,co-red,l-end" alt="Add text at 3 seconds and remove at 8 seconds" /%}

{% /linetab %}
{% linetab title="lso-bdu_mul_0.1,leo-bdu_mul_0.8" %}

Use `lso-bdu_mul_0.1,leo-bdu_mul_0.8` to add the text at 10 percent of the duration from the start and remove it after 80 percent of the total duration.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,lso-bdu_mul_0.1,leo-bdu_mul_0.8,i-hello,fs-100,co-red,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,lso-bdu_mul_0.1,leo-bdu_mul_0.8,i-hello,fs-100,co-red,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,lso-bdu_mul_0.1,leo-bdu_mul_0.8,i-hello,fs-100,co-red,l-end" alt="Add text layer at 10% and remove at 80% duration" /%}

{% /linetab %}
{% linetab title="lso-bdu_mul_0.1,ldu-bdu_mul_0.4" %}

Use `lso-bdu_mul_0.1,ldu-bdu_mul_0.4` to add the text at 10 percent of the duration from the start and keep it for the next 40 percent.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,lso-bdu_mul_0.1,ldu-bdu_mul_0.4,i-hello,fs-100,co-red,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,lso-bdu_mul_0.1,ldu-bdu_mul_0.4,i-hello,fs-100,co-red,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,lso-bdu_mul_0.1,ldu-bdu_mul_0.4,i-hello,fs-100,co-red,l-end" alt="Add text layer at 10% and remove at 50% duration" /%}

{% /linetab %}
{% /linetabs %}

## Apply transformations on text overlay

You can control the width, font size, font family, color, inner alignment, padding, transparency level, typography, background color, corner radius, rotation, line height of the text overlay using [these supported transformations](#list-of-supported-text-transformations-in-text-layers) parameters.

For example, let's add a white background with padding and a bigger font size.

You can add padding to the text overlay using the pa parameter. The padding can be controlled individually for each side using the CSS shorthand notation. Refer to text in image overlay for [more examples](/add-overlays-on-images#apply-transformation-on-text-overlay).

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,i-hello,fs-100,co-red,bg-FFFFFF,pa-20,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,i-hello,fs-100,co-red,bg-FFFFFF,pa-20,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-text,i-hello,fs-100,co-red,bg-FFFFFF,pa-20,l-end" alt="Add text with background and padding" /%}

### List of supported text transformations in text layers

| Parameter                          | Description                  |
|------------------------------------|------------------------------|
| w                                  | Width of the whole text layer. It can also accept arithmetic expressions such as `bw_div_2`, or `bw_mul_0.8`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations). |
| fs                                 | Font size. It can also accept arithmetic expressions such as `bh_div_20`, or `bh_mul_0.05`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).  |
| ff                                 | It is used to specify the font of the overlaid text on the image. You can choose [any font from this list](/add-overlays-on-images#supported-text-font-list) or use a [custom font](add-overlays-on-images#change-font-family-in-text-overlay).                          |
| co                                 | It is used to specify the color and transparency of the overlaid text on the image. It accepts RGB Hex Codes (e.g. `FF0000`), or RGBA Codes (e.g. `FFAABB50`), or color names (e.g. `red`). If you specify an 8-character background, the last two characters must be a number between `00` and `99`, which indicate the opacity level of the background. `00` represents an opacity level of `0.00`, `01` represents an opacity level of `0.01`, and so on. |
| ia                                 | Inner alignment. Accepts `left`, `right` and `center`. The default value is `center`. |
| pa                                 | Padding. It can also accept arithmetic expressions such as `bw_mul_0.05`, or `bw_mod_5`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations). |
| al                                 | Alpha |
| tg        | Typography. Supports bold `b`, italics `i`, `strikethrough`, or a combination of these. eg. `b_i`, `b_i_strikethrough` |
| bg                    | It is used to specify the background color in RGB Hex Code (e.g. FF0000) or an RGBA Code (e.g. FFAABB50) that must be used for the video. If you specify an 8-character background, the last two characters must be a number between 00 and 99, which is used to indicate the opacity level of the background. `00` represents an opacity level of `0.00`, `01`  represents opacity level `0.01`, and so on. |
| r                                | It is used to control the radius of the corner. To get a circle or oval shape, set the value to `max`. |
 rt | It is used to specify the degree by which the overlay text must be rotated. It accepts any number e.g. `45`, or `180` for a clockwise rotation, or any number preceded with `N` e.g. `N45`, or `N180`  for counter-clockwise rotation.
| lh         | It is used to specify the line height(spacing) of the text. It will come into effect only if the text wraps over multiple lines. Accepts integer values representing line height in points. It can also accept arithmetic expressions such as `bw_mul_0.2`, or `bh_div_20`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations). |

## Add video over video

You can add a video or a GIF over a base video using the video layer `l-video`.

### Syntax for adding video over video

```markup
         URL endpoint         Base video                   Video layer
┌──────────────────────────┐┌────────────┐      ┌──────────────────────────────┐
https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,i-sample-video.mp4,l-end
```

For example, let's overlay the video over itself. We are also [resizing the video](#apply-transformations-on-video-overlay) to 400px width so that the overlay effect is visible.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,i-sample-video.mp4,w-400,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,i-sample-video.mp4,w-400,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,i-sample-video.mp4,w-400,l-end" alt="Add video over video" /%}

{% callout style="info" %}
**Notes**
1. All supported [video formats](/transformations#supported-formats) & GIF can be used a input (`i` or `ie`) for video layer. Animated-WebP and animated-PNG (`apng`) are not supported in ImageKit's video API.
2. For a nested path, replace `/` with `@@`.
{% /callout %}

## Control time & position of video overlay

You can control video layer position using the `lx`, `ly` and `lfo` parameters. Learn more about [positional parameters](/transformations#position-of-layer) in layers. You can also use [arithmetic expressions](/arithmetic-expressions-in-transformations) in `lx` and `ly` to better control the position of the overlay.

{% linetabs %}
{% linetab title="lx-100,ly-200" %}

Use the URL below to align the video at `100px` from the top-left corner in the `x` direction and `200px` in the `y` direction relative to the base video.
[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,i-sample-video.mp4,w-400,lx-100,ly-200,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,i-sample-video.mp4,w-400,lx-100,ly-200,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,i-sample-video.mp4,w-400,lx-100,ly-200,l-end" alt="Video aligned at 100px on 'X-axis' and 200px on 'Y-axis'" /%}

{% /linetab %}
{% linetab title="lx-bw_mul_0.5,ly-bh_mul_0.3" %}

Use the URL below to align the video 50 percent from the top-left corner in the `x` direction and 30 percent in the `y` direction relative to the base video.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,i-sample-video.mp4,w-400,lx-bw_mul_0.5,ly-bh_mul_0.3,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,i-sample-video.mp4,w-400,lx-bw_mul_0.5,ly-bh_mul_0.3,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,i-sample-video.mp4,w-400,lx-bw_mul_0.5,ly-bh_mul_0.3,l-end" alt="Video aligned at 50% on 'X-axis' and 30% on 'Y-axis'" /%}

{% /linetab %}

{% linetab title="lx-bw_sub_cw,ly-100" %}

To align the video at `100px` from the top in the `y` direction and towards the right, use the below URL.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,i-sample-video.mp4,w-400:lx-bw_sub_cw,ly-100,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,i-sample-video.mp4,w-400:lx-bw_sub_cw,ly-100,l-end)

Note how `cw` has been used along with chain transformation to denote the latest modified width, i.e., `400px`.

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,i-sample-video.mp4,w-400:lx-bw_sub_cw,ly-100,l-end" alt="Video aligned at 100px on 'Y-axis' and towards right" /%}


{% /linetab %}
{% linetab title="lfo-left" %}

To align the video to the left of the base video use `lfo-left`.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,i-sample-video.mp4,w-400,lfo-left,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,i-sample-video.mp4,w-400,lfo-left,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,i-sample-video.mp4,w-400,lfo-left,l-end" alt="Left align video layer" /%}

{% /linetab %}
{% /linetabs %}


You can also use `lso`, `leo`, and `ldu` to control at what time the overlay should start, end, and the duration of the overlay. Additionally, you can use arithmetic expressions like `bdu_div_2` and `idu_mul_0.2` as a value for these parameters to better control the timing of the overlay. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).

{% linetabs %}
{% linetab title="lso-3,leo-8" %}

To overlay the video at 3 seconds and remove it at 8 seconds use `lso-3,leo-8`.


[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,lso-3,leo-8,i-sample-video.mp4,w-400,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,lso-3,leo-8,i-sample-video.mp4,w-400,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,lso-3,leo-8,i-sample-video.mp4,w-400,l-end" alt="Overlay video at 3 seconds and remove at 8 seconds" /%}

{% /linetab %}
{% linetab title="lso-bdu_mul_0.1,leo-bdu_mul_0.8" %}

Use `lso-bdu_mul_0.1,leo-bdu_mul_0.8` to add the logo at 10 percent of the duration from the start and remove it after 80 percent of the total duration.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,lso-bdu_mul_0.1,leo-bdu_mul_0.8,i-sample-video.mp4,w-400,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,lso-bdu_mul_0.1,leo-bdu_mul_0.8,i-sample-video.mp4,w-400,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,lso-bdu_mul_0.1,leo-bdu_mul_0.8,i-sample-video.mp4,w-400,l-end" alt="Overlay video layer at 10% and remove at 80% duration" /%}

{% /linetab %}
{% linetab title="lso-bdu_mul_0.1,ldu-bdu_mul_0.4" %}

Use `lso-bdu_mul_0.1,ldu-bdu_mul_0.4` to add the logo at 10 percent of the duration from the start and keep it for the next 40 percent.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,lso-bdu_mul_0.1,ldu-bdu_mul_0.4,i-sample-video.mp4,w-400,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,lso-bdu_mul_0.1,ldu-bdu_mul_0.4,i-sample-video.mp4,w-400,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,lso-bdu_mul_0.1,ldu-bdu_mul_0.4,i-sample-video.mp4,w-400,l-end" alt="Overlay video layer at 10% and remove at 50% duration" /%}

{% /linetab %}
{% /linetabs %}

## Apply transformations on video overlay

You can transform the layered video using any [supported video transformation parameter](/video-transformation) in ImageKit except `sr`.

Let's resize the video to 400px width by adding `w-400` inside the video layer.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,i-sample-video.mp4,w-400,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,i-sample-video.mp4,w-400,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-video,i-sample-video.mp4,w-400,l-end" alt="Resize video layer" /%}

## Add solid color blocks over video

You can add solid color blocks over a base video using the following example.

### Syntax for adding solid color blocks over video

```markup
https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,bg-red,l-end
```

Let's add a solid red color block over a base video.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,bg-red,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,bg-red,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,bg-red,l-end" alt="Add solid color block over video" /%}

## Control time & position of solid color block overlay

You can control the position of the solid color block overlay using the `lx`, `ly` and `lfo` parameters. Learn more about [positional parameters](/transformations#position-of-layer) in layers. You can also use [arithmetic expressions](/arithmetic-expressions-in-transformations) in `lx` and `ly` to better control the position of the overlay.

{% linetabs %}
{% linetab title="lx-100,ly-200" %}

Use the URL below to align the solid color block at `100px` from the top-left corner in the `x` direction and `200px` in the`y` direction relative to the base video.
[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,bg-red,lx-100,ly-200,w-500,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,bg-red,lx-100,ly-200,w-500,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,bg-red,lx-100,ly-200,w-500,l-end" alt="solid color block aligned at 100px on 'X-axis' and 200px on 'Y-axis'" /%}

{% /linetab %}
{% linetab title="lx-bw_mul_0.5,ly-bh_mul_0.3" %}

Use the URL below to align the solid color block at 50 percent from the top-left corner in the `x` direction and 30 percent in the `y` direction relative to the base video.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,bg-red,lx-bw_mul_0.5,ly-bh_mul_0.3,w-500,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,bg-red,lx-bw_mul_0.5,ly-bh_mul_0.3,w-500,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,bg-red,lx-bw_mul_0.5,ly-bh_mul_0.3,w-500,l-end" alt="Solid color block aligned at 50% on 'X-axis' and 30% on 'Y-axis'" /%}

{% /linetab %}

{% linetab title="lx-N0,ly-100" %}

To align the solid color block at `100px` from the top in the `y` direction and towards the right, use the below URL.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,bg-red,lx-N0,ly-100,w-500,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,bg-red,lx-N0,ly-100,w-500,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,bg-red,lx-N0,ly-100,w-500,l-end" alt="Solid color block aligned at 100px on 'Y-axis' and towards right" /%}

{% /linetab %}
{% linetab title="lfo-left" %}

To align the solid color block to the left of the video use `lfo-left`.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,bg-red,lfo-left,w-500,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,bg-red,lfo-left,w-500,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,bg-red,lfo-left,w-500,l-end" alt="Left align solid block" /%}

{% /linetab %}
{% /linetabs %}

You can also use `lso`, `leo`, and `ldu` to control at what time the overlay should start, end, and the duration of the overlay. Additionally, you can use arithmetic expressions like `bdu_div_2` and `bdu_mul_0.2` as a value for these parameters to better control the timing of the overlay. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).

{% callout style="info" %}
Inside `ik_canvas` layer only `bdu` is a valid expression variable.
{% /callout %}

{% linetabs %}
{% linetab title="lso-3,leo-8" %}

To add the solid color block at 3 seconds and remove it at 8 seconds use `lso-3,leo-8`.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lso-3,leo-8,i-ik_canvas,bg-red,lfo-left,w-500,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lso-3,leo-8,i-ik_canvas,bg-red,lfo-left,w-500,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lso-3,leo-8,i-ik_canvas,bg-red,lfo-left,w-500,l-end" alt="Add solid block at 3 seconds and remove at 8 seconds" /%}

{% /linetab %}
{% linetab title="lso-bdu_mul_0.1,leo-bdu_mul_0.8" %}

Use `lso-bdu_mul_0.1,leo-bdu_mul_0.8` to add the solid color block at 10 percent of the duration from the start and remove it after 80 percent of the total duration.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lso-bdu_mul_0.1,leo-bdu_mul_0.8,i-ik_canvas,bg-red,w-500,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lso-bdu_mul_0.1,leo-bdu_mul_0.8,i-ik_canvas,bg-red,w-500,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lso-bdu_mul_0.1,leo-bdu_mul_0.8,i-ik_canvas,bg-red,w-500,l-end" alt="Add solid block layer at 10% and remove at 80% duration" /%}

{% /linetab %}
{% linetab title="lso-bdu_mul_0.1,ldu-bdu_mul_0.4" %}

Use `lso-bdu_mul_0.1,ldu-bdu_mul_0.4` to add the solid color block at 10 percent of the duration from the start and keep it for the next 40 percent.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lso-bdu_mul_0.1,ldu-bdu_mul_0.4,i-ik_canvas,bg-red,w-500,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lso-bdu_mul_0.1,ldu-bdu_mul_0.4,i-ik_canvas,bg-red,w-500,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,lso-bdu_mul_0.1,ldu-bdu_mul_0.4,i-ik_canvas,bg-red,w-500,l-end" alt="Add solid block layer at 10% and remove at 50% duration" /%}

{% /linetab %}
{% /linetabs %}

## Apply transformations on solid color block overlay

The following transformation parameters are supported on the solid color block overlay inside a layer.

| Parameter                                                                                | Description                        |
|------------------------------------------------------------------------------------------|------------------------------------|
| w                                                                                        | Width of solid color block. It can also accept arithmetic expressions such as `bw_div_2`, or `bw_mul_0.8`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations). |
| h                                                                                        | Height of solid color block. It can also accept arithmetic expressions such as `bh_div_2`, or `bh_mul_0.8`. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).  |
| [bg](/effects-and-enhancements#background---bg) | It is used to specify the color of the block in RGB Hex Code (e.g. `FF0000`), or an RGBA Code (e.g. `FFAABB50`), or a color name (e.g. `red`). If you specify an 8-character background, the last two characters must be a number between `00` and `99`, which indicates the opacity level of the background. `00` represents an opacity level of `0.00`, `01` represents an opacity level of `0.01`, and so on. |
| al                                                                                       | It is used to specify the transparency level of the overlaid solid color layer. Supports integers from `1` to `9`. |
| [r](/effects-and-enhancements#radius---r)             | It is used to control the radius of the corner. To get a circle or oval shape, set the value to `max`. |

{% callout style="info" %}
If both `bg` and `al` are set in a single transformation and `bg` has an alpha component, then that value is used to set solid color background transparency. Otherwise, `al` value is used. If `bg` is set to a standard color name (e.g. `blue`), then the `al` value is ignored.
{% /callout %}

## Nest text and image layers inside canvas

A canvas layer (`i-ik_canvas`) can contain nested text and image child layers. This lets you build self-contained compositions — for example, a colored banner with a heading or a card with a product image and caption — all in a single overlay positioned on the base video.

Child layers are placed relative to the canvas, not the base video. Use `lfo` (relative focus) or `lx`/`ly`/`lxc`/`lyc`/`lap` (absolute coordinates) to position children within the canvas.

```markup
                                    Canvas layer with nested children
┌──────────────────────────────────────────────────────────────────────────────────────────┐
l-image,i-ik_canvas,w-600,h-200,bg-FF0000,r-20,l-text,i-Hello_World,fs-36,lfo-center,l-end,l-end
                                             └──────────────────┬─────────────────────┘
                                                  Nested text child inside the canvas
```

### Nested text layer in canvas

{% linetabs %}
{% linetab title="Text centered" %}
[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,w-500,h-120,bg-00FFFF,l-text,i-Centered_Text,fs-24,lfo-center,l-end,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,w-500,h-120,bg-00FFFF,l-text,i-Centered_Text,fs-24,lfo-center,l-end,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,w-500,h-120,bg-00FFFF,l-text,i-Centered_Text,fs-24,lfo-center,l-end,l-end" alt="Canvas with centered text" /%}
{% /linetab %}

{% linetab title="Text with lx, ly" %}
[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,w-500,h-200,bg-FFFF0090,l-text,i-Anchored,fs-32,co-000000,tg-b,lx-100,ly-50,l-end,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,w-500,h-200,bg-FFFF0090,l-text,i-Anchored,fs-32,co-000000,tg-b,lx-100,ly-50,l-end,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,w-500,h-200,bg-FFFF0090,l-text,i-Anchored,fs-32,co-000000,tg-b,lx-100,ly-50,l-end,l-end" alt="Canvas with text positioned using lx ly" /%}
{% /linetab %}

{% linetab title="Multiple text layers" %}
[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,w-500,h-120,bg-FF0000,l-text,i-Top,lfo-top,l-end:l-text,i-Bottom,lfo-bottom,l-end,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,w-500,h-120,bg-FF0000,l-text,i-Top,lfo-top,l-end:l-text,i-Bottom,lfo-bottom,l-end,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,w-500,h-120,bg-FF0000,l-text,i-Top,lfo-top,l-end:l-text,i-Bottom,lfo-bottom,l-end,l-end" alt="Canvas with multiple text layers" /%}
{% /linetab %}
{% /linetabs %}

### Nested image layer in canvas

{% linetabs %}
{% linetab title="Image centered" %}
[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,w-500,h-400,bg-FF0000,l-image,i-example_food_3.jpg,w-200,h-150,lfo-center,l-end,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,w-500,h-400,bg-FF0000,l-image,i-example_food_3.jpg,w-200,h-150,lfo-center,l-end,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,w-500,h-400,bg-FF0000,l-image,i-example_food_3.jpg,w-200,h-150,lfo-center,l-end,l-end" alt="Canvas with centered image" /%}
{% /linetab %}

{% linetab title="Image with lx, ly" %}
[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,w-500,h-400,bg-FFFF00,l-image,i-example_food_3.jpg,w-200,h-150,lx-100,ly-80,l-end,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,w-500,h-400,bg-FFFF00,l-image,i-example_food_3.jpg,w-200,h-150,lx-100,ly-80,l-end,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,w-500,h-400,bg-FFFF00,l-image,i-example_food_3.jpg,w-200,h-150,lx-100,ly-80,l-end,l-end" alt="Canvas with image positioned using lx ly" /%}
{% /linetab %}
{% /linetabs %}

### Mixed text and image layers in canvas

{% linetabs %}
{% linetab title="Image + text caption" %}
[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,w-500,h-400,bg-0000FF80,r-20,l-image,i-example_food_3.jpg,w-200,h-150,lfo-center,l-end:l-text,i-Caption_Text,fs-28,co-FFFF00,pa-8,lfo-bottom,l-end,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,w-500,h-400,bg-0000FF80,r-20,l-image,i-example_food_3.jpg,w-200,h-150,lfo-center,l-end:l-text,i-Caption_Text,fs-28,co-FFFF00,pa-8,lfo-bottom,l-end,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,w-500,h-400,bg-0000FF80,r-20,l-image,i-example_food_3.jpg,w-200,h-150,lfo-center,l-end:l-text,i-Caption_Text,fs-28,co-FFFF00,pa-8,lfo-bottom,l-end,l-end" alt="Canvas with image and text caption" /%}
{% /linetab %}

{% linetab title="Text header + image" %}
[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,w-500,h-400,bg-333333,l-text,i-Header,fs-28,co-FFFFFF,lfo-top,l-end:l-image,i-example_food_3.jpg,w-200,h-150,lfo-bottom,l-end,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,w-500,h-400,bg-333333,l-text,i-Header,fs-28,co-FFFFFF,lfo-top,l-end:l-image,i-example_food_3.jpg,w-200,h-150,lfo-bottom,l-end,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,w-500,h-400,bg-333333,l-text,i-Header,fs-28,co-FFFFFF,lfo-top,l-end:l-image,i-example_food_3.jpg,w-200,h-150,lfo-bottom,l-end,l-end" alt="Canvas with text header and image" /%}
{% /linetab %}
{% /linetabs %}

### Canvas with rounded corners, or transparency

{% linetabs %}
{% linetab title="Rounded canvas with text" %}
[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,w-600,h-200,bg-FF0000,r-20,l-text,i-Hello_World,fs-36,ff-Lora,co-FFFFFF,tg-b,ia-left,pa-10,lfo-center,l-end,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,w-600,h-200,bg-FF0000,r-20,l-text,i-Hello_World,fs-36,ff-Lora,co-FFFFFF,tg-b,ia-left,pa-10,lfo-center,l-end,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,w-600,h-200,bg-FF0000,r-20,l-text,i-Hello_World,fs-36,ff-Lora,co-FFFFFF,tg-b,ia-left,pa-10,lfo-center,l-end,l-end" alt="Rounded canvas with styled text" /%}
{% /linetab %}

{% linetab title="Semi-transparent canvas with text" %}
[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,w-500,h-120,bg-FF000080,l-text,i-Transparent,co-FFFFFF,lfo-center,l-end,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,w-500,h-120,bg-FF000080,l-text,i-Transparent,co-FFFFFF,lfo-center,l-end,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,w-500,h-120,bg-FF000080,l-text,i-Transparent,co-FFFFFF,lfo-center,l-end,l-end" alt="Semi-transparent canvas with text" /%}
{% /linetab %}

{% linetab title="Circular canvas with text" %}
[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,w-400,h-400,bg-FF00FF,r-max,l-text,i-Circle,co-FFFFFF,lfo-center,l-end,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,w-400,h-400,bg-FF00FF,r-max,l-text,i-Circle,co-FFFFFF,lfo-center,l-end,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-ik_canvas,w-400,h-400,bg-FF00FF,r-max,l-text,i-Circle,co-FFFFFF,lfo-center,l-end,l-end" alt="Circular canvas with text" /%}
{% /linetab %}
{% /linetabs %}

## Add subtitles over a video

You can overlay subtitles on a base video using the `l-subtitles` layer in ImageKit's VideoAPI.

### Syntax for adding subtitles over video

```markup
         URL endpoint         Base video                 Subtitles layer
┌──────────────────────────┐┌───────────────┐   ┌──────────────────────────────┐
https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,l-end
```

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,l-end" alt="Add subtitles over video" /%}

## Supported subtitle file types

* SRT (SubRip Subtitle)
* ASS (Advanced SubStation Alpha)
* WebVTT (Web Video Text Tracks)

{% callout style="info" %}
**Limitations**

For complex styling within subtitle files, we recommend using ASS subtitles. ImageKit fully supports all [Advanced SubStation Alpha](http://www.tcax.org/docs/ass-specs.htm) styling options.

While SRT and WebVTT formats are supported, their styling capabilities are limited. Advanced CSS styles in WebVTT may cause issues and not produce the intended output. For styling SRT and WebVTT subtitles, use the styling options available in `l-subtitles`.
{% /callout %}

## Styling controls for subtitles layer

| Property | Description                          |
| -------- | ------------------------------------ |
| bg       | Specifies the subtitle background color using a standard color name, an RGB color code (e.g., FF0000), or an RGBA color code (e.g., FFAABB50).       |
| fs       | Sets the font size of subtitle text.                  |
| ff       | Sets the font family of subtitle text. You can choose [any font from this list](/add-overlays-on-images#supported-text-font-list).                                                                                                             |
| co       | Sets the font color of the subtitle text using a standard color name, an RGB color code (e.g., FF0000), or an RGBA color code (e.g., FFAABB50).                                                                                        |
| tg       | Sets the typography style of the subtitle text. Supports values are `b` for bold, `i` for italics, and `b_i` for bold with italics. |
| fol      | Sets the font outline of the subtitle text. Requires the outline width (an integer) and the outline color (as an RGB color code, RGBA color code, or standard web color name) separated by an underscore. Example: `fol-2_blue` (outline width of 2px and outline color blue), `fol-2_A1CCDD` (outline width of 2px and outline color `#A1CCDD`) and `fol-2_A1CCDD50` (outline width of 2px and outline color `#A1CCDD` at 50% opacity). |
| fsh      | Sets the font shadow for the subtitle text. Requires the shadow color (as an RGB color code, RGBA color code, or standard web color name) and shadow indent (an integer) separated by an underscore. Example: `fsh-blue_2` (shadow color blue, indent of 2px), `fsh-A1CCDD_3` (shadow color `#A1CCDD`, indent of 3px), `fsh-A1CCDD50_3` (shadow color `#A1CCDD` at 50% opacity, indent of 3px).   |

{% callout style="info" %}
**RGBA Color**

If you specify an 8-character RGBA color code, the last two characters must be a number between `00` and `99`, which indicates the opacity level. `00` represents an opacity level of `0.00`, `01` represents an opacity level of `0.01`, and so on.

Examples:
* `FFAABB00` - Color `FFAABB` with `0%` opacity (fully transparent).
* `FFAABB50` - Color `FFAABB` with `50%` opacity.
* `FFAABB99` - Color `FFAABB` with `99%` opacity (almost fully opaque).
{% /callout %}

### Examples

Add background behind subtitle text with `bg` parameter in subtitles layer:

{% linetabs %}
{% linetab title="bg-purple" %}

Add background with standard color name `purple`.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,bg-purple,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,bg-purple,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,bg-purple,l-end" alt="Add background with standard color name" /%}

{% /linetab %}
{% linetab title="bg-AABBAA" %}

Add background with RGB color value `AABBAA`.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,bg-AABBAA,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,bg-AABBAA,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,bg-AABBAA,l-end" alt="Add background with RGB color value" /%}

{% /linetab %}
{% linetab title="bg-AABBAA50" %}

Add background with reduced opacity using aplha component.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,bg-AABBAA50,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,bg-AABBAA50,l-end)

In `bg-AABBAA50`, RGB color is `AABBAA` and the alpha value is `50` (50% opacity)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,bg-AABBAA50,l-end" alt="Add background with reduced opacity using aplha component" /%}

{% /linetab %}
{% /linetabs %}

Customize basic subtitle font properties using the `fs` (font size), `ff` (font family), `co` (color) and `tg` (typography) parameters in subtitles layer:

{% linetabs %}
{% linetab title="font-size" %}

Set font size to 32

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,fs-32,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,fs-32,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,fs-32,l-end" alt="Set subtitle font size" /%}

{% /linetab %}
{% linetab title="font-family" %}

Set font family to `Lora` with `ff` parameter.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,ff-Lora,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,ff-Lora,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,ff-Lora,l-end" alt="Set subtitle font family" /%}

{% /linetab %}
{% linetab title="font-color" %}

Set font color to `orange` with `co` parameter.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,co-orange,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,co-orange,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,co-orange,l-end" alt="Set subtitle font color" /%}

{% /linetab %}
{% linetab title="typography" %}

Set font style to bold with `tg` parameter.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,tg-b,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,tg-b,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,tg-b,l-end" alt="Set subtitle font typography" /%}

{% /linetab %}
{% /linetabs %}

Apply font outline using `fol` parameter in subtitles layer:

{% linetabs %}
{% linetab title="fol-2_blue" %}

Apply font outline of 2px width and `blue` color to the subtitles.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,fol-2_blue,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,fol-2_blue,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,fol-2_blue,l-end" alt="Set font outline with color name" /%}

{% /linetab %}
{% linetab title="fol-4_0000FF65" %}

Apply a font outline with a 4px width and the color in RGBA format 0000FF65 to the subtitles.

In RGBA color `0000FF65`,  the RGB component is `0000FF` (the RGB color code for blue) and the alpha value `65` (65% opacity).

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,fol-4_0000FF65,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,fol-4_0000FF65,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,fol-4_0000FF65,l-end" alt="Set font outline with RGBA color" /%}

{% /linetab %}
{% /linetabs %}

Apply text shadow using `fsh` parameter in subtitles layer:

{% linetabs %}
{% linetab title="fsh-darkgray_3" %}

Apply a text shadow of color `darkgray` and 3px indent.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,fsh-darkgray_3,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,fsh-darkgray_3,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,fsh-darkgray_3,l-end" alt="Set font shadow with color name" /%}

{% /linetab %}
{% linetab title="fsh-A9A9A950_3" %}

Apply a text shadow of RGBA color `A9A9A950` and 3px indent.

In RGBA color `A9A9A950`,  the RGB component is `A9A9A9` (that is RGB color code for darkgray) and the alpha value `50` (50% opacity).

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,fsh-A9A9A950_3,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,fsh-A9A9A950_3,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,fsh-A9A9A950_3,l-end" alt="Set font shadow with RGBA color" /%}

{% /linetab %}
{% /linetabs %}

## Set subtitle alignment in subtitles layer

You can set subtitle alignment relative to the video frame using `lfo` parameter. Supported values are: `top_left`, `top`, `top_right`, `left`, `center`, `right`, `bottom_left`, `bottom`, `bottom_right`.

### Examples

{% linetabs %}
{% linetab title="lfo-center" %}

Align the subtitles to the center of the video.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,lfo-center,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,lfo-center,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,lfo-center,l-end" alt="Align subtitle to the center of the video" /%}

{% /linetab %}
{% linetab title="lfo-top_right" %}

Align the subtitles to the top-right of the video.

[https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,lfo-top_right,l-end](https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,lfo-top_right,l-end)

{% video src="https://ik.imagekit.io/demo/sample-video.mp4?tr=l-subtitles,i-english.srt,lfo-top_right,l-end" alt="Align subtitle to the top-right of the video" /%}

{% /linetab %}
{% /linetabs %}


---

# Source: /common-video-transformations

---
title: Common Video Transformations
description: Learn about common video transformations like rotation, border, background, and more.
---

## Background - (bg)

It is used to specify the background when using [crop-mode pad_resize](/video-resize-and-crop#crop-crop-modes-and-focus) or border-radius (r). The background can be any solid color or blurred frame of the video.

**Default value** -  By default, the background is black.

### Solid color background

* RGB Hex code: A 6-digit hex code (eg. `AAFF00`, `0f0fac`).
* RGBA Hex code: An 8-digit hex code. Last two characters must be a number between `00` and `99`, specifying the opacity level (eg. `AAFF0040`, `0f0fac75`),
* Color name: A standard color name in lowercase (eg. lightgreen, beige),

{% linetabs %}
{% linetab title="bg=red" %}
URL - [https://ik.imagekit.io/demo/tr:h-700,w-700,cm-pad_resize,bg-red/sample2.mp4](https://ik.imagekit.io/demo/tr:h-700,w-700,cm-pad_resize,bg-red/sample2.mp4)

{%video src="https://ik.imagekit.io/demo/tr:h-700,w-700,cm-pad_resize,bg-red/sample2.mp4" alt="cm-pad_resize,bg-red" /%}

{% /linetab %}

{% linetab title="bg=A94D34" %}
URL - [https://ik.imagekit.io/demo/tr:h-700,w-700,cm-pad_resize,bg-A94D34/sample2.mp4](https://ik.imagekit.io/demo/tr:h-700,w-700,cm-pad_resize,bg-A94D34/sample2.mp4)
    
{%video src="https://ik.imagekit.io/demo/tr:h-700,w-700,cm-pad_resize,bg-A94D34/sample2.mp4" alt="cm-pad_resize,bg-A94D34" /%}

{% /linetab %}
{% /linetabs %}

### Blurred background

Syntax: `blurred[_<BlurIntensity>][_<Brightness>]`

|      Parameter |                              Value |                                                                                Description | Default |
| -------------: | ---------------------------------: | -----------------------------------------------------------------------------------------: | ------: |
| Blur intensity | `auto` or an integer from 0 to 100 |                                                                  Set the intensity of blur |  'auto' |
|     Brightness |           Integer from N255 to 255 | Negative value to make background darker and positive value to make the background lighter |       0 |

Limitation: Blurred background can only be used with `cm-pad_resize`

Blur intensity `auto`: The intensity of blur is automatically adjusted based on the provided height (h) & width (w) in the transformation.

{% linetabs %}
{% linetab title="bg=blurred" %}
URL - [https://ik.imagekit.io/demo/tr:h-700,w-700,cm-pad_resize,bg-blurred/sample2.mp4](https://ik.imagekit.io/demo/tr:h-700,w-700,cm-pad_resize,bg-blurred/sample2.mp4)

{%video src="https://ik.imagekit.io/demo/tr:h-700,w-700,cm-pad_resize,bg-blurred/sample2.mp4" alt="cm-pad_resize,bg-blurred" /%}
{% /linetab %}

{% linetab title="bg=blurred_25_N55" %}
URL - [https://ik.imagekit.io/demo/tr:h-700,w-700,cm-pad_resize,bg-blurred_25_N55/sample2.mp4](https://ik.imagekit.io/demo/tr:h-700,w-700,cm-pad_resize,bg-blurred_25_N55/sample2.mp4)

Customize blur-intensity to '25' & brightness to 'N55' (Make background darker)

{%video src="https://ik.imagekit.io/demo/tr:h-700,w-700,cm-pad_resize,bg-blurred_25_N55/sample2.mp4" alt="cm-pad_resize,bg-blurred_25_N55" /%}

{% /linetab %}

{% linetab title="bg=blurred_auto_30" %}
URL - [https://ik.imagekit.io/demo/tr:h-700,w-700,cm-pad_resize,bg-blurred_auto_30/sample2.mp4](https://ik.imagekit.io/demo/tr:h-700,w-700,cm-pad_resize,bg-blurred_auto_30/sample2.mp4)

Automatic blur-intensity & customize brightness to '30' (Make background lighter)

{%video src="https://ik.imagekit.io/demo/tr:h-700,w-700,cm-pad_resize,bg-blurred_auto_30/sample2.mp4" alt="cm-pad_resize,bg-blurred_auto_30" /%}
{% /linetab %}
{% /linetabs %}

## Border - (b)

This adds a border to the video. It accepts two parameters - the width of the border and the color of the border.

Usage - `b-<border-width>_<hex code>`

The width is specified as a number which is equivalent to the border width in pixels. The color code is specified as a 6-character hex code RRGGBB.

You can also provide an arithmetic expression such as `ih_div_20_red`, or `cw_mul_0.05_FF00FF` as a value for this parameter. Doing so will first calculate the value of the width and then apply transformations using that value. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).

{% linetabs %}
{% linetab title="5px yellow border" %}
URL - [https://ik.imagekit.io/ikmedia/sample-video.mp4?tr=b-5_yellow](https://ik.imagekit.io/ikmedia/sample-video.mp4?tr=b-5_yellow)

{%video src="https://ik.imagekit.io/ikmedia/sample-video.mp4?tr=b-5_yellow" alt="b-5_yellow" /%}
{% /linetab %}

{% linetab title="15px red border" %}
URL - [https://ik.imagekit.io/ikmedia/sample-video.mp4?tr=b-15_red](https://ik.imagekit.io/ikmedia/sample-video.mp4?tr=b-15_red)

{%video src="https://ik.imagekit.io/ikmedia/sample-video.mp4?tr=b-15_red" alt="b-15_red" /%}
{% /linetab %}

{% linetab title="15px #5587d9" %}
URL - [https://ik.imagekit.io/ikmedia/sample-video.mp4?tr=b-15_5587d9](https://ik.imagekit.io/ikmedia/sample-video.mp4?tr=b-15_5587d9)

{%video src="https://ik.imagekit.io/ikmedia/sample-video.mp4?tr=b-15_5587d9" alt="b-15_5587d9" /%}
{% /linetab %}

{% /linetabs %}

## Radius - (r)

Get a video with a rounded corner. Control the radius of the corner using this parameter. To get a circle or oval shape, set the value to `max`.

Usage - `r-<value>`

**Possible values** - Any positive integer or `max`.

{% callout style="info" %}
You can also change the background color of the video from the default black color using the [background parameter](#background---bg).
{% /callout %}

{% linetabs %}
{% linetab title="r=20" %}
URL - [https://ik.imagekit.io/ikmedia/sample-video.mp4?tr=r-20](https://ik.imagekit.io/ikmedia/sample-video.mp4?tr=r-20)

{%video src="https://ik.imagekit.io/ikmedia/sample-video.mp4?tr=r-20" alt="r-20" /%}
{% /linetab %}

{% linetab title="r=50" %}
URL - [https://ik.imagekit.io/ikmedia/sample-video.mp4?tr=r-50](https://ik.imagekit.io/ikmedia/sample-video.mp4?tr=r-50)

{%video src="https://ik.imagekit.io/ikmedia/sample-video.mp4?tr=r-50" alt="r-50" /%}
{% /linetab %}

{% linetab title="r=max" %}
If the input asset has 1:1 aspect ratio, using `max` will result in a circle shape. However, if the input asset is rectangular, using `max` will result in an oval shape.

URL - [https://ik.imagekit.io/ikmedia/sample-video.mp4?tr=r-max](https://ik.imagekit.io/ikmedia/sample-video.mp4?tr=r-max)

{%video src="https://ik.imagekit.io/ikmedia/sample-video.mp4?tr=r-max" alt="r-max" /%}
{% /linetab %}

{%linetab title="Red color background" %}

URL - [https://ik.imagekit.io/ikmedia/sample-video.mp4?tr=r-max,bg-red](https://ik.imagekit.io/ikmedia/sample-video.mp4?tr=r-max,bg-red)

{%video src="https://ik.imagekit.io/ikmedia/sample-video.mp4?tr=r-max,bg-red" alt="r-max,bg-red" /%}
{% /linetab %}

{% /linetabs %}

## Rotate - (rt)

It is used to specify the degree by which the output video must be rotated.

**Possible values** - `0` , `90` , `180` , `270` and `360`.

{% linetabs %}
{% linetab title="rt=90" %}
URL - [https://ik.imagekit.io/ikmedia/sample-video.mp4?tr=w-200,rt-90](https://ik.imagekit.io/ikmedia/sample-video.mp4?tr=w-200,rt-90)

{%video src="https://ik.imagekit.io/ikmedia/sample-video.mp4?tr=w-200,rt-90" alt="rt-90" /%}
{% /linetab %}

{% linetab title="rt=180" %}
URL - [https://ik.imagekit.io/ikmedia/sample-video.mp4?tr=w-200,rt-180](https://ik.imagekit.io/ikmedia/sample-video.mp4?tr=w-200,rt-180)

{%video src="https://ik.imagekit.io/ikmedia/sample-video.mp4?tr=w-200,rt-180" alt="rt-180" /%}
{% /linetab %}
{% /linetabs %}


---

# Source: /audio-transformations

---
title: Audio Transformations
description: Learn about audio transformations like muting a video, extracting audio from a video, and more.
---

## Muting Audio

Use `ac-none` to remove the audio stream from a video. This will mute the video. You can still control the video codec using the [video codec - (vc)](/video-optimization#video-codec---vc) parameter.

URL - [https://ik.imagekit.io/demo/tr:ac-none/sample-video.mp4](https://ik.imagekit.io/demo/tr:ac-none/sample-video.mp4)

{%video src="https://ik.imagekit.io/demo/tr:ac-none/sample-video.mp4" muted=false alt="Mutted video" /%}

## Extracting Audio

Use `vc-none` to remove the video stream from a video. This will extract the audio from the video. You can control the audio codec using the [audio codec - (ac)](/video-optimization#audio-codec---ac) parameter.

URL - [https://ik.imagekit.io/demo/tr:vc-none/sample-video.mp4](https://ik.imagekit.io/demo/tr:vc-none/sample-video.mp4)

{%video src="https://ik.imagekit.io/demo/tr:vc-none/sample-video.mp4" muted=false alt="Extracted audio" /%}


---

# Source: /create-video-thumbnails

---
title: Create Video Thumbnails
description: Learn how to create video thumbnails using ImageKit.io.
---

To get the first frame from the video `ik-thumbnail.jpg` after the video resource URL.

```markup
https://ik.imagekit.io/demo/sample-video.mp4/ik-thumbnail.jpg
```

## Basic example

[https://ik.imagekit.io/demo/img/sample-video.mp4/ik-thumbnail.jpg](https://ik.imagekit.io/demo/img/sample-video.mp4/ik-thumbnail.jpg)

![Create thumbnail from video](https://ik.imagekit.io/demo/img/sample-video.mp4/ik-thumbnail.jpg)

## Get thumbnail from a specific time point

To get the snapshot from a specific time point, use the [so parameter](/trim-videos#start-offset---so).

[https://ik.imagekit.io/demo/img/60cd.mp4/ik-thumbnail.jpg?tr=so-5](https://ik.imagekit.io/demo/img/60cd.mp4/ik-thumbnail.jpg?tr=so-5)

![Thumbnail from specific time point](https://ik.imagekit.io/demo/img/60cd.mp4/ik-thumbnail.jpg?tr=so-5)

## Transformations on video thumbnails

You can transform the output image using following transformation parameters. You can also add [layers](/transformations#overlay-using-layers) to add text and image overlay on top of the video thumbnail.

For example, to resize the thumbnail to 300px width, use the `w` parameter.

[https://ik.imagekit.io/demo/img/sample-video.mp4/ik-thumbnail.jpg?tr=w-300](https://ik.imagekit.io/demo/img/sample-video.mp4/ik-thumbnail.jpg?tr=w-300)

![Resize video thumbnail](https://ik.imagekit.io/demo/img/sample-video.mp4/ik-thumbnail.jpg?tr=w-300)


| Parameter   | Description |
| ----------- | ----------- |
| [w](/image-resize-and-crop#width---w)                                 | Specify the width. |
| [h](/image-resize-and-crop#height---h)                                | Specify the height. |
| [ar](/image-resize-and-crop#aspect-ratio---ar)                        | Aspect ratio of output, when either width or height is specified. |
| [c](/image-resize-and-crop#crop-crop-modes--focus)               | Cropping method. Accepts `force`, `at_max`, and `at_least`. |
| [cm](/image-resize-and-crop#crop-crop-modes--focus)              | Crop mode. Supports `extract` and `pad_resize`. |
| [fo](/image-resize-and-crop#focus---fo)                               | Relative focus area used during cropping. Accepts `center`, `top`, `left`, `bottom`, `right`, `top_left`, `top_right`, `bottom_left` and `bottom_right`. |
| [b](/effects-and-enhancements#border---b)                                | This adds a border to the image. It accepts two parameters - the width of the border and the color of the border in format `b-<border-width>-<hex code>` |
| [bg](/effects-and-enhancements#background---bg)                    | It is used to specify the background that can be used along with some cropping strategies while resizing or applying border-radius (`r`). You can choose either a solid color (using standard-browser-colors, RGB hex code, or RGBA hex code to specify color) or a blurred version of the image (using the syntax `blurred[_<BlurIntensity>][_<Brightness>]`). Example: `bg-red`, `bg-AAFF00`, `bg-AAFF0010`, `bg-blurred`, `bg-blurred_25_N15`. |
| [r](/effects-and-enhancements#radius---r)                                | It is used to control the radius of the corner. To get a circle or oval shape, set the value to `max`. (Background color can be specified with `bg` parameter) |
| [so](/trim-videos#start-offset---so)         | Start offset of the video in seconds to pick thumbnail from a specific time point. |


---

# Source: /trim-videos

---
title: Trim Videos
description: Learn how to trim videos using ImageKit.io.
---

You can trim a video using using `so`, `eo` and `du` options to specify start offset, end offset or duration.

You can also provide an arithmetic expressions like `idu_div_2`, `bdu_mul_0.2`, or `bdu` as a value for these parameter. Doing so will first calculate the value of the expression and then apply transformations using that value. Learn more about arithmetic expressions [here](/arithmetic-expressions-in-transformations).

## Start offset - (so)

Specify start offset in seconds. The video before the start offset is removed from the output.

Usage - `so-<value>`

**Possible values** - Specify the time in seconds as a positive number up to 2 decimal places, e.g.,  20 or 10.55, or an arithmetic expression like `idu_div_2`. It must be less than the duration of the input video.

{% linetabs %}
{% linetab title="Original (70 seconds)" %}
[https://ik.imagekit.io/demo/img/60cd.mp4](https://ik.imagekit.io/demo/img/60cd.mp4).

{%video src="https://ik.imagekit.io/demo/img/60cd.mp4" alt="Original video" /%}
{% /linetab %}
{% linetab title="so-5" %}
[https://ik.imagekit.io/demo/img/60cd.mp4?tr=so-5](https://ik.imagekit.io/demo/img/60cd.mp4?tr=so-5). This will return a video starting from 5th second till the end. The preview below is showing as if video starts at 4th second but that is just one frame, as soon as the video starts playing, it will start from 5th second.

{%video src="https://ik.imagekit.io/demo/img/60cd.mp4?tr=so-5" alt="Starting 5th second" /%}
{% /linetab %}

{% linetab title="so-idu_div_2"%}
[https://ik.imagekit.io/demo/img/60cd.mp4?tr=so-idu_div_2](https://ik.imagekit.io/demo/img/60cd.mp4?tr=so-idu_div_2). This will return a video starting from the mid-duration of the original video.

{%video src="https://ik.imagekit.io/demo/img/60cd.mp4?tr=so-idu_div_2" alt="Starting at mid" /%}
{% /linetab %}

{% linetab title="Inside layer" %}
You can also use expressions in the `so` parameter inside a layer. To trim the layer video by 80 percent of its original duration, i.e., 56 seconds from starting, you can use the following URL.
URL - [https://ik.imagekit.io/demo/img/sample-video.mp4?tr=l-video,i-img@@60cd.mp4,w-600,so-idu_mul_0.8,l-end](https://ik.imagekit.io/demo/img/sample-video.mp4?tr=l-video,i-img@@60cd.mp4,w-600,so-idu_mul_0.8,l-end)

{%video src="https://ik.imagekit.io/demo/img/sample-video.mp4?tr=l-video,i-img@@60cd.mp4,w-600,so-idu_mul_0.8,l-end" alt="Layer video is trimmed" /%}

{% /linetab %}
{% /linetabs %}

## End offset - (eo)

Specify end offset in seconds. The video after the end offset is removed from the output.

Usage - `eo-<value>`

**Possible values** - Specify the time in seconds as a positive number up to 2 decimal places, e.g.,  20 or 10.55, or an arithmetic expression like `idu_div_2`. It must be less than the duration of the input video.

{% linetabs %}
{% linetab title="Original (70 seconds)" %}
[https://ik.imagekit.io/demo/img/60cd.mp4](https://ik.imagekit.io/demo/img/60cd.mp4).

{%video src="https://ik.imagekit.io/demo/img/60cd.mp4" alt="Original video" /%}
{% /linetab %}

{% linetab title="eo-5" %}
[https://ik.imagekit.io/demo/img/60cd.mp4?tr=eo-5](https://ik.imagekit.io/demo/img/60cd.mp4?tr=eo-5). This will return a video starting from the beginning till 5th second.

{%video src="https://ik.imagekit.io/demo/img/60cd.mp4?tr=eo-5" alt="Till 5th second" /%}
{% /linetab %}

{% linetab title="eo-idu_sub_20"%}
To trim the video from the end by 20 seconds, you can use the following URL. [https://ik.imagekit.io/demo/img/60cd.mp4?tr=eo-idu_sub_20](https://ik.imagekit.io/demo/img/60cd.mp4?tr=eo-idu_sub_20). 

{%video src="https://ik.imagekit.io/demo/img/60cd.mp4?tr=eo-idu_sub_20" alt="Trimming video from end" /%}
{% /linetab %}

{% linetab title="Inside layer" %}
You can also use expressions in the `eo` parameter inside a layer. To ensure that layer video ends at 50 percent duration of the base video, you can use the following URL.
URL - [https://ik.imagekit.io/demo/img/sample-video.mp4?tr=l-video,i-img@@60cd.mp4,w-600,eo-bdu_mul_0.5,l-end](https://ik.imagekit.io/demo/img/sample-video.mp4?tr=l-video,i-img@@60cd.mp4,w-600,eo-bdu_mul_0.5,l-end)

{%video src="https://ik.imagekit.io/demo/img/sample-video.mp4?tr=l-video,i-img@@60cd.mp4,w-600,eo-bdu_mul_0.5,l-end" alt="Layer video will end at 50% of base video" /%}

{% /linetab %}
{% /linetabs %}

## Duration - (du)

Specify duration in seconds. It is often used with `so` to control the duration of the video to keep in output starting after `so` seconds.

Usage - `du-<value>`


**Possible values** - Specify the time in seconds as a positive number up to 2 decimal places, e.g.,  20 or 10.55, or an arithmetic expression like `idu_div_2`. It must be less than or equal to the duration of the input video.

{% linetabs %}
{% linetab title="Original (70 seconds)" %}
[https://ik.imagekit.io/demo/img/60cd.mp4](https://ik.imagekit.io/demo/img/60cd.mp4).

{%video src="https://ik.imagekit.io/demo/img/60cd.mp4" alt="Original video" /%}
{% /linetab %}

{% linetab title="so-5,du-5" %}
[https://ik.imagekit.io/demo/img/60cd.mp4?tr=so-5,du-5](https://ik.imagekit.io/demo/img/60cd.mp4?tr=so-5,du-5). This will return a video starting from 5th second and will be 5 seconds long.

{%video src="https://ik.imagekit.io/demo/img/60cd.mp4?tr=so-5,du-5" alt="Starting 5th second and duration 5 seconds" /%}

{% /linetab %}

{% linetab title="so-idu_mul_0.1,du-idu_mul_0.4"%}
To trim the video 10 percent from starting, and play it for next 40% you can use the following URL. [https://ik.imagekit.io/demo/img/60cd.mp4?tr=so-idu_mul_0.1,du-idu_mul_0.4](https://ik.imagekit.io/demo/img/60cd.mp4?tr=so-idu_mul_0.1,du-idu_mul_0.4). 

{%video src="https://ik.imagekit.io/demo/img/60cd.mp4?tr=so-idu_mul_0.1,du-idu_mul_0.4" alt="Starting at 10% and duration 40%" /%}
{% /linetab %}

{% linetab title="Inside layer" %}
You can also use expressions in the `du` parameter inside a layer. To ensure that layer video plays for 70 percent duration of the base video, you can use the following URL.
URL - [https://ik.imagekit.io/demo/img/sample-video.mp4?tr=l-video,i-img@@60cd.mp4,w-600,du-bdu_mul_0.7,l-end](https://ik.imagekit.io/demo/img/sample-video.mp4?tr=l-video,i-img@@60cd.mp4,w-600,du-bdu_mul_0.7,l-end)

{%video src="https://ik.imagekit.io/demo/img/sample-video.mp4?tr=l-video,i-img@@60cd.mp4,w-600,du-bdu_mul_0.7,l-end" alt="Layer video will end at 70% of base video" /%}

{% /linetab %}
{% /linetabs %}


---

# Source: /adaptive-bitrate-streaming

---
title: Adaptive bitrate streaming
description: Learn how to use Adaptive Bitrate Streaming for long videos with ImageKit and the Video Player SDK.
---

Adaptive Bitrate Streaming (ABS) automatically adjusts video quality based on each viewer's network speed and device capabilities. This eliminates buffering, speeds up playback startup, and delivers the best possible experience across all connections.

## Why ABS matters

- **Zero buffering**: Video automatically adapts to network conditions in real-time
- **Fast startup**: Begins playback immediately at the lowest quality, then upgrades as bandwidth becomes available
- **Universal compatibility**: Works seamlessly across all devices from mobile to 4K displays
- **Cost efficient**: Viewers on slow connections download smaller files, reducing bandwidth costs

## Quick start

**Recommended:** Use the [Video Player SDK](/video-player/overview) for production implementations. It handles ABS automatically with zero configuration complexity:

{% ikvideoplayer config="abs-demo" /%}

```javascript
const player = videoPlayer('my-video', {
  imagekitId: 'YOUR_IMAGEKIT_ID',
  abs: {
    protocol: 'hls', // or 'dash'
    sr: [240, 360, 480, 720, 1080] // Available resolutions
  }
});

player.src({
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4'
});
```

That's it! The Video Player SDK handles:
- Manifest generation
- Quality adaptation based on bandwidth
- Seamless transitions between quality levels
- Playback optimization

## How ABS works

Adaptive Bitrate Streaming works by splitting your video into multiple quality variants. The viewer's client (video player) loads the manifest file and continuously adapts playback:

1. Player loads manifest file with all available variants
2. Player starts playback at lowest bitrate for fast startup
3. Player monitors network speed and device capabilities
4. Player requests higher quality segments as bandwidth allows
5. Player downgrades quality if network slows down

This continuous adaptation creates a smooth experience without buffering or interruptions.

## How ImageKit handles ABS

ImageKit automatically generates all required variants and manifest files from your original video. You only need to provide the source video—ImageKit creates everything else:

- Generates multiple quality versions (240p through 4K)
- Creates HLS and/or DASH manifest files
- Serves all files through ImageKit's CDN
- Caches aggressively for performance

The original video can be hosted in ImageKit Storage or [external storage](/integration/connect-external-storage) integrated with your ImageKit account.

## Streaming protocols

ImageKit supports both major ABS protocols. Both work with all modern video players and leverage standard HTTP infrastructure including CDN caching:

- **HTTP Live Streaming (HLS)**: Apple's standard, excellent compatibility with all devices
- **MPEG-DASH**: Industry standard, more flexible and efficient

Choose based on your target audience and player requirements. The Video Player SDK supports both seamlessly.

## Manual implementation

For custom implementations or when not using the Video Player SDK, construct manifest URLs directly.

### HLS manifest URL

```
https://ik.imagekit.io/YOUR_ID/path/to/video.mp4/ik-master.m3u8?tr=sr-240_360_480_720_1080
```

### DASH manifest URL

```
https://ik.imagekit.io/YOUR_ID/path/to/video.mp4/ik-master.mpd?tr=sr-240_360_480_720_1080
```

### Generation timing

When you first request a manifest URL:
- Returns `202 Accepted` status (processing)
- ImageKit generates variants in the background (takes seconds to minutes depending on file size)
- Second request returns `200 OK` with the manifest

Use the `<video>` element with the appropriate MIME type for your chosen protocol (HLS uses `application/x-mpegURL`, DASH uses `application/dash+xml`).

## Quality representations (sr parameter)

Use the `sr` parameter to specify which quality variants to generate. You can include any combination of the supported representations below:

**Usage:** `sr-240_360_480_720_1080`

This tells ImageKit to generate 5 variants: 240p, 360p, 480p, 720p, and 1080p.

### Supported resolutions

| Representations | Resolution | Max Bitrate | Video Codec | Audio Codec | Format |
|-----------------|------------|-------------|-------------|-------------|--------|
| 240             | 426x240    | 200K        | h264        | aac         | mp4    |
| 360             | 640x360    | 400K        | h264        | aac         | mp4    |
| 480             | 854x480    | 800K        | h264        | aac         | mp4    |
| 720             | 1280x720   | 3300K       | h264        | aac         | mp4    |
| 1080            | 1920x1080  | 5500K       | h264        | aac         | mp4    |
| 1440            | 2560x1440  | 12000K      | h264        | aac         | mp4    |
| 2160            | 3840x2160  | 18000K      | h264        | aac         | mp4    |


{% callout style="info" %}
ImageKit uses H.264 codec for encoding video and AAC for encoding audio for both HLS and DASH.

All ABS representations will use [at_max cropping strategy](/video-resize-and-crop#max-size-cropping-strategy---c-at_max) to resize the representations. Output will match the aspect ratio of the original video after this change.
{% /callout %}

## Best practices

- **Use Video Player SDK**: The [Video Player SDK](/video-player/overview) handles ABS automatically with optimal quality adaptation.
- **Include 360p and higher**: Always include at least 360p for mobile, then 720p and 1080p for desktop.
- **Test manifest generation**: Allow 2-5 minutes for processing on first request depending on video size.

{% callout style="warning" %}
**Transformation limitations:** You cannot apply width (`w`), height (`h`), aspect ratio (`ar`), format (`f`), video codec (`vc`), audio codec (`ac`), or quality (`q`) transformations when using ABS. All other transformations work normally.
{% /callout %}

## Related features

- **[Video Player SDK](/video-player/overview)**: Built-in ABS with automatic adaptation and enhanced playback controls
- **[Video transformations](/video-transformation)**: Apply transformations alongside ABS for quality optimization
- **[Video optimization](/video-optimization)**: Best practices for video delivery and performance
- **[Core delivery features](/core-delivery-features)**: CDN caching, security, and delivery optimization


---

# Source: /video-webhook-events

---
title: Video Webhook Events
description: Listen to video webhook events to set up an end-to-end video encoding pipeline using ImageKit Video API.
---

Use webhook to get real-time updates about video transformation operations. Use the events like `video.transformation.accepted` and `video.transformation.ready` to automatically update fields in your database or CMS.

{% callout style="info" %}
Before receiving video related events, you need to [configure webhooks](/webhooks) in your ImageKit account.
{% /callout %}

- `video.transformation.accepted`
- `video.transformation.ready`
- `video.transformation.error`

## video.transformation.accepted

It is triggered when a new video transformation request is accepted for processing. You can use this for debugging purposes.

Example payload looks like below:

```js
{
  "type": "video.transformation.accepted",
  "id": "58e6d24d-6098-4319-be8d-40c3cb0a402d",
  "created_at": "2022-06-20T11:59:58.461Z",
  "request": {
    "x_request_id": "fa98fa2e-d6cd-45b4-acf5-bc1d2bbb8ba9",
    "url": "http://ik.imagekit.io/demo/sample-video.mp4?tr=f-webm,q-10",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:101.0) Gecko/20100101 Firefox/101.0"
  },
  "data": {
    "asset": {
      "url": "http://ik.imagekit.io/demo/sample-video.mp4"
    },
    "transformation": {
      "type": "video-transformation",
      "options": {
        "video_codec": "vp9",
        "audio_codec": "opus",
        "auto_rotate": true,
        "quality": 10,
        "format": "webm"
      }
    }
  }
}
```

Here is the description of all fields.

| Field                                       | Description                                                                   |
| ------------------------------------------- | ----------------------------------------------------------------------------- |
| type                                        | Type of event.                                                                |
| id                                          | Unique identifier of the event.                                               |
| createdAt                                   | Timestamp of the event in ISO8601 format.                                     |
| request.url                                 | URL of the submitted request.                                                 |
| request.x_request_id                        | A unique request ID to identify request.                                      |
| request.user_agent                          | `user_agent` in submitted request.                                            |
| data.asset.url                              | URL to download the source video file.                                        |
| data.transformation.type                    | `video-transformation`, `gif-to-video`, `video-thumbnail`                     |
| data.transformation.options.video_codec     | `h264` or `vp9`                                                               |
| data.transformation.options.audio_codec     | `aac` or `opus`                                                               |
| data.transformation.options.format          | `mp4`, `webm`, `jpg`, `png` or `webp`                                         |
| data.transformation.options.stream_protocol | `HLS` or `DASH`                                                               |
| data.transformation.options.variants        | Array of representations for ABS e.g. `["360","480","720","1028"]`.           |
| data.transformation.options.auto_rotate     | A boolean indicating whether to autorotate the video based on their metadata. |


## video.transformation.ready

It is triggered when a video encoding is finished, and the transformed resource is ready to be served. You should listen to this webhook and update any flag in your database or CMS against that particular asset so your application can start showing it to users.

Example payload looks like below:

```js
{
  "type": "video.transformation.ready",
  "id": "a03031b5-ad5f-4985-8cf5-4de67630f6d7",
  "created_at": "2022-06-20T12:00:11.703Z",
  "request": {
    "x_request_id": "fa98fa2e-d6cd-45b4-acf5-bc1d2bbb8ba9",
    "url": "http://ik.imagekit.io/demo/sample-video.mp4?tr=f-webm,q-10",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:101.0) Gecko/20100101 Firefox/101.0"
  },
  "timings": {
    "download_duration": 2713,
    "encoding_duration": 10175
  },
  "data": {
    "asset": {
      "url": "http://ik.imagekit.io/demo/sample-video.mp4"
    },
    "transformation": {
      "type": "video-transformation",
      "options": {
        "video_codec": "vp9",
        "audio_codec": "opus",
        "auto_rotate": true,
        "quality": 10,
        "format": "webm"
      },
      "output": {
        "url": "http://ik.imagekit.io/demo/sample-video.mp4?tr=f-webm,q-10",
        "video_metadata": {
          "duration": 15.023,
          "width": 1280,
          "height": 720,
          "bitrate": 180260
        }
      }
    }
  }
}
```

Here is the description of all fields.

| Field                                              | Description                                                                         |
| -------------------------------------------------- | ----------------------------------------------------------------------------------- |
| type                                               | Type of event.                                                                      |
| id                                                 | Unique identifier of the event.                                                     |
| createdAt                                          | Timestamp of the event in ISO8601 format.                                           |
| request.url                                        | URL of th submitted request.                                                           |
| request.x_request_id                               | A unique request ID to identify request.                                            |
| request.user_agent                                 | `user_agent` in the submitted request.                                                  |
| data.asset.url                                     | URL to download the source video file.                                                  |
| data.transformation.type                           | `video-transformation`, `gif-to-video`, `video-thumbnail`                           |
| data.transformation.options.video_codec            | `h264` or `vp9`                                                                     |
| data.transformation.options.audio_codec            | `aac` or `opus`                                                                     |
| data.transformation.options.format                 | `mp4`, `webm`, `jpg`, `png` or `webp`                                               |
| data.transformation.options.stream_protocol        | `HLS` or `DASH`                                                                     |
| data.transformation.options.variants               | Array of representations for ABS e.g. `["360","480","720","1028"]`.                 |
| data.transformation.options.auto_rotate            | A boolean indicating whether to autorotate the video based on their metadata.       |
| data.transformation.output.video_metadata.duration | Output duration in seconds.                                                         |
| data.transformation.output.video_metadata.bitrate  | Output bitrate (bits/second).                                                       |
| data.transformation.output.video_metadata.width    | Output video width.                                                                 |
| data.transformation.output.video_metadata.height   | Output video height.                                                                |
| data.transformation.output.url                     | URL to download output video.                                                       |
| data.timings.download_duration                     | Time spent downloading the video from your origin or media library in milliseconds. |
| data.timings.encoding_duration                     | Time spent in encoding in milliseconds.                                             |

## video.transformation.error

It is triggered if an error occurs during encoding. Listen to this webhook to log the reason. You should check your origin and URL endpoint settings if the reason is related to download failure. For the any other error reason, raise a support ticket at [support@imagekit.io](mailto:support@imagekit.io).

Example payload looks like below:

```js
{
    "type": "video.transformation.error",
    "request": {
        "x_request_id": "f005b939-7ca3-4310-9e1e-009239b3616b",
        "url": "http://ik.imagekit.io/demo/sample-video.mp4?tr=l-image,i-nonexistent.png,l-end",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:101.0) Gecko/20100101 Firefox/101.0"
    },
    "id": "293a65c6-ceb4-4b62-a10b-5f3333860fae",
    "created_at": "2022-06-20T12:14:02.353Z",
    "data": {
        "asset": {
            "url": "http://ik.imagekit.io/demo/sample-video.mp4"
        },
        "transformation": {
            "type": "video-transformation",
            "options": {
                "video_codec": "vp9",
                "audio_codec": "opus",
                "auto_rotate": true,
                "quality": 50,
                "format": "webm"
            },
            "error": {
                "reason": "download_failed"
            }
        }
    }
}
```

Here is the description of all fields.

| Field                                       | Description                                                                   |
| ------------------------------------------- | ----------------------------------------------------------------------------- |
| type                                        | Type of event.                                                                |
| id                                          | Unique identifier of the event.                                               |
| createdAt                                   | Timestamp of the event in ISO8601 format.                                     |
| request.url                                 | URL of the submitted request.                                                 |
| request.x_request_id                        | A unique request ID to identify request.                                      |
| request.user_agent                          | `user_agent` in the submitted request.                                        |
| data.asset.url                              | URL to download the source video file.                                        |
| data.transformation.type                    | `video-transformation`, `gif-to-video`, `video-thumbnail`                     |
| data.transformation.options.video_codec     | `h264` or `vp9`                                                               |
| data.transformation.options.audio_codec     | `aac` or `opus`                                                               |
| data.transformation.options.format          | `mp4`, `webm`, `jpg`, `png` or `webp`                                         |
| data.transformation.options.stream_protocol | `HLS` or `DASH`                                                               |
| data.transformation.options.variants        | Array of representations for ABS e.g. `["360","480","720","1028"]`.           |
| data.transformation.options.auto_rotate     | A boolean indicating whether to autorotate the video based on their metadata. |
| data.transformation.error.reason            | One of `encoding_failed`, `download_failed`, `internal_server_error`.         |


---

# Source: /arithmetic-expressions-in-transformations

---
title: Arithmetic Expressions in Transformations
description: Learn how to use arithmetic expressions in ImageKit transformations to create dynamic and flexible transformations.
---

ImageKit allows use of arithmetic expressions in certain dimension and position-related parameters, making media transformations more flexible and dynamic. They allow for more flexible and complex transformations without the need to hard code specific values in scenarios where the exact dimensions or positions may not be known beforehand or when they need to be adjusted based on other parameters.

Example use cases:

* Dynamic resizing:
  You can use arithmetic expressions to set the dimensions of an image relative to its original dimensions or other parameters. For instance, making the width of an image half of its original size using `w-iw_div_2`.
* Positioning overlays:
  Arithmetic expressions can be used to calculate the position of overlays or watermarks based on the dimensions of the original image. For instance, placing a watermark at a position that is 10% from the top and right edges of the image using the transformation `lx-bw_mul_0.9,ly-bh_mul_0.1`.
* Adjusting border in image:
  Arithmetic expressions can be used to calculate these values based on other parameters like the image's dimensions or aspect ratio using `b-ch_mod_5_yellow`.

You can create arithmetic expressions by using arithmetic operators with expression variables or positive numbers. A simple expression follows the `{value}_{operator}_{value}` syntax, where the value can be expression variables, positive integers, or positive decimal numbers. You can also directly assign expression variables like `ih`, or `bw` to supported parameters. For example, you can use expressions like `bh_div_2` or `ch_mul_0.25`. Furthermore, you can combine multiple operators and values to create complex expressions, such as `ih_mul_0.8_add_iw_mul_0.4`.

## Supported expression variables

| Property | Description                                                                                                                                                                                                               |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ih`     | Initial height of the asset. Inside a layer transformation, it indicates the initial height of the asset being overlaid.                                                                                                  |
| `iw`     | Initial width of the asset. Inside a layer transformation, it indicates the initial width of the asset being overlaid.                                                                                                    |
| `iar`    | Initial aspect ratio of the asset. Inside a layer transformation, it indicates the initial aspect ratio of the asset being overlaid.                                                                                      |
| `idu`    | It represents the original duration of the asset. Inside a layer transformation, it indicates the original duration of the asset being overlaid. It can only be used with durational parameters `so`, `eo`, `du`, `lso`, `ldu`, and `leo`.                                                                                                 |
| `ch`     | It represents the height resulting from the last applied transformation in a chain of transformations. Similarly, inside a layer transformation, it indicates the current height of the asset being overlaid.             |
| `cw`     | It represents the width resulting from the last applied transformation in a chain of transformations. Similarly, inside a layer transformation, it indicates the current width of the asset being overlaid.               |
| `car`    | It represents the aspect ratio resulting from the last applied transformation in a chain of transformations. Similarly, inside a layer transformation, it indicates the current aspect ratio of the asset being overlaid. |
| `bh`     | It represents the current height of the base asset upon which the layer will be overlaid. It can only be used within a layer transformation.                                                                              |
| `bw`     | It represents the current width of the base asset upon which the layer will be overlaid. It can only be used within a layer transformation.                                                                               |
| `bar`    | It represents the current aspect ratio of the base asset upon which the layer will be overlaid. It can only be used within a layer transformation.                                                                        |
| `bdu`    | It represents the current duration of the base asset upon which the layer will be overlaid. It can only be used within a layer transformation and with durational parameters `so`, `eo`, `du`, `lso`, `ldu`, and `leo`.    |   


## Supported operators
| Operator name | Operation       |
| ------------- | --------------- |
| add           | add             |
| sub           | sub             |
| mul           | mul             |
| div           | div             |
| mod           | mod (remainder) |
| pow           | pow             |

## Parameter supporting arithmetic expressions
{% table %}
- **Parameter** {% width="20%" %}
- **Examples** {% width="40%" %}
- **Remarks** {% width="40%" %}
---
- **h**
- h-ih_add_10
  
  h-ch_mul_0.8_add_bh_mul_0.6
- 
---
- **w**
- w-ih_add_10
  
  w-ch_mul_0.8_add_bh_mul_0.6
- 
---
- **ar**
- ar-car_mul_0.5
  
  ar-bar
- The calculated value of the expression will represent the `width/height` ratio.
---
- **x, y**
- x-iw_sub_cw
  
  y-ih_sub_ch
- 
---
- **xc, yc**
- xc-cw_mul_0.25
  
  yc-ch_mul_0.25
- 
---
- **b**
- b-ih_mul_0.05_red
  
  b-cw_mod_5_AAAA54
- The border follows the `{expression}_{color}` syntax, where the calculated expression value is used as the border width.
---
- **lx, ly, lxc, lyc**
- lx-bw_div_2
  
  ly-bh_div_2
  
  lxc-cw_div_2_add_iw_div_2
  
  lyc-ch_div_2_add_cw_div_2
- These are layer positional parameters that can be placed in any order within a chain of transformations inside a layer transformation but are always executed last. Hence `ch`, `cw`, and `car` expression variables, when used along with `lx`, `ly`, `lxc`, or `lyc` parameters, always represent the final height, width, and aspect ratio, respectively, of the asset being overlaid.
---
- **so, du, eo**
- so-bdu_sub_idu
  
  du-bdu_div_2
  
  eo-idu_div_2

- Valid expression variables are only `idu` and `bdu`.
---
- **lso, ldu, leo**
- lso-bdu_mul_0.2
  
  ldu-bdu_mul_0.5
  
  leo-idu_sub_2
- Valid expression variables are only `idu` and `bdu`. When these parameters are used inside an `image` or `text` layer, they can only accept `bdu` expression variable. 
---
- **pa**
- pa-bh_mul_0.05
  pa-bw_mod_5
- The calculated expression value will be applied as uniform padding along all four edges of the text.
---
- **fs**
- fs-bh_mul_0.1
  
  fs-bw_div_50
- 
---
- **sp** (inside [e-gradient](/effects-and-enhancements#gradient---e-gradient))
- sp-bh_mul_0.75
  
  sp-bh_div_2
- 
{% /table %}


## Calculation Sequence for multiple operators

1. Multiplication and Division: Multiplication and division are evaluated first from left to right.
2. Addition and Subtraction: Addition and subtraction are evaluated next from left to right.
3. Modulus: Modulus is evaluated then from left to right.
4. Power: Power is evaluated last from left to right.

{% callout style="info" %}
* If you're using expressions inside a layer, then the layer should be a separate chain transformation.

* Only the `bw`, `bh`, and `bar` expression variables are allowed inside text layers, solid image layers, and gradient block layers.
{% /callout %}

## Examples

### Resizing

To resize the height to half of the original, the width to one-fourth of the original, and then add a yellow color border that's 5% of the current width, you can use the following URL.

URL - [https://ik.imagekit.io/demo/img/plant.jpeg?tr=w-iw_div_4,h-ih_div_2:b-cw_mul_0.05_yellow](https://ik.imagekit.io/demo/img/plant.jpeg?tr=w-iw_div_4,h-ih_div_2:b-cw_mul_0.05_yellow)

![](https://ik.imagekit.io/demo/img/plant.jpeg?tr=w-iw_div_4,h-ih_div_2:b-cw_mul_0.05_yellow)

To crop the image with half height and width while extracting from a position that is 20% from top and left edges, you can use the following URL.

URL - [https://ik.imagekit.io/demo/medium_cafe_B1iTdD0C.jpg?tr=w-iw_div_2,h-ih_div_2,cm-extract,x-iw_mul_0.2,y-ih_mul_0.2](https://ik.imagekit.io/demo/medium_cafe_B1iTdD0C.jpg?tr=w-iw_div_2,h-ih_div_2,cm-extract,x-iw_mul_0.2,y-ih_mul_0.2)

![](https://ik.imagekit.io/demo/medium_cafe_B1iTdD0C.jpg?tr=w-iw_div_2,h-ih_div_2,cm-extract,x-iw_mul_0.2,y-ih_mul_0.2)

### Image overlay

You can also resize and position the image layer relative to the base asset. For example, to first resize the image being overlaid to half of the base image dimensions and then place it one-eight from the top and left edges, you can use the following URL.

URL - [https://ik.imagekit.io/demo/medium_cafe_B1iTdD0C.jpg?tr=l-image,i-logo-white_SJwqB4Nfe.png,cm-pad_resize,bg-yellow,w-bw_div_2,h-bh_div_2,lx-bw_div_8,ly-bh_div_8,l-end](https://ik.imagekit.io/demo/medium_cafe_B1iTdD0C.jpg?tr=l-image,i-logo-white_SJwqB4Nfe.png,cm-pad_resize,bg-yellow,w-bw_div_2,h-bh_div_2,lx-bw_div_8,ly-bh_div_8,l-end)

![](https://ik.imagekit.io/demo/medium_cafe_B1iTdD0C.jpg?tr=l-image,i-logo-white_SJwqB4Nfe.png,cm-pad_resize,bg-yellow,w-bw_div_2,h-bh_div_2,lx-bw_div_8,ly-bh_div_8,l-end)

Expressions can also conveniently be used to resize and position nested layers in relation to their outer layers. In this example, we overlay the resized `women-dress.jpeg` with a red border, positioning it 10% from the top and left edges of `medium_cafe_B1iTdD0C.jpg`, and then add the `imagekit.io` logo, positioning it at 10% from the top and left edges of `women-dress.jpeg`.

URL - [https://ik.imagekit.io/demo/tr:l-image,i-women-dress.jpeg,w-bw_div_3,b-iw_mul_0.02_red,lx-bw_mul_0.1,ly-bh_mul_0.1:l-image,i-logo-white_SJwqB4Nfe.png,w-bw_div_2,lx-bw_mul_0.1,ly-bh_mul_0.1,l-end,l-end/medium_cafe_B1iTdD0C.jpg](https://ik.imagekit.io/demo/tr:l-image,i-women-dress.jpeg,w-bw_div_3,b-iw_mul_0.02_red,lx-bw_mul_0.1,ly-bh_mul_0.1:l-image,i-logo-white_SJwqB4Nfe.png,w-bw_div_2,lx-bw_mul_0.1,ly-bh_mul_0.1,l-end,l-end/medium_cafe_B1iTdD0C.jpg)

![](https://ik.imagekit.io/demo/tr:l-image,i-women-dress.jpeg,w-bw_div_3,b-iw_mul_0.02_red,lx-bw_mul_0.1,ly-bh_mul_0.1:l-image,i-logo-white_SJwqB4Nfe.png,w-bw_div_2,lx-bw_mul_0.1,ly-bh_mul_0.1,l-end,l-end/medium_cafe_B1iTdD0C.jpg)

### Text overlay

To control the text layer's width and font size with respect to the base layer, you can use the following URL.

URL - [https://ik.imagekit.io/demo/medium_cafe_B1iTdD0C.jpg?tr=l-text,i-overlay%20made%20easy,fs-bh_div_20,w-bh_div_2,l-end](https://ik.imagekit.io/demo/medium_cafe_B1iTdD0C.jpg?tr=l-text,i-overlay%20made%20easy,fs-bh_div_20,w-bh_div_2,l-end)

![](https://ik.imagekit.io/demo/medium_cafe_B1iTdD0C.jpg?tr=l-text,i-overlay%20made%20easy,fs-bh_div_20,w-bh_div_2,l-end)

To add padding to a text layer with a background color, you can use the following URL.

URL - [https://ik.imagekit.io/demo/medium_cafe_B1iTdD0C.jpg?tr=l-text,i-overlay%20made%20easy,bg-yellow,pa-bw_mul_0.01,l-end](https://ik.imagekit.io/demo/medium_cafe_B1iTdD0C.jpg?tr=l-text,i-overlay%20made%20easy,bg-yellow,pa-bw_mul_0.01,l-end)

![](https://ik.imagekit.io/demo/medium_cafe_B1iTdD0C.jpg?tr=l-text,i-overlay%20made%20easy,bg-yellow,pa-bw_mul_0.01,l-end)

### Video overlay

Expressions can also be used inside video layers for resizing and positioning in parameters that allow arithmetic expressions.

To overlay the video of size half of base width and height, we can use the following URL.

URL - [https://ik.imagekit.io/demo/img/60cd.mp4?tr=l-video,i-img@@sample-video.mp4,w-bw_div_2,h-bh_div_2,l-end](https://ik.imagekit.io/demo/img/60cd.mp4?tr=l-video,i-img@@sample-video.mp4,w-bw_div_2,h-bh_div_2,l-end)

{%video src="https://ik.imagekit.io/demo/img/60cd.mp4?tr=l-video,i-img@@sample-video.mp4,w-bw_div_2,h-bh_div_2,l-end"/%}


To overlay the video at 25 percent from the top-left corner along both `x` and `y` direction, with a width of `600px`, we can use the following URL.

URL - [https://ik.imagekit.io/demo/img/60cd.mp4?tr=l-video,i-img@@sample-video.mp4,lx-bw_div_4,ly-bh_div_4,w-600,l-end](https://ik.imagekit.io/demo/img/60cd.mp4?tr=l-video,i-img@@sample-video.mp4,lx-bw_div_4,ly-bh_div_4,w-600,l-end)

{%video src="https://ik.imagekit.io/demo/img/60cd.mp4?tr=l-video,i-img@@sample-video.mp4,lx-bw_div_4,ly-bh_div_4,w-600,l-end"/%}

### Trimming the video
We can also use expressions with trim parameters `so`, `du`, `eo` and positional parameters `lso`, `ldu`, `leo` to trim the video smartly.

{% callout style="info" %}
Trim parameters `so`, `du` and `eo` can only be used once in a chain transformation if any of them is using expression variable.
For ex. `tr:so-idu_mul_0.2,du-idu_mul_0.4` is a valid transformation, but `tr:so-idu_mul_0.2,du-idu_mul_0.4:so-idu_mul_0.2` is invalid and result in an error.
{% /callout %}


To trim the video 10 sec from the end we can use the below URL.

URL - [https://ik.imagekit.io/demo/img/60cd.mp4?tr=eo-idu_sub_10](https://ik.imagekit.io/demo/img/60cd.mp4?tr=eo-idu_sub_10)

{%video src="https://ik.imagekit.io/demo/img/60cd.mp4?tr=eo-idu_sub_10"/%}

To start the overlay after half of the base video’s duration has passed, use the following URL.

URL - [https://ik.imagekit.io/demo/img/60cd.mp4?tr=l-video,i-img@@sample-video.mp4,w-600,lso-bdu_div_2,l-end](https://ik.imagekit.io/demo/img/60cd.mp4?tr=l-video,i-img@@sample-video.mp4,w-600,lso-bdu_div_2,l-end)

In the below video overlay will start at 35 seconds.

{%video src="https://ik.imagekit.io/demo/img/60cd.mp4?tr=l-video,i-img@@sample-video.mp4,w-600,lso-bdu_div_2,l-end"/%}


---

# Source: /optimize-image-and-video-for-web-delivery

---
title: Optimize Image and Video for Web Delivery
description: Learn how to optimize images and videos for web delivery using ImageKit.io.
---

ImageKit automates many aspects of image and video optimization for web delivery and provides a range of features that allow you to tweak the optimization settings to suit your specific requirements.

ImageKit automatically converts images & videos to the most optimal format and quality based on the user's device, input format, and account settings. Learn more about:

* [Image optimization](/image-optimization)
* [Video optimization](/video-optimization)

## Content Negotiation in Browser & Mobile App

ImageKit uses the standard [content negotiation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation) approach to identify the image formats supported by a device or browser. This content negotiation technique depends on the request's `Accept` header value. We use `User-Agent` headers to determine the supported formats for videos. However, mobile apps do not always send these headers. You can refer to [mobile app-specific optimizations](/production-checklist#mobile-app-specific-optimizations) to ensure the correct format is delivered to mobile apps.

{% callout style="info" %}
On the enterprise plan, you can specify a list of user agents for which ImageKit should serve images in next-gen formats.
{% /callout %}

## Network-Based Optimization

There are two steps to building this:

### Step 1: Determine the user's network speed

If a user is connected to 4G mobile data, they may not get the download speed expected on 4G. The actual download speed can vary. There are different ways of determining this on apps and websites. 

On any browser, web or mobile, that supports the `NetworkInformation` API, you can get the approximate category of the user's download speeds using the value of `navigator.connection.effectiveType`. 

On mobile devices, external libraries such as Meta's [Network Connection Class](https://github.com/facebookarchive/network-connection-class) evaluate connection quality by monitoring network traffic and categorizing it accordingly. 

Both methods above categorize the user into a class that gives an approximate representation of their download speed.

### Step 2: Adjust the file compression and resolution based on the network speed

Once you have determined whether the user has a fast or slow download speed, you can decide the compression level for that user. You can adjust the quality of images and videos using the [quality (q)](/image-optimization#quality---q) parameter. To serve in lower resolution, apply [height (h)](/image-resize-and-crop#height---h) and [width (w)](/image-resize-and-crop#width---w) transformations. 

### Where to make this quality parameter change in your app or website

1. For apps, since the layout is rendered on the client side, you can change the media URLs you receive from your backend APIs and add the quality parameter to them before adding them to the layout.
2. For web and mobile web, if you use a client-side rendering framework like React or Vue, you can use the same technique as point 1—add the quality parameter to the file URL you receive from the backend and use it on your website.
3. If you use a server-side rendered website, the server won't know the user's effective connection type. In such cases, you will need to intercept the file requests in a service worker, modify their URL with the quality parameter, and get the response from the modified URL.

{% callout style="info" %}
1. You may only want to optimize some files based on the user's network. For example, your logo or a sale banner should always appear in high quality on the app or website. Take this into account when implementing network-based media optimization.
   
2. Find the quality thresholds that work for your business for different network types. Some businesses may be unable to increase compression because it reduces visual quality.
   
3. See if you can eliminate network-based optimization by performing other format, quality, and responsive image optimizations or by reducing the default compression level. This will save you a lot of development time while giving all your users a good user experience. Refer to the docs here to [fix all media performance issues](/production-checklist#fix-media-performance-issues) pointed out by standard tools such as Google Lighthouse or PageSpeed.
{% /callout %}


---

# Source: /image-optimization

---
title: Image optimization
description: Learn how to optimize images for web delivery using ImageKit.io.
---

Image optimization is very important for any web application. Optimized images load faster, consume less bandwidth, and improve the overall user experience. On the other hand, unoptimized images load slowly, degrade user experience, increase bounce rates, and negatively impact your business.

Images are the single largest contributor to the Largest Contentful Paint (LCP) metric, a key metric for measuring page load speed. Optimizing images can significantly improve your LCP score.

{% callout style="info" %}
ImageKit automates many aspects of image optimization for web delivery. Additionally, it provides a range of features that allow you to tweak the optimization settings further to suit your specific requirements.
{% /callout %}

## What is image optimization?

Image optimization is a set of techniques to reduce image file size without compromising "perceived" image quality. The goal is to make images load faster on web and mobile applications. Techniques that are used for image optimization include:

* **Image compression** - Reducing the file size of an image while maintaining visual quality using lossy compression techniques. Learn how [automatic image compression](#automatic-image-compression) works in ImageKit.
* **Image format selection** - Choosing the right output image format based on the image content and device. Learn how [automatic format conversion](#automatic-format-conversion) works in ImageKit.
* **Image resizing** - Changing the dimensions of an image on the server side to fit the application layout on the front end. Learn how to [correctly resize images](#how-to-resize-images).
* **Lazy loading** - Loading images only when the user is about to see them on the screen. Learn how to [lazy load images](#how-to-lazy-load-images).

## Limits and supported image formats

Refer to [supported image formats](/transformations#supported-formats) for a list of image formats supported by ImageKit.io for optimization. Check out various [limits](/transformations#limits).

## Automatic image compression

Image quality is a measure of the perceived visual quality of the image. ImageKit.io measures the image quality on a scale of 1 to 100, with 100 indicating the best quality and 1 indicating the lowest quality. Image quality and file size are also directly proportional. The higher the image quality, the larger the file size.

The human eye's inability to perceive pixel-level changes in an image can be advantageous for serving smaller images.

For example, the images below show no perceived visual difference between quality 100 and 80.

![Image Quality](<https://ik.imagekit.io/ikmedia/docs_images/features/image-optimization/quality-optimization/qualityoptimization_xK-qYC02N9.png?updatedAt=1704455461047>)

ImageKit automatically compresses images to reduce the file size without compromising the visual quality. The [quality](#quality---q) parameter controls the compression level. The default quality is set to 80, but you can change it from the [dashboard settings](https://imagekit.io/dashboard/settings/images).

![Image quality settings in ImageKit.io dashboard](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/image-quality-setting.png?tr=w-1600>)

By default, ImageKit strips out all the metadata from the image, including the color profile. Learn more about [image metadata](#image-metadata---md).

{% callout style="info" %}
Specific industries like eCommerce, which depend on image quality to drive conversions, can choose a quality level between 85 and 95. As mentioned earlier, the higher the image quality, the larger the file size. Avoid setting your image quality at 100. This will lead to a larger image size without much perceptible improvement in the visual quality of the image.
{% /callout %}

## Automatic format conversion

The right image format is the one that provides high quality and the smallest file size based on the image content and device support. This means that AVIF may be suitable for some users, and JPEG may be the better choice for others.

ImageKit automatically converts images to the most optimal format based on the user's device, input format, and account settings. The [format](#format---f) parameter can control the output format. You can turn off image format optimization from the [dashboard settings](https://imagekit.io/dashboard/settings/images).

![](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/best-image-format-settings.png?tr=w-1600)

ImageKit uses standard content negotiation techniques to identify the image formats a device or browser supports. This content negotiation technique depends on the request's `Accept` header value. However, mobile apps do not always send these headers. You can force the output format using URL transformation parameters to ensure that the right format is delivered to mobile apps. Or, for enterprise plans, you can specify a list of user agents for which ImageKit should serve images in next-gen formats.

![](https://ik.imagekit.io/ikmedia/docs_images/features/image-optimization/automatic-image-format-conversion/Optimized%20asset%20delivery%20based%20on%20user%20agents_uQ6n1v-ThV.png?tr=w-1600)

## How to resize images

Resizing an image means changing its dimensions on the server side per layout requirements before delivering it to the user. Many of us have inadvertently uploaded full-size images directly onto web pages. This is an easy mistake to make, especially when fast internet speeds make large images appear to load swiftly and display properly. However, in practical scenarios, this can significantly degrade performance as users are forced to download excessive data, impacting their experience negatively.

Use height (h) and width (w) parameters to resize images. Learn about [basic image resizing](/image-resize-and-crop) parameters.

Check out the [Responsive Image Guide](https://imagekit.io/responsive-images) for more information about correctly sizing images for different devices.

## How to lazy load images

Lazy Loading Images is a set of techniques in web and application development that defer the loading of images on a page to a later time - when those images are needed, instead of loading them upfront. These techniques help improve performance, better utilize the device's resources, and reduce associated delivery costs.

{% callout style="info" %}
Learn more about [lazy load images](https://imagekit.io/blog/lazy-loading-images-complete-guide/). If you are using ImageKit's React, Vue.js, or Angular SDK, you will get lazy loading out of the box.
{% /callout %}

## Image metadata - (md)

By default, ImageKit removes all metadata as part of [automatic image compression](#automatic-image-compression). You can control this using the `md` parameter.

It specifies whether the output image should contain all the metadata that is initially available with the original image. Image metadata is not relevant for rendering on the web and apps, so it is recommended not to use it while delivering images. The only situation to enable the metadata option is when you want additional data like camera information, lens information, and other image profiles attached to your original image. 

**Default value** - `false` (from the dashboard).

**Possible values** - `true` and `false`.

## Color profile and orientation metadata

Image metadata contains information about the color profile and orientation of the image. Here's how ImageKit handles color profile and orientation:

* **Color profile**: ImageKit removes all metadata, including the color profile, by default. You can globally control this behavior from the [dashboard settings](https://imagekit.io/dashboard/settings/images) or use the [color profile - (cp)](#color-profile---cp) parameter on URL-basis. Use `cp-true` to preserve the color profile.
* **Orientation**: ImageKit automatically rotates the image based on the EXIF orientation tag in image metadata. You can globally control this behavior from the [dashboard settings](https://imagekit.io/dashboard/settings/images) or use [rotate - (rt)](/effects-and-enhancements#rotate---rt) parameter on URL-basis. Use `rt-auto` to auto-rotate based on metadata.
* **Entire metadata**: You can preserve all the metadata using the [Image metadata - (md)](#image-metadata---md) parameter. Use `md-true` to preserve the metadata.

![Color profile setting](https://ik.imagekit.io/ikmedia/docs_images/features/image-optimization/metadata-color-profile-and-orientation/color-profile-setting-in-imagekitio-dashboard_IL9E1DIEG.png?tr=w-1600)

![Rotation setting](https://ik.imagekit.io/ikmedia/docs_images/features/image-optimization/metadata-color-profile-and-orientation/auto-image-orientation-setting-in-imagekitio-dashboard_WoFgUmO3l.png?tr=w-1600)

## Color profile - (cp)

It specifies whether the output image should contain the color profile initially available with the original image. It is recommended that the color profile be removed before serving the images on the web and apps. However, if you feel that the output image looks faded or washed out after using ImageKit.io and want to preserve the colors of your original image, you should set this parameter to `true`.

**Default value** - `false` (from the dashboard).

**Possible values** - `true` and `false`.

{% linetabs %}
{% linetab title="cp=false (Default)" %}
URL - [https://ik.imagekit.io/ikmedia/tr:h-300,w-400,f-jpg,cp-false/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:h-300,w-400,f-jpg,cp-false/docs_images/examples/example_food_3.jpg)

![](https://ik.imagekit.io/ikmedia/tr:h-300,w-400,f-jpg,cp-false/docs_images/examples/example_food_3.jpg)
{% /linetab %}

{% linetab title="cp=true" %}
URL - [https://ik.imagekit.io/ikmedia/tr:h-300,w-400,f-jpg,cp-true/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:h-300,w-400,f-jpg,cp-true/docs_images/examples/example_food_3.jpg)

You might not observe any change in this particular image. It depends on if the original image has any specific color profile or not.

![](https://ik.imagekit.io/ikmedia/tr:h-300,w-400,f-jpg,cp-true/docs_images/examples/example_food_3.jpg)
{% /linetab %}
{% /linetabs %}

{% callout style="info" %}
If a URL contains both `cp-true` and `md-false` at the same time, then the `md-false` will take precedence and all metadata will be stripped, including the color profile if present.
{% /callout %}

## Progressive image - (pr)

Used to specify whether the output JPEG image must be rendered progressively. In progressive loading, the output image renders as a low-quality pixelated full image, which, over time, keeps on adding more pixels and information to the image.  This helps you maintain a fast perceived load time.

**Possible values** - `true` and `false`.

[https://ik.imagekit.io/ikmedia/tr:h-300,w-400,f-jpg,pr-true/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:h-300,w-400,f-jpg,pr-true/docs_images/examples/example_food_3.jpg)

## Lossless WebP and PNG - (lo)

Used to specify whether the output image (if in JPEG or PNG) must be compressed losslessly. In lossless compression, the output file size is larger than the regular lossy compression. However, the perceived image quality can be higher in certain cases, especially for computer-generated graphics. Using lossless compression for photographs is not recommended.

**Possible values** - `true` and `false`.

[https://ik.imagekit.io/ikmedia/tr:w-500,h-361,lo-true/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:w-500,h-361,lo-true/docs_images/examples/example_food_3.jpg)

## Quality - (q)

Used to specify the quality of the output image for lossy formats like JPEG, WebP, and AVIF.  A large quality number indicates a larger output image size with high quality. A small quality number indicates a smaller output image size with lower quality. 

**Default value** - `80` (can be managed from image settings in the dashboard)

{% linetabs %}
{% linetab title="quality=90" %}
URL - [https://ik.imagekit.io/ikmedia/tr:q-90/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:q-90/docs_images/examples/example_food_3.jpg)

![](https://ik.imagekit.io/ikmedia/tr:q-90/docs_images/examples/example_food_3.jpg)
{% /linetab %}

{% linetab title="quality=10" %}
URL - [https://ik.imagekit.io/ikmedia/tr:q-10/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:q-10/docs_images/examples/example_food_3.jpg)

![](https://ik.imagekit.io/ikmedia/tr:q-10/docs_images/examples/example_food_3.jpg)
{% /linetab %}
{% /linetabs %}

## Format - (f)

Used to specify the format of the output image. If no output image format is specified then based on your image settings in the dashboard, ImageKit.io [automatically picks the best format](/image-optimization) for that image request.

Possible values include `auto`, `orig`, `jpg`, `jpeg`, `webp`, `avif` and `png`.

If `orig` is used, then image remains in its original format after processing.

**Default value** - `auto` (from dashboard settings).

{% callout style="info" %}
A few WebP images may not render correctly in Safari v14+ on MacOS v11+ and IOS 14 because of a [possible OS-level issue](https://bugs.webkit.org/show\_bug.cgi?id=219977).
{% /callout %}

## Data Saver Mode

Mobile browsers like Chrome Mobile and Opera Mobile allow users to activate a Data Saver mode. With this mode enabled, the browser sends a `Save-data` header within the request. By identifying this header, a web page can customize and deliver an optimized user experience to cost—and performance-constrained users.

ImageKit supports Data Saver mode to further optimize images for users on slow connections. You can turn on this setting within the Optimization section of the [Image Settings](https://imagekit.io/dashboard/settings/images).

![Data Saver Mode setting in ImageKit.io dashboard](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/data-saver-setting.png?tr=w-1600)

## Chroma Subsampling

Chroma Subsampling is an optimization technique that is used for JPEG encoding. This takes advantage of the lower sensitivity of the human eye towards color (chroma) than towards brightness (luma).

It is generally recommended to use 4:2:0 chroma subsampling on all images for a smaller output image. But in certain cases, especially ones with a bright object in the foreground over a completely white background, this optimization introduces unwanted artefacts, i.e., as your image size gets smaller, the visual quality goes down as well.

ImageKit.io keeps this setting turned OFF by default to avoid changing the image's visual quality. It is recommended to test this setting with your images before implementing it on your live site.

{% callout style="info" %}
**Note:** \
Since Chroma Subsampling is turned OFF by default, web analysis tools like Google's PageSpeed Insights might show that your images can be further optimized by a couple of KBs.
{% /callout %}

You can turn on Chroma Subsampling within the Optimization section of the [Image Settings](https://imagekit.io/dashboard/settings/images).

![Chroma Subsampling setting in ImageKit.io dashboard](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/chroma-setting.png?tr=w-1600)


## PNG Compression

ImageKit.io performs lossy compression for all your images by default. Lossy compression helps deliver smaller-sized files with good perceived visual quality.

However, certain images like computer-generated graphics and logo designs aren't great with lossy compression. In such cases, lossless compression can result in better visual quality at the expense of image size.

Lossless compression is turned OFF by default. You can switch on lossless compression using the parameter `lo-true` in the URL. This transformation parameter applies to both, PNG as well as WebP images.

For example:

[https://ik.imagekit.io/demo/img/tr:w-500,h-361,lo-true/default-image.jpg](https://ik.imagekit.io/demo/img/tr:w-500,h-361,lo-true/default-image.jpg)

The above URL delivers a losslessly compressed WebP image in Chrome. Adding the parameter `f-png` to the above URL results in a losslessly compressed PNG image.

Additionally, from the [ImageKit.io dashboard](https://imagekit.io/dashboard/settings/images), you can change the PNG compression mode from the Advanced Settings tab under Image Settings and set it to `Minimum` . This compression mode change from the dashboard is applicable only for PNG images.

You can completely turn off PNG image optimization by setting the PNG Compression mode to `None` from your dashboard. This is not recommended.


---

# Source: /video-optimization

---
title: Video Optimization
description: Learn how to optimize videos for web delivery using ImageKit.io.
---

Videos are becoming an essential part of modern web applications. However, they can be large in file size, and slow loading times can degrade the playback experience.

ImageKit automates many aspects of video optimization for web delivery and provides a range of features that allow you to tweak the optimization settings further to suit your specific requirements.

## What is Video Optimization?

Video optimization is the process of compressing and converting videos to reduce their file size while maintaining the best possible quality. This process ensures that videos load quickly and play smoothly on all devices.

* **Video compression** - Reducing the video file size while maintaining visual quality using lossy compression techniques. Learn how [automatic video compression](#automatic-video-compression) works in ImageKit.
* **Video format selection** - Choosing the right output video format based on the video content and device. Learn how [automatic format conversion](#automatic-format-conversion) works in ImageKit.
* **Video resizing** - Changing the dimensions of a video on the server side to fit the application layout on the front end. Learn how to [correctly resize videos](#how-to-resize-video).
* **Adaptive bitrate streaming** - Delivering videos at different quality levels based on the user's network speed. Learn how to [implement adaptive bitrate streaming](/adaptive-bitrate-streaming) with ImageKit.
* **Lazy loading** - Loading videos only when the user plays them. Learn how to [lazy load videos](#how-to-lazy-load-videos).

## Limits and supported video formats

Refer to [supported video formats](/transformations#supported-formats) for a list of video formats supported by ImageKit.io for optimization. Check out various [limits](/transformations#limits).

## Pricing

{% callout %}
All video processing, including format optimization, compression, transformations, and adaptive bitrate streaming, consumes video processing units. To learn more about how video processing units are consumed, [refer to this documentation](/how-pricing-works#video-processing-units-pricing).
{% /callout %}

## Automatic Video Compression

Video quality measures the perceived visual quality of the video. ImageKit.io measures video quality on a scale of 1 to 100, with 100 indicating the best quality and 1 indicating the lowest quality. Video quality and file size are also directly proportional. The higher the video quality, the larger the file size.

Since our eyes are better at seeing differences in brightness than color, the video encoder stores more detail for brightness and less for color. This helps reduce the file size without losing much quality.

ImageKit automatically compresses videos to reduce the file size without compromising the visual quality. The [quality](#quality---q) parameter controls the compression level. The default quality is set to 50, but you can change it from the [dashboard settings](https://imagekit.io/dashboard/settings/videos).

{% callout style="info" %}
ImageKit relies on the presence of a `.mp4` or `.mov` extension in the URL. If your resource doesn't have that extension, you can add `/ik-video.mp4` at the end. ImageKit uses it as a hint to fetch the original asset from your media library or origin and perform video optimization.

For example, if your original asset URL is \
`https://ik.imagekit.io/demo/img/video-no-extension_X9my06BI-`

You can add `/ik-video.mp4` at the end to perform video transformation and optimization i.e. \
`https://ik.imagekit.io/demo/img/video-no-extension_X9my06BI-/ik-video.mp4`
{% /callout %}


![Video Quality](<https://ik.imagekit.io/ikmedia/docs_images/features/video-optimization/quality-optimization/video-default-quality-settings_G-qw5jgYe.png?tr=w-1600>)

{% callout style="info" %}
Choosing 100 quality will not improve an already low-quality video. However, it will increase the size of the video file. It is recommended not to use a 100-quality setting.
{% /callout %}

See the difference in file size and quality between a video at quality 90 and quality 50.

{% linetabs %}
{% linetab title="Quality 20 (5MB)" %}

[https://ik.imagekit.io/ikmedia/docs_images/examples/Videos/example_video_2.mp4?tr=q-20,f-mp4](https://ik.imagekit.io/ikmedia/docs_images/examples/Videos/example_video_2.mp4?tr=q-20,f-mp4)

![Quality 20](<https://ik.imagekit.io/ikmedia/docs_images/features/video-optimization/quality-optimization/quality-20__ZSTNTIkS.png?tr=w-1600>)

{% /linetab %}
{% linetab title="Quality 90 (76MB)" %}

[https://ik.imagekit.io/ikmedia/docs_images/examples/Videos/example_video_2.mp4?tr=q-90,f-mp4](https://ik.imagekit.io/ikmedia/docs_images/examples/Videos/example_video_2.mp4?tr=q-90,f-mp4)

![Quality 90](<https://ik.imagekit.io/ikmedia/docs_images/features/video-optimization/quality-optimization/quality-90_g4yDQneKE.png?tr=w-1600>)

{% /linetab %}
{% /linetabs %}

## Automatic Format Conversion

Format Optimization is the process of delivering the best video format to the end-user while considering various factors such as requesting device capabilities, browser support for certain video formats, and your preferences. Ensuring the right format helps you reduce the size of the video and, subsequently, the playback time.

ImageKit chooses between H.264, VP9, and AV1 codecs and automatically delivers the video in the appropriate format based on browser support. You can control the output format using the [format](#format---f) parameter or from the [dashboard settings](https://imagekit.io/dashboard/settings/videos).

{% callout style="info" %}
ImageKit relies on the presence of a `.mp4` or `.mov` extension in the URL. If your resource doesn't have that extension, you can add `/ik-video.mp4` at the end. ImageKit uses it as a hint to fetch the original asset from your media library or origin and perform video optimization.

For example, if your original asset URL is \
`https://ik.imagekit.io/demo/img/video-no-extension_X9my06BI-`

You can add `/ik-video.mp4` at the end to perform video transformation and optimization i.e. \
`https://ik.imagekit.io/demo/img/video-no-extension_X9my06BI-/ik-video.mp4`
{% /callout %}

![Automatic format conversion setting](<https://ik.imagekit.io/ikmedia/docs_images/features/video-optimization/automatic-video-format-conversion/video-settings_FZhrYg9gT.png?ik-obj-version=GrFnNY_86d.L4JyqFy4ED6vFYkMrF7EC&tr=w-1600>)

* **H.264**—This is a widely supported video codec that provides good quality and compression. It is supported by most browsers and devices. Use H. 264 to ensure compatibility with older devices.
* **VP9** is a high-quality video codec with better compression than H.264. Modern browsers and devices support it. For better compression and quality, use [VP9](https://imagekit.io/blog/vp9-codec/).
* **AV1**—It is the predecessor to VP9 and provides better compression and quality. It is supported by modern browsers and devices. Use [AV1](https://imagekit.io/blog/av1-codec/) for the highest quality at the lowest file size.

## How to Resize Video

Resizing videos means resizing the dimensions of videos on the server side to fit the application's layout on the front end. The lower the resolution of the video, the smaller the file size and the faster the loading time.

You can resize videos using the [height (h)](/video-resize-and-crop#height---h) and [width (w)](/video-resize-and-crop#width---w) parameters. Learn more about [basic video resizing and cropping](/video-resize-and-crop).

## How to Lazy Load Videos

Lazy loading videos means preventing browser requests for videos until the user explicitly plays them or scrolls near them. This technique can improve the initial loading time of the web page and reduce bandwidth usage.

You can leverage `preload="none"` attribute in the video tag to lazy load videos. This attribute tells the browser not to download the video until the user hits the play button.

```html
<video controls preload="none">
  <source src="https://ik.imagekit.io/demo/sample-video.mp4" type="video/mp4">
 Your browser does not support the video tag.
</video>
```

You can also check the following libraries for lazy-loading videos:

* [vanilla-lazyload](https://github.com/verlok/vanilla-lazyload) and [lozad.js](https://github.com/ApoorvSaxena/lozad.js) are highly efficient options that rely on the Intersection Observer. They require polyfills for compatibility with older browsers.
* [yall.js](https://github.com/malchata/yall.js) incorporates both Intersection Observer and event handlers, offering a robust solution. It can also handle the lazy loading of video poster images via a data-poster attribute.
* If you're developing with React, consider [react-lazyload](https://github.com/jasonslyvia/react-lazyload). Although it doesn't utilize Intersection Observer, it provides a method for lazy loading that is familiar to those accustomed to React development.

## Quality - (q)

ImageKit.io allows you to choose a quality level between `1` and `100`. `1` results in the lowest perceptual quality and smallest file size. `100` results in the highest perceptual quality and biggest file size.

{% callout style="info" %}
Setting quality to 100 will not improve an already low-quality video. However, it will increase the size of the video file. It is recommended not to set quality to 100.
{% /callout %}

**Default value** - `50`. You can change the default quality setting from the dashboard.

### Video at quality 90

URL - [https://ik.imagekit.io/demo/sample-video.mp4?tr=h-300,w-300,q-90](https://ik.imagekit.io/demo/sample-video.mp4?tr=h-300,w-300,q-90)

The video size is 3.3MB, which is larger than the original 1.1MB video.

![Video at quality 90](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/q-90-3.3mb.png?tr=w-1600)

### Video at quality 50

URL - [https://ik.imagekit.io/demo/sample-video.mp4?tr=h-300,w-300,q-50](https://ik.imagekit.io/demo/sample-video.mp4?tr=h-300,w-300,q-50)

The video size is 406KB, which is less than half of the original 1.1MB video. The file size is reduced by 60%, and there is no perceptual change in the output video.

![Video at quality 50](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/q-50-406kb.png?tr=w-1600)

## Format - (f)

Used to specify the format of the output video. If no output format is specified then based on your settings in the dashboard, ImageKit.io automatically picks the best format for that video request.

Possible values include `auto` ,`mp4` , `webm`.

**Default value** - `auto`. You can disable [automatic video format conversion](#automatic-format-conversion) from the dashboard settings.

## Audio codec - (ac)

Used to specify the audio codec for encoding the output.

Possible values include `aac`, `opus`, and `none`.

Use `none` to remove audio from the source video. So, the output will have no audio.

## Video codec - (vc)

Used to specify the video codec for encoding the output.

Possible values include `h264`, `vp9`, `av1` and `none`

Use `none` to extract audio from the source video. The output will be an audio file.

## Valid combinations for format (f), audio codec (ac) & video codec (vc)

| f    | ac   | vc   |
| ---- | ---- | ---- |
| mp4  | aac  | h264 |
| mp4  | aac  | none |
| mp4  | none | h264 |
| webm | opus | vp9  |
| webm | opus | none |
| webm | none | vp9  |
| webm | opus | av1  |
| webm | none | av1  |


---

# Source: /performance-center

---
title: Performance center
description: Automate media performance monitoring and alerts with ImageKit's performance center. Get insights into image and video performance on your website.
---

The performance center in ImageKit automates media performance monitoring and alerts, helping you understand how images and videos impact your website.

With weekly reports, you gain actionable insights into media delivery efficiency and user experience. Automated monitoring helps you identify performance regressions and optimize media delivery for a better user experience.

![Media performance metrics of tracked pages](https://ik.imagekit.io/ikmedia/docs_images/performance-center/list-of-urls.png?tr=w-1600&v=2)

You can view performance metrics for different device types, allowing you to see how images and videos perform for users across various screens.

At a glance, see how different pages perform across:

- **Image optimization**: Evaluates if images are efficiently encoded.
- **Image responsiveness**: Checks if images are resized to suit the layout.
- **Image format modernization**: Indicates if images are served in modern formats (e.g., WebP or AVIF).
- **Video format modernization**: Verifies if videos are served in modern formats (e.g., VP9 or AV1).

Color-coded indicators make it easy to identify pages requiring attention and track performance improvements or declines.

The same summary is available in the weekly performance report, which is sent to your inbox.

![Email performance report;width=400](https://ik.imagekit.io/ikmedia/docs_images/performance-center/email-alert.jpg?v=2)

## Track new pages

To set up performance monitoring, go to the [performance alerts](https://imagekit.io/dashboard/performance-alerts) section and click "Track new URL." Enter the URL and a label for easy identification.

![Performance Alerts](https://ik.imagekit.io/ikmedia/docs_images/performance-center/track-new-page.png?tr=w-1600&v=2)

## Alert subscriptions and recipients

Add multiple email addresses to receive weekly performance reports. Click "Alert preferences" to manage email addresses for report distribution.

![Alert preferences](https://ik.imagekit.io/ikmedia/docs_images/performance-center/alert-preferences.png?tr=w-1600&v=2)

## Historical trends

Analyze historical performance trends with up to 90 days of stored data. This feature empowers you to:

- **Track trends over time**: Gain insights into performance improvements or regressions by analyzing historical data.
- **Identify patterns**: Spot recurring issues or trends that may impact your website’s performance.
- **Pinpoint performance drops**: Determine when and why performance decreases occurred to take timely corrective actions.

The performance dashboard provides a clear view of how your design, UI, or technology updates affect your website’s performance, allowing for data-driven decisions and proactive optimization.

![Historical trends](https://ik.imagekit.io/ikmedia/docs_images/performance-center/historical-trends.png?updatedAt=1732772597547&tr=w-1600&v=2)


---

# Source: /core-delivery-features

---
title: Core Delivery Features
description: Learn about common delivery features in ImageKit.
---

ImageKit is a media CDN that optimizes and transforms images and videos. It lets you deliver any other file type, including JS, CSS, or Fonts, through a global CDN. In addition to [optimizations](/optimize-image-and-video-for-web-delivery) and [transformations](/transformations), ImageKit offers some other standard media delivery features.

* **CDN caching and purging** - ImageKit caches all files on a global CDN and allows you to purge the cache instantly. [Learn more](/cdn-caching-and-purging).
* **SEO-friendly URLs** - ImageKit lets you create SEO-friendly URLs without changing the resource location. [Learn more](/seo-friendly-url).
* **Basic security features** - ImageKit provides basic security features like signed URLs with expiry and limitations on using unnamed transformations. [Learn more](/media-delivery-basic-security).
* **Advanced WAF and DDoS protection** - ImageKit provides advanced WAF and DDoS protection to protect your account from abuse and malicious attacks. [Learn more](/media-delivery-advanced-waf).


## Deliver original file as is - (orig-true)

If you keep the default optimization and compression turned on ImageKit for images and videos, any image or video delivered via ImageKit.io always gets optimized. While this automatic optimization is great for web and apps, there might be certain cases where you want the original file as is. 

You can do so by using the parameter `orig` and setting its value to `true`. If any other transformation parameters are specified along with `orig-true`, then those are ignored.

Example - [https://ik.imagekit.io/ikmedia/tr:orig-true/docs_images/examples/example_food_3.jpg](https://ik.imagekit.io/ikmedia/tr:orig-true/docs_images/examples/example_food_3.jpg)

![](https://ik.imagekit.io/ikmedia/tr:orig-true/docs_images/examples/example_food_3.jpg)

## Create download link - (ik-attachment)

Set `ik-attachment=true` query param in the URL to download the file as an attachment rather than viewing it inline in the web browser.

By specifying this parameter in the file URL, ImageKit sets the `content-disposition` header in the response with the value `attachment` along with the file name.

[Download file](https://ik.imagekit.io/ikmedia/docs_images/examples/example_food_3.jpg?ik-attachment=true)

## Using custom domain name

Let's say your website is loading at `https://www.example.com`. Now, you can configure ImageKit.io to serve your assets via a custom domain, for example, `https://assets.example.com`.

A custom domain only works on ImageKit.io's paid plans. ImageKit handles SSL verification, certificate procurement, certificate deployment, and renewals. Once you are ready, tell us the custom domain you want to configure via support chat or by emailing us at [support@imagekit.io](mailto:support@imagekit.io). Our team will provide you with the next steps.


{% callout style="info" %}
**Automatic SSL certificate procurement** \
Depending on the method of procuring an SSL certificate, you might be informed about certain requirements, like maintaining a DNS entry, to ensure correct certificate renewal.
{% /callout %}

Once the custom domain name is configured, you can fetch files using this domain apart from the ImageKit.io URL endpoint `https://ik.imagekit.io/your_imagekit_id`.

Suppose the old URL was - `https://ik.imagekit.io/your_imagekit_id/rest-of-the-path.jpg`

The new URL would become - `https://assets.example.com/rest-of-the-path.jpg`.

You can optionally associate a custom domain name with a specific [URL endpoint](/integration/connect-external-storage#url-endpoints). This is useful when using a custom domain name for a specific origin.

# Using with your CDN

By default, ImageKit.io offers a global CDN [Amazon CloudFront](https://aws.amazon.com/cloudfront/). This means that not only are your images optimized for size and you can transform them as per your requirements, but you also get a superfast delivery network with ImageKit.io that helps deliver images to your end users in milliseconds. You can use ImageKit.io's integrated CDN to deliver not only images but also JS/CSS/fonts or any other static asset.

However, you can integrate ImageKit.io with your CDN as well. This could be useful if you are in a long-term contract with any existing CDN vendor.

{% callout style="info" %}
**Custom Enterprise Paid plan feature** \
This setup is only available for enterprise plan users and requires a minimum billing. If you want to use ImageKit.io with your CDN, please contact the support team.
{% /callout %}

{% callout style="warning" %}
**Feature support on custom CDNs with ImageKit** \
Not all features will work with a custom CDN. This is mostly because of limitations in the CDN and how they don't work with how ImageKit automatically optimizes or transforms media assets. Additionally, ImageKit cannot deliver detailed usage analytics when a custom CDN is used.
{% /callout %}

### Supported CDNs

We have integrated and tested ImageKit.io with the following CDNs so far:

✅  Akamai \
✅  Azure \
✅  Alibaba Cloud CDN \
✅  CloudFlare (only on Enterprise plan in CloudFlare) \
✅  CloudFront \
✅  Fastly \
✅  Google CDN \
✅  Zenedge

### Features availability

| Feature                          | Available |
| -------------------------------- | --------- |
| Image transformation             | Yes       |
| Automatic image optimization     | Yes       |
| Automatic format conversion      | Yes       |
| Network-based media optimization | Yes       |
| Data Saver                       | No        |
| Security                         | Yes       |

### Integration steps for custom CDN

1. Write to us at [support@imagekit.io](mailto:support@imagekit.io) or contact your Customer Success Manager.
2. Our team will work with you to make the necessary configuration changes in your CDN to support optimization and transformation features. Depending on your CDN, certain features might not be available at all. Our team will also inform you about that.
3. Test the configuration of your CDN and go live.


---

# Source: /cdn-caching-and-purging

---
title: CDN caching and purging
description: Learn how ImageKit uses CDN caching to deliver your media and other files faster and how to purge the cache to update resources.
---

ImageKit uses [Amazon CloudFront](https://aws.amazon.com/cloudfront/) CDN to deliver your media and other files faster. When you request a file from ImageKit, it is served from the nearest CDN edge server to your location, ensuring that your files are delivered quickly.

![CDN edge location and ImageKit processing servers](<https://ik.imagekit.io/ikmedia/Graphics/2024%20Website%20Graphics/Media%20Processing/Securely%20deliver%20your%20assets%20globally.jpg?updatedAt=17140493735811&tr=w-1250>)

Behind the global CDN, ImageKit has processing servers in 7 AWS regions. You can select the processing region during account setup. The processing region is where your files are stored and processed. When a file is requested from ImageKit, it is cached on the CDN edge server for a certain period. This is known as CDN caching. The cached file is then served to subsequent requests for the same file without having to go back to the ImageKit server.

## Default caching behavior

By default, ImageKit caches all files on the global CDN for a maximum time of 1 year. This means once a file is requested from ImageKit, it is cached on the CDN edge server for up to 1 year. Note that this is the maximum time a file can be cached on the CDN. The CDN can evict non-popular files from the cache before the one-year period. 

After the maximum cache time elapses, the file is removed from the CDN cache, and the subsequent request for the file will fetch the file from the ImageKit server.

ImageKit sets the standard [Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) headers on the response. For example, the following Cache-Control header is set on the response for a file:

```
Cache-Control: public, s-maxage=31536000, max-age=31536000, must-revalidate
```

* `s-maxage=31536000, max-age=31536000` indicates the CDN and the browser to cache the resource for 1 year. We have tested this across different browsers to ensure that caching works as expected.
* `must-revalidate` response directive indicates that the response can be stored in caches and can be reused while [fresh](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching#etagif-none-match). If the response becomes stale, it must be revalidated with the origin server before reuse. ImageKit sets the `ETag` header on the response to enable revalidation.

{% callout style="info" %}
Please note that revalidation of sub-resources, i.e., images, videos, JS, and CSS files in a webpage, became pretty efficient in Chrome after [this change](https://blog.chromium.org/2017/01/reload-reloaded-faster-and-leaner-page_26.html). Now, when you do a normal reload in Chrome, it only revalidates the main HTML document and skip revalidation of subresources to leverage browser cache efficiently. You can read more about it on Facebook's [blog post](https://engineering.fb.com/2017/01/26/web/this-browser-tweak-saved-60-of-requests-to-facebook/?utm_source=codedot_rss_feed). Learn more about [static assets caching](https://imagekit.io/blog/ultimate-guide-to-http-caching-for-static-assets/) from our blog.
{% /callout %}

In Chrome, you can load a page and see the network tab in the developer tools to see how the browser is caching the resources. Please uncheck the "Disable cache" checkbox in the network tab to see the caching behavior. Also, if you issue a hard refresh (Ctrl + F5) in the browser, the browser will ignore the cache and fetch the resources from the server. In that case, you will see a `200` status code in the network tab.

![Loading from cache](https://ik.imagekit.io/ikmedia/docs_images/features/cache-purging/caching-example.png?tr=w-1600)

## Internal caches in ImageKit

Besides CDN caching, ImageKit also caches the transformed images & videos to improve performance in an internal cache. Video transformations are cached permanently on ImageKit's end, while the duration of stored image transformation is limited.

If you encounter slow response times for your requests, please [refer to this documentation](/integration/connect-external-storage#debugging-slow-origin-response). 

You can also opt for the [save a copy of assets on demand](/integration/connect-external-storage#save-copy-of-assets-on-demand) feature. If enabled, ImageKit will start caching the original files too.

When you [purge the cache](#purging-the-cache), ImageKit removes the cached resource from the CDN, all internal caches, and the original asset caches. This ensures that the subsequent request for the same resource fetches the latest version.

### Controlling intermediate cache TTL (ik-cacheTime)

The `ik-cacheTime` query parameter lets you control how long a transformed image is stored in ImageKit's intermediate cache. After this specified period, the cached transformation is removed, and the next request for that transformation will regenerate and cache it again.

Usage of this feature is restricted to [signed URLs](/media-delivery-basic-security#how-to-generate-signed-urls) only. To use the feature, add the `ik-cacheTime` query parameter to your image URL with the desired TTL value in days, and sign it.

**Example:**

```
https://ik.imagekit.io/your_imagekit_id/image.jpg?ik-cacheTime=7&ik-s=<signature>
```

This caches the transformed image in the intermediate cache for 7 days.

**Allowed values:**

| Value | Description                                              |
| ----- | -------------------------------------------------------- |
| 0     | No intermediate cache is created for the transformation  |
| 1     | Cache for 1 day                                          |
| 3     | Cache for 3 days                                         |
| 7     | Cache for 7 days                                         |
| 15    | Cache for 15 days                                        |
| 30    | Cache for 30 days                                        |
| 60    | Cache for 60 days                                        |

{% callout style="info" %}
**Enterprise plan feature** \
The `ik-cacheTime` parameter is only available on enterprise plans. Contact us at [support@imagekit.io](mailto:support@imagekit.io) to get this feature enabled for your account.
{% /callout %}

{% callout style="warning" %}
**Scope** \
The `ik-cacheTime` parameter only affects images and only controls the TTL of the internal intermediate cache. It does not affect CDN caching behavior.
{% /callout %}

## Advanced caching configuration

When using ImageKit with [external storages](/integration/connect-external-storage), you can configure the caching duration for each resource. This method **does not** work if you store files in the ImageKit Media Library.

You can configure ImageKit to respect the `Cache-control` response header sent by the origin at a [URL-endpoint](/integration/connect-external-storage#url-endpoints) level. You can set the `Cache-control` header in object storage using the UI or programmatically. Learn more from [S3](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Expiration.html#ExpirationAddingHeadersInS3), [GCS](https://cloud.google.com/storage/docs/caching#built-in_caching_for), or [Azure](https://learn.microsoft.com/en-us/azure/cdn/cdn-manage-expiration-of-blob-content) documentation. We only pick timing from the `max-age` directive in the `Cache-control` header. 

For example, suppose your external storage sends a Cache-Control header to cache a file for 1 hour, i.e., `public, max-age=3600`. In that case, ImageKit.io applies the cache-control header across all its internal caches, generated transformations, and CDN. This ensures that the cache control you set is obeyed at all times.

If the max-age directive is missing from the origin, ImageKit caches the file for the default cache time.

{% callout style="info" %}
**Notes**

1. Origin-based cache control is turned off by default. Contact us at [support@imagekit](mailto:support@imagekit.io) to enable it for your account.
2. This feature can be applied to any [URL endpoint](/integration/connect-external-storage#url-endpoints) in your ImageKit.io account.
3. This method does not work if you store files in the ImageKit Media Library.
4. We do not recommend using a lower cache duration than the default 1 year for all assets. This can lead to degraded performance and increased bandwidth costs. You should do it only for assets where you absolutely need a lower cache time. 
{% /callout %}

## Purging the cache

You can purge the content from CDN and ImageKit intermediate cache by using the [purge cache API](/api-reference/caching/purge-cache) or from the [dashboard](https://imagekit.io/dashboard/purge-cache).

![Purge cache from ImageKit dashboard](<https://ik.imagekit.io/ikmedia/docs_images/features/cache-purging/purge-cache-from-imagekit-dashboard_n6QaNEcYF.png?tr=w-1600>)

## Purging multiple files

You can purge the cache for multiple files within a directory by appending a wildcard at the end of the URL only if **ANY ONE** of the following conditions are met:

1. The path consists of at least two levels of nesting: \
 The path of the directory, excluding your imagekitId and URL pattern, contains at least two levels of nesting, starting from the root as shown below: \
 ✅ `https://ik.imagekit.io/IMAGEKIT_ID/PATTERN/LEVEL_1/LEVEL_2*` \
 ❌ `https://ik.imagekit.io/IMAGEKIT_ID/PATTERN/LEVEL_1*`
   
 For example, the path `/images/upload*` is valid, but `/images*` is not.

2. The path length is at least 15 characters: \
 The path of the directory, excluding your imagekitId and URL pattern, is at least 15 characters in length, as shown below: \
 ✅ `https://ik.imagekit.io/IMAGEKIT_ID/PATTERN/FIFTEEN_CHARACTERS*`
   
 However, if the first condition is met, i.e., the path consists of at least two levels of nesting, then it need not be 15 characters long.

3. The path is a complete file path: \
 The path specified is a complete path pointing to a file, with the file extension present at the end of the path, as shown below: \
 ✅ `https://ik.imagekit.io/IMAGEKIT_ID/PATTERN/FILE.EXT*`
   
 For example, the path `/sample.jpg*` is valid despite not being 15 characters long or having two levels of nesting.

{% callout style="alert" %}
The following paths are unconditionally not supported when using a wildcard. Please contact us at support@imagekit.io if you need to purge the following patterns.
* `media/catalog/*`
* `s/files/*`
{% /callout %}

## Cache purge limitations

Purge has the following limitations:

* Based on your pricing plan, you can purge a limited number of URLs per month. After that, each cache purge request is charged as per your [pricing plan](https://imagekit.io/plans).
* Note that the wildcard can only be appended at the end of a URL. Wildcards within the path are not supported. i.e., `/folder/*/sample.jpg` is an invalid path. Please reach out to us at [support@imagekit.io](mailto:support@imagekit.io) if you need to purge all images on a specific pattern not supported through the API.

## Working with custom CDN

When using ImageKit behind your CDN, you must purge the cache on both ImageKit and your CDN in specific order to ensure that the resource is updated. With custom CDN integration, you probably use [custom domain name](/docs/core-delivery-features#using-custom-domain-name) integration and have mapped custom domains with ImageKit's URL endpoint.

Follow the steps to update a resource:

1. First, update the resource on your origin server.
2. Purge cache from ImageKit.
3. Verify that the resource is updated on ImageKit. Fetch the resource using the ImageKit URL endpoint to ensure that the resource is updated.
4. Once you have verified that the resource is updated on ImageKit, purge the cache on your CDN. This ensures that the resource is updated on your CDN as well.

## Best practices

We suggest you follow these best practices to ensure optimal performance and cost-effectiveness:

1. Do not rely on cache purging as a primary method to update resources. Instead, use versioning or query parameters to update resources. For example, you can use `https://ik.imagekit.io/IMAGEKIT_ID/resource.jpg?v=2` and update the value of `v` query parameters to update the resource. Never add a value that changes on every request. When the query parameter updates, it is like a new URL for the browser or the app, and therefore it fetches the new resource from the server. This guarantees that your users always get the latest version of the resource.
2. Check your cache hit ratio in the ImageKit dashboard [analytics](/usage-analytics) to understand how effectively your resources are being cached. A high cache hit ratio above 80% indicates that your resources are being served from the cache with optimal performance.
3. Add transformation parameters in the query instead of path to allow for wildcard invalidation of all resources. For example, you can purge `https://ik.imagekit.io/your_imagekit_id/resource.jpg/*` to purge all transformations of `resource.jpg`. If you use transformations in the path, you must purge each transformation individually.


---

# Source: /seo-friendly-url

---
title: SEO-friendly URLs with dynamic suffixes
description: Make your URL SEO-friendly without changing the underlying file's name with dynamic SEO suffixes in ImageKit.
---

SEO starts with the file name. Google uses the URL path and the file name to understand your images and videos.

For example, consider the following image of the Eiffel Tower.

![Eiffel Tower](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/Eiffel Tower.jpg?tr=w-1600>)

The image URL ideally should have "Eiffel Tower" in the file name. This is more SEO-friendly than a generic file name, e.g., `DSC1234.jpg`.

{% callout style="alert" %}
**Bad image URL** \
https://ik.imagekit.io/demo/DSC1234.jpg
{% /callout %}

{% callout style="success" %}
**SEO-friendly image URL** \
https://ik.imagekit.io/demo/eiffel-tower.jpg
{% /callout %}

## Dynamic SEO suffix (ik-seo)

When you cannot modify the file names of already stored images, ImageKit helps you create dynamic SEO-friendly URLs.

For example, let say you have the following image of the Eiffel Tower.

```
https://ik.imagekit.io/demo/DSC1234.jpg
```

Here, `https://ik.imagekit.io/demo/` is your [URL endpoint](/integration/connect-external-storage#url-endpoints).

You can dynamically use **eiffel-tower.jpg** as the file name using `ik-seo` parameter. For example:

```
https://ik.imagekit.io/demo/ik-seo/DSC1234/eiffel-tower.jpg
```

So the following URL:

https://ik.imagekit.io/demo/`ik-seo`/DSC1234/eiffel-tower.jpg

will fetch the same image as:

https://ik.imagekit.io/demo/DSC1234.jpg

Essentially

your-url-endpoint/old-file-name.extension

becomes:

your_url_endpoint/**`ik-seo`**/old-file-name/**`seo-friendly-file-name`**.extension

### Accessing file that is stored in a nested folder

If your file is stored inside a nested folder e.g.

`https://ik.imagekit.io/demo/path/of/folder/old-file-name.jpg`

You can still dynamically add an SEO-friendly suffix like this:

`https://ik.imagekit.io/demo/ik-seo/path/of/folder/old-file-name/seo-friendly-file-name.jpg`

## Examples

Let's say we have the following URL:

`https://ik.imagekit.io/your_imagekit_id/default-image.jpg`

We want to change the file name from `default-image.jpg` to `seo-friendly-file-name.jpg`

So the new URL becomes

`https://ik.imagekit.io/your_imagekit_id/ik-seo/default-image/seo-friendly-file-name.jpg`

Let's do this using the client-side SDKs.

{% linetabs %}
{% linetab title="Javascript" %}
```javascript
// Without ik-seo
var imageURL = imagekit.url({
    path: "/default-image.jpg",
    urlEndpoint: "https://ik.imagekit.io/your_imagekit_id/",
    transformation: [{
        height: 300,
        width: 400
    }]
});

// With ik-seo
var imageURL = imagekit.url({
    path: "/default-image/seo-friendly-file-name.jpg",
    urlEndpoint: "https://ik.imagekit.io/your_imagekit_id/ik-seo",
    transformation: [{
        height: 300,
        width: 400
    }]
});
```
{% /linetab %}

{% linetab title="React" %}
```javascript
// Without ik-seo, urlEndpoint has been defined in parent IKContext 
<IKImage
  path="/default-image.jpg"
  transformation={[{
    height: 300,
    width: 400
  }]}
/>
  
// With ik-seo
<IKImage
  urlEndpoint="https://ik.imagekit.io/your_imagekit_id/ik-seo"
  path="/default-image/seo-friendly-file-name.jpg"
  transformation={[{
    height: 300,
    width: 400
  }]}
/>
```
{% /linetab %}

{% linetab title="Vue.js" %}
```javascript
// Without ik-seo, urlEndpoint has been defined globally 
<ik-image 
  path="/default-image.jpg"
  :transformation="[{height:300,width:400}]"
/>


// With ik-seo
<ik-image 
  path="/default-image/seo-friendly-file-name.jpg"
  :transformation="[{height:300,width:400}]"
  urlEndpoint="https://ik.imagekit.io/your_imagekit_id/ik-seo"
/>
```
{% /linetab %}
{% /linetabs %}


---

# Source: /media-delivery-basic-security

---
title: Basic security features
description: Prevent unauthorized access and modification of your media assets with security features like signed URLs, named transformations, and private files.
---

ImageKit provides some security features for media delivery on all pricing plans, including free plans. These features help you prevent unauthorized access and modification of your media assets. However, to prevent hotlinking and advanced restrictions based on HTTP referrer, IP, country, etc., you should use [advanced security features](/media-delivery-advanced-waf) available on the enterprise plan.

In this guide, we will cover the following basic security features:

- [Restrict unsigned URLs](#restrict-unsigned-urls)
- [Restrict unnamed transformations](#restrict-unnamed-transformations)
- [Private files](#private-files)
- [SVG Sanitization](#svg-sanitization)

## Restrict unsigned URLs

Signed URLs have a signature that is generated using your [private API key](/api-keys) and the URL. This signature is then appended to the URL as a query parameter. When the URL is requested, ImageKit verifies the signature to ensure that the URL has not been tampered with. Besides signature verification, you can optionally specify the expiration time for the signed URL. After the expiry time, the signed URL will no longer be valid. This allows you to:

* Enforce time-bound access to your media assets. After the expiration time, the signed URL will no longer be valid.
* Prevent unauthorized modification of the URL. For example, you are using [image overlay](/add-overlays-on-images) to add a watermark to protect the artwork. If the signed URL is tampered with to remove the watermark transformation, ImageKit will not serve the image.

You can restrict access to your media assets by enforcing signed URLs from the dashboard independently for [images](https://imagekit.io/dashboard/settings/images) and [videos](https://imagekit.io/dashboard/settings/videos).

You have three options to enforce signed URLs:

* Do not restrict - ImageKit will serve the media assets even if the URL has no valid signature.
* Restrict only AI transformation requests - ImageKit will serve the media assets if the URL does not have a valid signature, except for AI transformation requests that consumes extension units. This is recommended if you use [AI transformations](/ai-transformations) to prevent unauthorized consumption of extension units on your account.
* Restrict all requests - ImageKit will only serve the media assets if the URL has a valid signature. If the URL does not have a valid signature, ImageKit will return a `401 Unauthorized` status code.

When signed URLs are enforced, ImageKit will only serve the media assets if the URL has a valid signature. When signed URLs are not enforced, ImageKit will serve the media assets even if the URL does not have a valid signature.

![Restrict unsigned image URLs](https://ik.imagekit.io/ikmedia/docs_images/features/security/restrict-unsigned-urls.png?updatedAt=1723186280370?tr=w-1600)

{% callout style="info" %}
**Note:** Signed URLs are not enforced by default. You need to enable this feature from the dashboard. This feature only works for images and videos. For any other resource type, you need to [mark the file as private](#private-files).
{% /callout %}

## How to generate signed URLs

A signed URL has a `ik-s` query parameter that contains the signature. The signature is generated using your [private API key](/api-keys) and the URL. Besides the signature, you can optionally specify the expiry time using the `ik-t` query parameter.

A typical signed URL looks like this:


```
                                              signature
                              ┌──────────────────────────────────────┐
{url-endpoint}/image.jpg?ik-s=e26ca157df99b30b2443d7cb6886fc396fb4c87b&ik-t=9999999999
                                                                            └────┬───┘
                                                                            expiry time
```

* **signature** - `ik-s` query parameter contains the signature generated using your private key and the URL. ImageKit uses this signature to verify the authenticity of the URL. If the signature is invalid, ImageKit will return the `401 Unauthorized` status code when the restricted unsigned URL setting is enabled.
* **expiry time** - This is optional. The `ik-t` query parameter contains the expiry time, which is the number of seconds after epoch time (UTC) when the signed URL will expire. After this time, the signed URL will no longer be valid. ImageKit will return a `401 Unauthorized` status code if the signed URL is accessed after the expiry time.

Here is [this pseudo code](#pseudo-code-to-generate-signed-url) to generate signed URLs. To simplify things, we have added utility methods in all our [server-side SDKs](/quick-start-guides#back-end) to generate signed URLs. The SDKs handle edge cases like URL encoding for you.

{% linetabs %}
{% linetab title="Node.js" %}
```js
import ImageKit from '@imagekit/nodejs';

const client = new ImageKit({
    privateKey: "your_private_key"
});

const imageURL = client.helper.buildSrc({
    urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
    src: "/default-image.jpg",
    queryParameters: {
        "v": "123"
    },
    transformation: [{
        "height": 300,
        "width": 400
    }],
    signed: true,
    expiresIn: 300
});
```
{% /linetab %}

{% linetab title="Go" %}
```go
import (
	"github.com/imagekit-developer/imagekit-go/v2"
	"github.com/imagekit-developer/imagekit-go/v2/option"
	"github.com/imagekit-developer/imagekit-go/v2/packages/param"
	"github.com/imagekit-developer/imagekit-go/v2/shared"
)

client := imagekit.NewClient(
	option.WithPrivateKey("your_private_key"),
)

imageURL := client.Helper.BuildURL(shared.SrcOptionsParam{
	URLEndpoint: "https://ik.imagekit.io/your_imagekit_id",
	Src:         "/default-image.jpg",
	QueryParameters: map[string]string{
		"v": "123",
	},
	Transformation: []shared.TransformationParam{
		{
			Height: shared.TransformationHeightUnionParam{
				OfFloat: param.Opt[float64]{Value: 300},
			},
			Width: shared.TransformationWidthUnionParam{
				OfFloat: param.Opt[float64]{Value: 400},
			},
		},
	},
	Signed:    param.Opt[bool]{Value: true},
	ExpiresIn: param.Opt[float64]{Value: 300},
})
```
{% /linetab %}

{% linetab title="Python" %}
```python
import os
from imagekitio import ImageKit

imagekit = ImageKit(
    private_key=os.environ.get("IMAGEKIT_PRIVATE_KEY"),
)

image_url = imagekit.helper.build_url(
    url_endpoint="https://ik.imagekit.io/your_imagekit_id",
    src="/default-image.jpg",
    query_parameters={"v": "123"},
    transformation=[{
        "height": 300,
        "width": 400
    }],
    signed=True,
    expires_in=300
)
print(image_url)
```
{% /linetab %}

{% linetab title="PHP" %}
```PHP
$imageURL = $imageKit->url(array(
    "path" => "/default-image.jpg",
    "queryParameters" => array(
        "v" => "123",
    ),
    "transformation" => array(
        array(
            "height" => "300",
            "width" => "400"
        ),
    ),
    "signed" => true,
    "expireSeconds" => 300,
));
```
{% /linetab %}

{% linetab title="Java" %}
```java
import io.imagekit.client.ImageKitClient;
import io.imagekit.client.okhttp.ImageKitOkHttpClient;
import io.imagekit.models.SrcOptions;
import io.imagekit.models.Transformation;

ImageKitClient client = ImageKitOkHttpClient.builder()
    .privateKey("your_private_key")
    .build();

String imageURL = client.helper().buildUrl(
    SrcOptions.builder()
        .urlEndpoint("https://ik.imagekit.io/your_imagekit_id")
        .src("/default-image.jpg")
        .addTransformation(
            Transformation.builder()
                .height(300.0)
                .width(400.0)
                .build()
        )
        .signed(true)
        .expiresIn(300.0)
        .build()
);
System.out.println(imageURL);
```
{% /linetab %}

{% linetab title="Ruby" %}
```ruby
require "imagekitio"

client = Imagekitio::Client.new(
  private_key: ENV["IMAGEKIT_PRIVATE_KEY"]
)

image_url = client.helper.build_url(
  url_endpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/default-image.jpg",
  query_parameters: {
    v: "123"
  },
  transformation: [{
    height: 300,
    width: 400
  }],
  signed: true,
  expires_in: 300
)
puts image_url
```

{% /linetab %}

{% linetab title=".Net" %}
```csharp
using Imagekit;
using Imagekit.Models;

ImageKitClient client = new() { PrivateKey = "your_private_key" };

var imageURL = client.Helper.BuildUrl(new SrcOptions
{
    UrlEndpoint = "https://ik.imagekit.io/your_imagekit_id",
    Src = "/default-image.jpg",
    QueryParameters = new Dictionary<string, string>
    {
        ["v"] = "123",
    },
    Transformation =
    [
        new() { Height = 300, Width = 400 }
    ],
    Signed = true,
    ExpiresIn = 300,
});
```

{% /linetab %}
{% /linetabs %}

### Pseudo code to generate signed URL

To generate the signed URL yourself, refer to the pseudo-code below.

{% callout style="info" %}
The value of the signature `ik-s` should be lowercase.
{% /callout %}

```js
// Assume we have an image URL
var imageUrl = "https://ik.imagekit.io/your_imagekit_id/tr:w-400:rotate-91/sample/testing-file.jpg";

// This is our endpoint
var urlEndpoint = "https://ik.imagekit.io/your_imagekit_id";

// Make sure urlEndpoint has a trailing slash (/)
if(urlEndpoint[urlEndpoint.length - 1] != "/") {
    urlEndpoint = urlEndpoint + "/"
}

// Let's say we want to expire image in 300 seconds, so expireTimestamp (UTC timestamp) would be
var expiryTimestamp = parseInt(new Date().getTime() / 1000, 10) + 300;

// Remove the urlEndpoint from image URL
var str = imageUrl.replace(urlEndpoint,"");
// str will be tr:w-400:rotate-91/sample/testing-file.jpg

// Append the expiryTimestamp in above str
str = str + expiryTimestamp
// str will be tr:w-400:rotate-91/sample/testing-file.jpg9999999999

// Calcualte the signature using your priviate key 
var signature = crypto.createHmac('sha1', "your_private_key").update(str).digest('hex');

// Add ik-t and ik-s query parameters in the url
var finalImageUrl = imageUrl + "?ik-t=" + expiryTimestamp + "&ik-s=" + signature;
```

Most browser engines encode special characters, diacritics, or characters from different charsets to [UTF-8](https://developer.mozilla.org/en-US/docs/Glossary/UTF-8). For example, `é` (diacritic) is encoded as `e%CC%81`, and so on.

{% callout style="info" %}
To ensure that your signed URLs that contain such characters work, you must encode the complete URL of the input image before signing it. For example, instead of using `/default-image-with-é.jpg` as the input path for the signed URL, use `/default-image-with-e%CC%81.jpg`. The backend SDKs handle this encoding for you.
{% /callout %}

## Restrict unnamed transformations

Transformation allows you to resize, crop, rotate, and apply various effects to your images and videos. Transformations are ultimately a few URL parameters that you append to the URL of the media asset. For example, to resize an image to 300x400, you can append `tr:w-300,h-400` to the URL.

To prevent unauthorized manipulation of your media assets, you can create [named transformations](/transformations#named-transformations) in the dashboard and enforce restrictions on the usage of unnamed transformations. When you enforce this setting, ImageKit will only serve the media asset if the transformation is named. If the transformation is not named, ImageKit will return a `400: Bad Request` status code.

You can turn on this setting separately for [images](https://imagekit.io/dashboard/settings/images) and [videos](https://imagekit.io/dashboard/settings/videos) from the dashboard.

![Restrict unnamed image transformations](https://ik.imagekit.io/ikmedia/docs_images/features/security/restrict-unnamed-image-transformation-setting-in-imagekitio-dashboard_mQrdlrYpsi.png?tr=w-1600)

## Private files

If you do not want to restrict unsigned URLs on all your media assets but still want to prevent unauthorized access to some of them, you can mark them as private. When a resource is private, it can only be accessed using a [valid signed URL](#how-to-generate-signed-urls) or using a valid [named transformation](/transformations#named-transformations). This is useful when you want to share media assets with only authenticated users or after a certain event, like payment completion.

Here is how to mark a resource as private:

- **ImageKit Media Library** - You can mark a file as private during upload from the dashboard or through upload API (`isPrivateFile` property). Once a file is marked private, its status cannot be changed. To unmark a file as private, re-upload the file with the same name as the one marked private.
- **Amazon Simple Storage Service (S3)** - If you are delivering files from your [S3 bucket](/integration/aws-s3) added as an external storage, set the object metadata `x-amz-meta-isprivatefile` as `true` to mark the file as private. This [documentation from AWS](https://docs.aws.amazon.com/AmazonS3/latest/userguide/add-object-metadata.html) provides an overview of adding metadata to an object within S3.
- **Google Cloud Storage (GCS)** - If you are delivering files from your [GCS bucket](/integration/google-cloud-storage) added as an external storage, set an object metadata `isprivatefile` as `true` to mark the file as private. This [documentation from GCS](https://cloud.google.com/storage/docs/metadata) provides an overview of adding metadata to an object within Google Cloud Storage.
- **HTTP server/Web server** - If you are delivering files from an [HTTP server](/integration/web-server) added as an external storage, add a response header `Is-Private-File: true`. When ImageKit sees this header, it will consider the file as private.


## SVG Sanitization

You can sanitize your SVG files to remove any potentially harmful content from them before delivering the file. Add the `ik-sanitizeSvg=true` query parameter to your URL to achieve this. It is especially useful when handling SVG files originating from untrusted sources. This operation will strip the SVG file of all `<script>` elements, `onload` and `onerror` attributes, and other parts of SVG markup that can be harmful.

Here's both the unsanitized and sanitized versions of some sample SVG markup:

```xml
// Unsanitized SVG
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="200"
    height="200">
    <path fill="#add8e6" stroke="#00f" stroke-width="2" d="M10 10h180v180H10z" />
    <circle cx="100" cy="100" r="50" fill="#ff0" />
    <script>alert(&apos;This script will be removed&apos;);</script>
    <a xlink:href="javascript:alert('This XSS attack will be removed')">
        <text x="50" y="50" font-family="Arial" font-size="16">Click me (unsafe link)</text>
    </a>
    <path fill="red" d="M50 120h100v30H50z" onmouseover="alert('This event handler will be removed')" />
    <path fill="red" d="M10 10h100v50H10z"
        onmouseover="javascript:alert('This XSS attach via onmouseover event will be removed');" />
    <a xlink:href="javascript:alert('This XSS attach via javascript: URL will be removed');">
        <text x="10" y="90" fill="#00f" font-size="20">
            Click me (JavaScript link)
        </text>
    </a>
    <foreignObject width="200" height="80" x="10" y="110">
        <body xmlns="http://www.w3.org/1999/xhtml">
            <p style="color:green">This ForeignObject content will be removed</p>
            <script>alert(&apos;XSS via foreignObject embedded HTML!&apos;);</script>
        </body>
    </foreignObject>
    <text x="60" y="100" fill="#000" font-family="Arial" font-size="12">Safe Text Content</text>
</svg>

// Sanitized SVG
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="200"
  height="200">
  <path fill="#add8e6" stroke="#00f" stroke-width="2" d="M10 10h180v180H10z" />
  <circle cx="100" cy="100" r="50" fill="#ff0" />
  <a>
    <text x="50" y="50" font-family="Arial" font-size="16">Click me (unsafe link)</text>
  </a>
  <path fill="red" d="M50 120h100v30H50z" />
  <path fill="red" d="M10 10h100v50H10z" />
  <a>
    <text x="10" y="90" fill="#00f" font-size="20">
      Click me (JavaScript link)
    </text>
  </a>
  <text x="60" y="100" fill="#000" font-family="Arial" font-size="12">Safe Text Content</text>
</svg>
```


---

# Source: /media-delivery-advanced-waf

---
title: Advanced Web Application Firewall
description: Learn about how to prevent hotlinking based on referrer, block IPs, and more using ImageKit's advanced security settings.
---

{% callout style="info" %}
**Enterprise plan only** \
This feature is only available in custom enterprise pricing plans.
{% /callout %}

Besides [basic security](/media-delivery-basic-security) features, ImageKit provides advanced security settings to prevent hotlinking based on referrer, block IPs, and more. These settings give you more control over who can access your assets.

The advanced security settings include the following features:

1. IP and IP range blocking.
2. Optimized asset delivery based on user agents. This is needed for delivering WebP or AVIF images on mobile applications as they don't follow standard Content Negotiation conventions based on the `Accept` header value.
3. Geographic restriction.
4. HTTP Referrer-based restriction.
5. User Agent-based restriction.
6. Improved caching of assets.


![Advanced security settings in ImageKit's dashboard](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/advanced-security-settings.png?tr=w-1600>)

## How to configure?

If your plan includes this feature, please get in touch with us at [support@imagekit.io](mailto:support@imagekit.io) to set it up for your account. Once enabled and configured, you can use this feature from your ImageKit account's dashboard.

## IP and IP range blocking

{% callout style="info" %}
**Limits**
- You can block at most 100 absolute IPs or IP ranges.
- Only IPv4 blocking is supported.
{% /callout %}

This feature blocks absolute IPs or IP ranges from accessing content. Any request from these unauthorized IPs would result in an HTTP `403` error response, and the asset will not be delivered.

To block IPs, you need to provide a list of valid absolute IPv4 addresses or IPv4 ranges in CIDR notation separated by a new line in the input - using the advanced security settings in the dashboard.

Examples of valid input- 
- Absolute IPv4 - `163.120.4.15`.
- IPv4 range using CIDR notation - `10.0.0.0/24`. This blocks all IPs in range `10.0.0.0` to `10.0.0.255`.

## Optimized asset delivery based on user agents

{% callout style="info" %}
**Limits**
- You can configure at most 10 user agents for WebP/AVIF image delivery.
{% /callout %}

Mobile apps often do not automatically request the most optimized image format using the Accept header. This setting allows you to force the delivery of WebP or AVIF formats to specific mobile user agents, ensuring high performance without requiring changes to your app's networking code.

To configure this setting for your requests, go to the advanced security settings on the dashboard to provide a list of user agents, each separated by a new line.

These user agents do not have to be exactly the same as the user agent header sent in the request. If the user agent in your request has any of the defined user agents as a substring, ImageKit will send the optimized asset. User-agent match is case-insensitive.

For requests with one of the configured user agents, you can select the accept header from the options in the drop-down menu. This helps in the detection of the format of the asset to be delivered as well as in caching.

For example:
- If you configure the user agent `Android 11` and accept headers for the configured user agents `image/webp,image/apng,*/*;q=0.8`, for a request having the user agent header `Linux; U; Android 11`, ImageKit would deliver a WebP image.

> Note: Even if the Accept header set with this setting contains `image/avif`, an image will be automatically converted to AVIF only when you have automatic AVIF format conversion turned on for your account. You can check the status of this feature from the [Image settings section](https://imagekit.io/dashboard/settings/images).

## Geographic restriction

ImageKit provides geographic restriction that allows you to restrict access to assets at the country level.

There are three options for geographic restriction-

- Blocklist
- Allowlist
- No restriction

By default, no geographic restrictions are applied.

## HTTP Referrer-based restriction

{% callout style="info" %}
**Limits**

You can allow or block at most 30 referrers.
{% /callout %}

The `Referer` HTTP request header contains the absolute or partial address of the page that makes the request. It allows a server to identify a page from which people are requesting the resource.

Referrer-based restriction ensures that content only loads on requests from authorized domains. Any unauthorized request will result in an HTTP `403` error, and the asset will not be delivered.

ImageKit provides three options for Referrer-based restriction-

- Blocklist 
- Allowlist
- No restriction

To block or allow domains, you need to provide a list of valid URLs (Each URL must include at least the scheme and domain name) separated by a new line. The exact domain mentioned in the URLs would be allowed or blocked.

For example:
- If you add `https://ik.imagekit.io` to the allowlist, the URL `ik.imagekit.io` will be allowed.
- If you add `https://developer.mozilla.org/en-US/search?q=URL` to the blocklist, the domain `developer.mozilla.org` will be restricted.

**Note:** Wildcard domain restrictions such as `*.example.com` are not supported at this time.

### Uses
The blocklist will block domains that are hotlinking your content or assets, increasing bandwidth usage and hosting costs. If your assets are undesirably hotlinked on other websites, the blocklist can save you significant costs.

The allowlist allows only selected domains to access your assets. For example, you can use it to serve content only on your allowed domains and automatically block other referrers.

If you do not want any HTTP Referrer-based restriction, you can opt for no restriction, which is the default behavior.

## User Agent-based restriction

{% callout style="info" %}
**Limits**
- You can configure 10 user agents to block at most.
{% /callout %}

This feature blocks user agents from accessing content. Any request with a blocked user agent will result in an HTTP `403` error, and the asset will not be delivered.

To configure this setting for your requests, go to the advanced security settings on the dashboard to provide a list of user agents, each separated by a new line.

These user agents do not have to be exactly the same as the user agent header sent in the request. If the user agent in your request has any of the defined user agents as a substring, ImageKit will block the request. User-agent match is case-insensitive.

For example:
- If you configure the user agent `Bytespider` for a request with the user agent header `Linux; U; Bytespider/3.0`, ImageKit will block the request.


---

# Source: /video-player/overview

---
title: Video player
description: Learn how to use ImageKit's advanced video player with enhanced features including playlists, recommendations, shoppable videos, and more.
---

ImageKit's video player is an advanced video player built on top of [Video.js 8.20.0](https://videojs.org/guides) delivering enhanced features for a seamless, interactive video experience. It's fully integrated with ImageKit's video delivery and transformation solution.

Source code is available on [GitHub](https://github.com/imagekit-developer/imagekit-video-player).

{% callout style="warning" %}
**Beta Release** \
ImageKit Video Player is currently in beta. It is actively evolving with new features and improvements—please test thoroughly before using it in production.
{% /callout %}

## Key features

- **Video transformations**: Apply [ImageKit video transformations](/video-transformation) at the player level that will apply to all videos delivered in that player. Apply additional or override video transformations at the per-video level.
- **Adaptive bitrate streaming**: Full support for HLS and MPEG-DASH including automatic generation of all required streaming representations and supporting files. Learn more about ABS [here](/adaptive-bitrate-streaming).
- **Subtitles and chapters**: Easy addition of subtitles, captions, and chapter markers to organize and navigate your video content. See [subtitles and captions](/video-player/subtitles-and-chapters#subtitles-and-captions) and [chapters](/video-player/subtitles-and-chapters#chapters).
- **Player enhancements**: Floating player that appears when scrolled out of view, and seek thumbnails that show previews when hovering over the progress bar.
- **Custom branding**: Add a clickable logo to brand your video player and link to your website.
- **Playlists and recommendations**: Create playlists of multiple videos with a scrollable widget, or display recommended videos when a video ends. See [playlist](/video-player/playlist-and-recommendations#playlist) and [recommendations](/video-player/playlist-and-recommendations#recommendations).
- **Shoppable Video**: Make your videos shoppable by displaying product images alongside your videos. This allows your users to visit your product detail pages and make a purchase. See [shoppable videos](/video-player/shoppable-videos).

{% callout style="info" %}
**Try it live:** See all features in action in this interactive [demo](https://imagekit-developer.github.io/imagekit-video-player/).
{% /callout %}

## Installation

Install the package using npm or yarn:

```bash
npm install @imagekit/video-player
# or
yarn add @imagekit/video-player
```

For JavaScript with CDN, add these links to your HTML:

```html
<link rel="stylesheet" href="https://unpkg.com/@imagekit/video-player@latest/dist/styles.css" />
<script src="https://unpkg.com/@imagekit/video-player@latest/dist/index.js"></script>
```

{% callout style="info" %}
**Tip:** For production use, pin to a specific version instead of using `@latest` to ensure stability: `@imagekit/video-player@1.2.3`
{% /callout %}

## Quick example

Here's how to set up a basic video player with a single video source.

{% linetabs %}

{% linetab title="JavaScript" %}
```html
<!-- Add video element to your HTML -->
<video id="my-video" class="video-js"></video>
```

```javascript
import { videoPlayer } from '@imagekit/video-player';
import '@imagekit/video-player/styles.css';

const player = videoPlayer('my-video', {
  imagekitId: 'YOUR_IMAGEKIT_ID'
});

player.src({
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4'
});
```
{% /linetab %}

{% linetab title="React" %}
```jsx
import { IKVideoPlayer } from '@imagekit/video-player/react';
import '@imagekit/video-player/styles.css';

export default function App() {
  const ikOptions = {
    imagekitId: 'YOUR_IMAGEKIT_ID'
  };

  const source = {
    src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4'
  };

  return (
    <IKVideoPlayer
      ikOptions={ikOptions}
      source={source}
    />
  );
}
```
{% /linetab %}

{% linetab title="Vue" %}
```html
<template>
  <IKVideoPlayer
    :ikOptions="ikOptions"
    :source="source"
  />
</template>

<script setup>
import { IKVideoPlayer } from '@imagekit/video-player/vue';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID'
};

const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4'
};
</script>
```
{% /linetab %}

{% linetab title="Astro" %}
```html
---
import { IKVideoPlayer } from '@imagekit/video-player/astro';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID'
};

const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4'
};
---

<IKVideoPlayer
  ikOptions={ikOptions}
  source={source}
/>
```
{% /linetab %}

{% /linetabs %}

## Adaptive bitrate streaming example

Enable adaptive bitrate streaming for optimal video quality based on network conditions. The player automatically generates all required streaming representations.

{% linetabs %}

{% linetab title="JavaScript" %}
```javascript
import { videoPlayer } from '@imagekit/video-player';
import '@imagekit/video-player/styles.css';

const player = videoPlayer('my-video', {
  imagekitId: 'YOUR_IMAGEKIT_ID',
  abs: {
    protocol: 'hls',
    sr: [360, 480, 720, 1080]
  }
});

player.src({
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4'
});
```
{% /linetab %}

{% linetab title="React" %}
```jsx
import { IKVideoPlayer } from '@imagekit/video-player/react';
import '@imagekit/video-player/styles.css';

export default function App() {
  const ikOptions = {
    imagekitId: 'YOUR_IMAGEKIT_ID',
    abs: {
      protocol: 'hls',
      sr: [360, 480, 720, 1080]
    }
  };

  const source = {
    src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4'
  };

  return (
    <IKVideoPlayer
      ikOptions={ikOptions}
      source={source}
    />
  );
}
```
{% /linetab %}

{% linetab title="Vue" %}
```html
<template>
  <IKVideoPlayer
    :ikOptions="ikOptions"
    :source="source"
  />
</template>

<script setup>
import { IKVideoPlayer } from '@imagekit/video-player/vue';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID',
  abs: {
    protocol: 'hls',
    sr: [360, 480, 720, 1080]
  }
};

const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4'
};
</script>
```
{% /linetab %}

{% linetab title="Astro" %}
```html
---
import { IKVideoPlayer } from '@imagekit/video-player/astro';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID',
  abs: {
    protocol: 'hls',
    sr: [360, 480, 720, 1080]
  }
};

const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4'
};
---

<IKVideoPlayer
  ikOptions={ikOptions}
  source={source}
/>
```
{% /linetab %}

{% /linetabs %}

{% callout style="info" %}
**Why use adaptive bitrate streaming?** ABS automatically adjusts video quality based on the viewer's network speed, providing smooth playback without buffering. It delivers the best quality possible for each viewer's connection.
{% /callout %}

## Player configuration

Configure how the player behaves globally, including your ImageKit ID, player features like floating mode and seek thumbnails, default transformations, and standard Video.js settings.

{% linetabs %}

{% linetab title="JavaScript" %}
The `videoPlayer` function accepts three parameters:

{% table %}
- **Parameter** {% width="30%" %}
- **Description** {% width="70%" %}
---
- element  
  `string | HTMLElement`
- Container element where the video player will be initialized. Can be a CSS selector string or a DOM element reference.
---
- ikOptions  
  `object`
- ImageKit-specific configuration options (see [IKPlayer options](#ikplayer-options) below).
---
- videoJsOptions  
  `object`
- Optional. Standard Video.js options passed directly to the underlying Video.js player instance. See [common Video.js options](#videojs-options) used.
{% /table %}
{% /linetab %}

{% linetab title="React" %}
Use the `IKVideoPlayer` component with the following props:

```jsx
import { IKVideoPlayer } from '@imagekit/video-player/react';
import '@imagekit/video-player/styles.css';

export default function App() {
  const ikOptions = {
    // IKPlayer options
  };

  const videoJsOptions = {
    // Video.js options
  };

  const source = {
    // Source options
  };

  return (
    <IKVideoPlayer
      ikOptions={ikOptions}
      videoJsOptions={videoJsOptions}
      source={source}
    />
  );
}
```

{% table %}
- **Prop** {% width="30%" %}
- **Description** {% width="70%" %}
---
- ikOptions **(required)**  
  `object`
- ImageKit-specific configuration options (see [IKPlayer options](#ikplayer-options) below).
---
- videoJsOptions  
  `object`
- Optional. Standard Video.js options passed directly to the underlying Video.js player instance. See [common Video.js options](#videojs-options) used.
---
- source  
  `object`
- Single video source configuration. See [Setting up video source](#setting-up-video-source) for details.
---
- playlist  
  `object`
- Playlist configuration with `sources` array and optional `options` object. See [playlist](/video-player/playlist-and-recommendations#playlist) for details.
{% /table %}

{% callout style="info" %}
At least one of `source` or `playlist` should be provided for the player to display a video. If both are provided, `playlist` takes precedence and `source` is ignored.
{% /callout %}
{% /linetab %}

{% linetab title="Vue" %}
Use the `IKVideoPlayer` component with the following props:

```jsx
<script setup>
import { IKVideoPlayer } from '@imagekit/video-player/vue';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  // IKPlayer options
};

const videoJsOptions = {
  // Video.js options
};

const source = {
  // Source options
};
</script>

<template>
  <IKVideoPlayer
    :ikOptions="ikOptions"
    :videoJsOptions="videoJsOptions"
    :source="source"
  />
</template>
```

{% table %}
- **Prop** {% width="30%" %}
- **Description** {% width="70%" %}
---
- ikOptions **(required)**  
  `object`
- ImageKit-specific configuration options (see [IKPlayer options](#ikplayer-options) below).
---
- videoJsOptions  
  `object`
- Optional. Standard Video.js options passed directly to the underlying Video.js player instance. See [common Video.js options](#videojs-options) used.
---
- source  
  `object`
- Single video source configuration. See [Setting up video source](#setting-up-video-source) for details.
---
- playlist  
  `object`
- Playlist configuration with `sources` array and optional `options` object. See [playlist](/video-player/playlist-and-recommendations#playlist) for details.
{% /table %}

{% callout style="info" %}
At least one of `source` or `playlist` should be provided for the player to display a video. If both are provided, `playlist` takes precedence and `source` is ignored.
{% /callout %}
{% /linetab %}

{% linetab title="Astro" %}
Use the `IKVideoPlayer` Astro component with the following props:

```html
---
import { IKVideoPlayer } from '@imagekit/video-player/astro';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  // IKPlayer options
};

const videoJsOptions = {
  // Video.js options
};

const source = {
  // Source options
};
---

<IKVideoPlayer
  ikOptions={ikOptions}
  videoJsOptions={videoJsOptions}
  source={source}
/>
```

{% table %}
- **Prop** {% width="30%" %}
- **Description** {% width="70%" %}
---
- ikOptions **(required)**  
  `object`
- ImageKit-specific configuration options (see [IKPlayer options](#ikplayer-options) below).
---
- videoJsOptions  
  `object`
- Optional. Standard Video.js options passed directly to the underlying Video.js player instance. See [common Video.js options](#videojs-options) used.
---
- source  
  `object`
- Single video source configuration. See [Setting up video source](#setting-up-video-source) for details.
---
- playlist  
  `object`
- Playlist configuration with `sources` array and optional `options` object. See [playlist](/video-player/playlist-and-recommendations#playlist) for details.
{% /table %}

{% callout style="info" %}
At least one of `source` or `playlist` should be provided for the player to display a video. If both are provided, `playlist` takes precedence and `source` is ignored.
{% /callout %}
{% /linetab %}

{% /linetabs %}

### IKPlayer options

ImageKit-specific configuration options for the video player.

{% table %}
- **Parameter** {% width="50%" %}
- **Description** {% width="50%" %}
---
- imagekitId **(required)**  
  `string`
- Your ImageKit ID
---
- floatingWhenNotVisible  
  `'left' | 'right' | null`
- When enabled, displays a floating player in a corner of the screen when half of the player is visible in the viewport. Use `'right'` to show the floating player in the bottom right corner, or `'left'` for the bottom left corner. Set to `null` to disable.  
  Default: `null`
---
- hideContextMenu  
  `boolean`
- Hide right-click context menu.  
  Default: `false`
---
- logo  
  `object`
- Configurations to show a clickable logo within the player.

  ```javascript
  {
    // Default: false
    showLogo: boolean;
    // URL of the logo image
    logoImageUrl: string;
    // URL to navigate when clicked
    logoOnclickUrl: string;
  }
  ```
---
- seekThumbnails  
  `boolean`
- Enable seek thumbnails on progress bar.  
  Default: `true`
---
- abs  
  `object`
- Adaptive bitrate streaming configurations. See [Adaptive bitrate streaming](/adaptive-bitrate-streaming) for more details.

  ```javascript
  {
    // Streaming protocol
    protocol: 'hls' | 'dash';
    // Screen resolutions, e.g., [240, 360, 720, 1080]
    sr: number[];
  }
  ```

  **Note:** When using ABS, you cannot provide these transformations: `w`, `h`, `ar`, `f`, `vc`, `ac`, and `q`. All other video transformations will work.
---
- transformation  
  `object[]`
- Global ImageKit transformations applied to all video sources. Can be overridden per video in the source configuration. Useful for playlists and recommendations to ensure consistent transformations across all videos. See [video transformations](/video-transformation).
---
- maxTries  
  `number`
- The maximum number of times the video player will attempt to request a video. Multiple requests may be necessary if the video is still being processed when it is first requested.  
  Default: `3`
---
- videoTimeoutInMS  
  `number`
- The maximum time (in milliseconds) the video player will wait for a video to be available in each video request. This may be relevant if the video is still being processed when it is first requested.  
  Default: `55000`
---
- delayInMS  
  `number`
- Delay in milliseconds between retry attempts for failed video requests. Defaults to exponential backoff (10,000ms, 20,000ms, 40,000ms, etc.) if not specified. When set, uses a fixed delay instead.  
  Default: Exponential backoff
---
- signerFn  
  `Function`
- A function that generates a signed URL when provided with an ImageKit-powered input URL. Required for [private files](/media-delivery-basic-security#private-files) or when [restrict unsigned videos](/media-delivery-basic-security#restrict-unsigned-urls) setting is enabled on the account.
{% /table %}

### VideoJs options

Standard [Video.js 8.20.0](https://docs.videojs.com/) options are passed directly to the underlying Video.js player instance. This parameter is optional and allows you to configure native Video.js behavior like player dimensions, autoplay, controls visibility, and playback settings. Common options include `controls` (boolean), `autoplay` (boolean or `'muted'`), `muted` (boolean), `preload` (`'auto'`, `'metadata'`, or `'none'`), `width` and `height` (number or string), `fluid` and `responsive` (boolean), `playbackRates` (array of numbers), and `aspectRatio` (string like `'16:9'`). For the complete list of available options, refer to the [Video.js documentation](https://docs.videojs.com/).

{% callout style="info" %}
**Common use cases:** Most developers use `videoJsOptions` for basic settings like `autoplay: 'muted'` for auto-playing videos, `fluid: true` for responsive sizing, or `playbackRates: [0.5, 1, 1.5, 2]` for speed controls.

**Caution with plugins:** Using the `plugins` option may interfere with ImageKit's video player features. Test thoroughly before deploying to production.
{% /callout %}

## Setting up video source

The player configuration (IKPlayer options and VideoJs options) defines how the player behaves globally - things like your ImageKit ID, floating player settings, and default transformations that apply to all videos. Source options, on the other hand, configure individual videos - their URLs, metadata, poster images, and video-specific transformations. Think of player options as the player's personality, and source options as the content it plays.

{% linetabs %}

{% linetab title="JavaScript" %}
Set the video source using `player.src()`:

```javascript
// Set source with options object
player.src({
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  // ... options
});

// Get current source
const currentSrc = player.src();
```
{% /linetab %}

{% linetab title="React" %}
Set the video source using the `source` prop:

```jsx
import { IKVideoPlayer } from '@imagekit/video-player/react';
import '@imagekit/video-player/styles.css';

function App() {
  const ikOptions = {
    imagekitId: 'YOUR_IMAGEKIT_ID'
  };

  const source = {
    src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
    // ... options
  };

  return (
    <IKVideoPlayer
      ikOptions={ikOptions}
      source={source}
    />
  );
}
```
{% /linetab %}

{% linetab title="Vue" %}
Set the video source using the `source` prop:

```jsx
<template>
  <IKVideoPlayer
    :ikOptions="ikOptions"
    :source="source"
  />
</template>

<script setup>
import { IKVideoPlayer } from '@imagekit/video-player/vue';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID'
};

const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  // ... options
};
</script>
```
{% /linetab %}

{% linetab title="Astro" %}
Set the video source using the `source` prop:

```html
---
import { IKVideoPlayer } from '@imagekit/video-player/astro';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID'
};

const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  // ... options
};
---

<IKVideoPlayer
  ikOptions={ikOptions}
  source={source}
/>
```
{% /linetab %}

{% /linetabs %}

#### Source options

{% table %}
- **Parameter** {% width="50%" %}
- **Description** {% width="50%" %}
---
- src **(required)**  
  `string`
- ImageKit-powered URL of the video source
---
- chapters  
  `boolean | object`
- Chapters configuration for dividing videos into sections with markers on the progress bar.

  ```javascript
  // Auto-generate chapters using AI
  true
  
  // Or load from VTT file
  { url: string }
  
  // Or provide time-based chapters (keys are seconds)
  { [key: number]: string }
  // Example: { 0: 'Introduction', 30: 'Main content', 60: 'End' }
  ```
---
- info  
  `object`
- Video metadata displayed in upcoming video preview and playlist widgets.

  ```javascript
  {
    // Video title
    title: string;
    // Video description
    description: string;
  }
  ```
---
- poster  
  `object`
- Poster image configuration. If omitted, ImageKit generates a thumbnail automatically.

  ```javascript
  {
    // Poster image URL
    src: string;
    // ImageKit transformations
    transformation: object[];
  }
  ```
---
- abs  
  `object`
- Adaptive bitrate streaming configuration for HLS or DASH. See [adaptive bitrate streaming](/adaptive-bitrate-streaming) for more details.

  ```javascript
  {
    protocol: 'hls' | 'dash';
    sr: number[];
  }
  ```
---
- transformation  
  `object[]`
- ImageKit transformations to apply to the video. See [video transformations](/video-transformation).
---
- recommendations  
  `object[]`
- Array of recommended videos to display when the video ends. Each item is a [source options](/video-player/overview#source-options) object. See [recommendations](/video-player/playlist-and-recommendations#recommendations).
---
- shoppable  
  `object`
- Shoppable video configuration. See [shoppable options](/video-player/shoppable-videos#shoppable-options) for more detail.
---
- textTracks  
  `object[]`
- Array of text tracks for subtitles and captions. See [subtitles & chapters](/video-player/subtitles-and-chapters).
{% /table %}

## Getting the player instance

The player supports all standard Video.js events and methods. Common events include `play`, `pause`, `ended`, `timeupdate`, and `ready`. Common methods include `play()`, `pause()`, `currentTime()`, `src()`, `volume()`, and `muted()`. See the [Video.js Player API documentation](https://docs.videojs.com/player.html) for the complete list.

{% linetabs %}
{% linetab title="JavaScript" %}
In JavaScript, the `videoPlayer()` function returns the player instance directly:

```javascript
import { videoPlayer } from '@imagekit/video-player';
import '@imagekit/video-player/styles.css';

const player = videoPlayer('my-video', {
  imagekitId: 'YOUR_IMAGEKIT_ID'
});

// Listen to common events
player.on('play', () => console.log('Playing'));
player.on('pause', () => console.log('Paused'));
player.on('ended', () => console.log('Ended'));
player.on('timeupdate', () => {
  console.log('Time:', player.currentTime());
});

// Use common methods
player.play();
player.pause();
player.currentTime(30); // Seek to 30 seconds
```
{% /linetab %}

{% linetab title="React" %}
In React, use a ref to access the player instance:

```jsx
import { useRef, useEffect } from 'react';
import { IKVideoPlayer } from '@imagekit/video-player/react';
import type { IKVideoPlayerRef } from '@imagekit/video-player/react';
import '@imagekit/video-player/styles.css';

function App() {
  const playerRef = useRef<IKVideoPlayerRef>(null);

  useEffect(() => {
    const checkPlayer = () => {
      const player = playerRef.current?.getPlayer();
      if (player) {
        // Listen to common events
        player.on('play', () => console.log('Playing'));
        player.on('pause', () => console.log('Paused'));
        player.on('ended', () => console.log('Ended'));
        player.on('timeupdate', () => {
          console.log('Time:', player.currentTime());
        });
      } else {
        setTimeout(checkPlayer, 50);
      }
    };
    checkPlayer();
  }, []);

  // Use common methods
  const play = () => playerRef.current?.getPlayer()?.play();
  const pause = () => playerRef.current?.getPlayer()?.pause();
  const seek = (time) => playerRef.current?.getPlayer()?.currentTime(time);

  return (
    <IKVideoPlayer
      ref={playerRef}
      ikOptions={{ imagekitId: 'YOUR_IMAGEKIT_ID' }}
      source={{ src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4' }}
    />
  );
}
```
{% /linetab %}

{% linetab title="Vue" %}
In Vue, use a ref to access the player instance:

```jsx
<template>
  <IKVideoPlayer
    ref="playerRef"
    :ikOptions="ikOptions"
    :source="source"
  />
</template>

<script setup>
import { ref, onMounted } from 'vue';
import { IKVideoPlayer } from '@imagekit/video-player/vue';
import type { IKVideoPlayerRef } from '@imagekit/video-player/vue';
import '@imagekit/video-player/styles.css';

const playerRef = ref<IKVideoPlayerRef | null>(null);

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID'
};

const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4'
};

// Use common methods
const play = () => playerRef.value?.getPlayer()?.play();
const pause = () => playerRef.value?.getPlayer()?.pause();
const seek = (time) => playerRef.value?.getPlayer()?.currentTime(time);

onMounted(() => {
  const checkPlayer = () => {
    const player = playerRef.value?.getPlayer();
    if (player) {
      // Listen to common events
      player.on('play', () => console.log('Playing'));
      player.on('pause', () => console.log('Paused'));
      player.on('ended', () => console.log('Ended'));
      player.on('timeupdate', () => {
        console.log('Time:', player.currentTime());
      });
    } else {
      setTimeout(checkPlayer, 50);
    }
  };
  checkPlayer();
});
</script>
```
{% /linetab %}

{% linetab title="Astro" %}
In Astro, use the JavaScript API in a client-side `<script>` block to access the player instance directly:

```html
---
import { IKVideoPlayer } from '@imagekit/video-player/astro';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID'
};

const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4'
};
---

<IKVideoPlayer
  id="my-video"
  ikOptions={ikOptions}
  source={source}
/>

<script>
  const elem = document.getElementById('my-video');
  const player = elem.getPlayer();

  // Listen to common events
  player.on('play', () => console.log('Playing'));
  player.on('pause', () => console.log('Paused'));
  player.on('ended', () => console.log('Ended'));
  player.on('timeupdate', () => {
    console.log('Time:', player.currentTime());
  });

  // Use common methods
  player.play();
  player.pause();
  player.currentTime(30); // Seek to 30 seconds
</script>
```
{% /linetab %}
{% /linetabs %}

## Generating signed URLs

If your account has [restrict unsigned URLs](/media-delivery-basic-security#restrict-unsigned-urls) enabled, or if you are delivering [private files](/media-delivery-basic-security#private-files), every resource (video, poster, seek thumbnails, subtitles etc.) URL the player loads must be signed.

The player handles this through a **signer function** that you provide:

```ts
type SignerFn = (url: string) => Promise<string>;
```

The player calls your function each time it needs to load a resource, not once upfront. This means you can return short-lived signed URLs — every new resource load gets a fresh signature.

{% callout style="warning" %}
**Sign on the server, never in the browser.** Signing requires your ImageKit **private key**, which must never be shipped to the client. Expose an endpoint in your backend that performs the signing — either using one of ImageKit's [server-side SDKs](/media-delivery-basic-security#how-to-generate-signed-urls), or by implementing it yourself following the [signed URL generation guide](/media-delivery-basic-security#pseudo-code-to-generate-signed-url) — and call it from `signerFn`.
{% /callout %}

{% linetabs %}

{% linetab title="JavaScript" %}
```javascript
import { videoPlayer } from '@imagekit/video-player';
import '@imagekit/video-player/styles.css';

const player = videoPlayer('my-video', {
  imagekitId: 'YOUR_IMAGEKIT_ID',
  signerFn: async (url) => {
    const res = await fetch('/api/sign', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ url }),
    });
    return await res.text(); // signed URL as plain text
  },
});

player.src({ src: 'https://ik.imagekit.io/<your-imagekit-id>/private-video.mp4' });
```
{% /linetab %}

{% linetab title="React" %}
```jsx
import { IKVideoPlayer } from '@imagekit/video-player/react';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID',
  signerFn: async (url) => {
    const res = await fetch('/api/sign', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ url }),
    });
    return await res.text();
  },
};

export default function App() {
  return (
    <IKVideoPlayer
      ikOptions={ikOptions}
      source={{ src: 'https://ik.imagekit.io/<your-imagekit-id>/private-video.mp4' }}
    />
  );
}
```
{% /linetab %}

{% linetab title="Vue" %}
```html
<template>
  <IKVideoPlayer :ik-options="ikOptions" :source="source" />
</template>

<script setup>
import { IKVideoPlayer } from '@imagekit/video-player/vue';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID',
  signerFn: async (url) => {
    const res = await fetch('/api/sign', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ url }),
    });
    return await res.text();
  },
};

const source = { src: 'https://ik.imagekit.io/<your-imagekit-id>/private-video.mp4' };
</script>
```
{% /linetab %}

{% linetab title="Astro" %}
Astro renders `.astro` components to HTML on the server, so a JavaScript function passed as a prop can't be carried over to the browser. This means the `signerFn` you'd use in other frameworks cannot be wired up the same way here.

The Astro component offers two ways to attach a signer instead:

- **Declarative:** Configure the component with the location of your signing endpoint and let it call that endpoint from the browser whenever a signed URL is needed. Use this when the endpoint can authorize the request on its own — for example, via a session cookie sent automatically with the request.
- **Imperative:** Render the component without a signer and attach one later from a client-side `<script>`. Use this when signing depends on client-side runtime state that isn't available at render time — such as an in-memory access token, a value from an auth SDK, or any signing flow that doesn't fit the simple POST contract.

{% callout style="info" %}
**Need something neither approach can express?** You can drop the `React` or `Vue` `IKVideoPlayer` component into an Astro page via an [Astro UI framework integration](https://docs.astro.build/en/guides/integrations-guide/#official-integrations). Those components accept a `signerFn` directly and offer a simpler interface for arbitrary signing logic.
{% /callout %}

{% linetabs %}

{% linetab title="Declarative" %}
{% callout style="warning" %}
**Do not put secrets in `signerOptions`.** The `url`, `headers`, and `body` you set here are rendered into the page HTML and visible to anyone who views the source. Never include API keys, access tokens, or per-user secrets. If your signer needs a value that shouldn't be exposed in the HTML, use the imperative approach.
{% /callout %}

```html
---
import { IKVideoPlayer } from '@imagekit/video-player/astro';
import '@imagekit/video-player/styles.css';

const ikOptions = { imagekitId: 'YOUR_IMAGEKIT_ID' };
const source = { src: 'https://ik.imagekit.io/<your-imagekit-id>/private-video.mp4' };
---

<IKVideoPlayer
  ikOptions={ikOptions}
  source={source}
  signerOptions={{ url: '/api/sign' }}
/>
```

**Endpoint contract** — your `/api/sign` route must:

- Accept `POST` with a JSON body `{ url: string, ...body }`.
- Return the signed URL as **plain text** in the response body with a 2xx status.

`signerOptions` also accepts:

{% table %}
- **Field** {% width="25%" %}
- **Description** {% width="75%" %}
---
- url **(required)**
- Endpoint that returns the signed URL as plain text.
---
- headers
- Extra request headers (e.g. a static API key).
---
- body
- Extra JSON fields merged with `{ url }` in the request body.
---
- credentials
- `fetch` credentials mode. Defaults to `'same-origin'`, so session cookies are sent automatically for same-origin endpoints.
{% /table %}
{% /linetab %}

{% linetab title="Imperative" %}
Set `signerOptions={{ mode: 'imperative' }}` so the component **defers loading the video** until you assign `signerFn` to the `ik-video-player` element from a sibling `<script>`. The pending source is flushed through the signer as soon as it is assigned.

```html
---
import { IKVideoPlayer } from '@imagekit/video-player/astro';
import '@imagekit/video-player/styles.css';
---

<IKVideoPlayer
  id="player"
  ikOptions={{ imagekitId: 'YOUR_IMAGEKIT_ID' }}
  source={{ src: 'https://ik.imagekit.io/<your-imagekit-id>/private-video.mp4' }}
  signerOptions={{ mode: 'imperative' }}
/>

<script>
  const el = document.querySelector('#player');
  el.signerFn = async (url) => {
    // Obtain the token however your app does it (auth SDK, cookie-backed
    // endpoint, etc.). The point of the imperative pattern is that this
    // value is resolved on the client, after hydration.
    const token = await getAccessToken();
    const res = await fetch('/api/sign', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${token}`,
      },
      body: JSON.stringify({ url }),
    });
    return await res.text();
  };
</script>
```
{% /linetab %}

{% /linetabs %}
{% /linetab %}

{% /linetabs %}

## Best practices

- **Use adaptive bitrate streaming**: Enable ABS for better viewer experience across different network conditions. It automatically optimizes quality based on bandwidth.
- **Optimize video transformations**: Apply global transformations at the player level for consistency, and override per-video when needed for specific content requirements.
- **Enable seek thumbnails**: Keep seek thumbnails enabled (default behavior) to help viewers navigate through content quickly.
- **Pin package versions**: In production, use specific version numbers instead of `@latest` to avoid unexpected breaking changes.
- **Test player events**: Always test video player events (`play`, `pause`, `ended`) in your target browsers to ensure compatibility with your application logic.
- **Consider floating player**: For content-heavy pages with long scrolls, enable `floatingWhenNotVisible` to keep videos accessible as users browse.
- **Implement signed URLs**: For private or sensitive content, use the `signerFn` option to secure your video delivery.

## Related features

- **[Subtitles & chapters](/video-player/subtitles-and-chapters)**: Add subtitles, captions, and chapter markers to your videos
- **[Playlist & recommendations](/video-player/playlist-and-recommendations)**: Create playlists and show video recommendations
- **[Shoppable videos](/video-player/shoppable-videos)**: Make your videos shoppable with product overlays
- **[Adaptive bitrate streaming](/adaptive-bitrate-streaming)**: Learn more about HLS and MPEG-DASH support
- **[Video transformations](/video-transformation)**: Apply transformations to optimize your videos


---

# Source: /video-player/subtitles-and-chapters

---
title: Subtitles & chapters
description: Learn how to add subtitles, captions, and chapter markers to your videos using ImageKit Video Player with AI-powered auto-generation, word-level highlighting, and multi-language support.
---

Enhance your video content with subtitles, captions, and chapter markers using ImageKit Video Player. This guide covers both manual configuration and AI-powered auto-generation features that make your videos more accessible and navigable.

## Subtitles and captions

Add subtitles and captions using the `textTracks` array when [setting up your video source](/video-player/overview#setting-up-video-source). ImageKit supports standard [WebVTT files](https://developer.mozilla.org/en-US/docs/Web/API/WebVTT_API/Web_Video_Text_Tracks_Format) or AI-powered auto-generation with advanced features like word highlighting and multi-language translation.

{% callout style="info" %}
**Why use subtitles?** Subtitles improve accessibility, boost engagement, and help with SEO. They make your content accessible to viewers who are deaf or hard of hearing, watching in sound-sensitive environments, or speak different languages.
{% /callout %}

### Auto-generated subtitles

Auto-generate subtitles using ImageKit's AI transcription. This approach creates a custom transcript file (`.transcript`) that supports advanced features unavailable in standard VTT files, including word-level highlighting and automatic multi-language translation.

{% callout style="info" %}
**Note:** AI transcription costs **2 extension units per minute** of source video duration. When you enable auto-generated subtitles or chapters for a video, both features are generated together automatically—you're billed once, not separately. Each language translation costs an additional **2 units per minute** for that language's subtitles and chapters. Learn about [extension unit pricing](/how-pricing-works#extension-units-pricing) here.
{% /callout %}

{% linetabs %}

{% linetab title="JavaScript" %}
```javascript
import { videoPlayer } from '@imagekit/video-player';
import '@imagekit/video-player/styles.css';

const player = videoPlayer('my-video', {
  imagekitId: 'YOUR_IMAGEKIT_ID'
});

player.src({
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  textTracks: [
    {
      autoGenerate: true,
      default: true,
      maxChars: 60, // Control subtitle pace
      highlightWords: true, // Enable word-level highlighting
      translations: [
        { langCode: 'fr', label: 'French' },
        { langCode: 'de', label: 'German' },
        { langCode: 'hi', label: 'Hindi' }
      ]
    }
  ]
});
```
{% /linetab %}

{% linetab title="React" %}
```jsx
import { IKVideoPlayer } from '@imagekit/video-player/react';
import '@imagekit/video-player/styles.css';

export default function App() {
  const ikOptions = {
    imagekitId: 'YOUR_IMAGEKIT_ID'
  };

  const source = {
    src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
    textTracks: [
      {
        autoGenerate: true,
        default: true,
        maxChars: 60,
        highlightWords: true,
        translations: [
          { langCode: 'fr', label: 'French' },
          { langCode: 'de', label: 'German' },
          { langCode: 'hi', label: 'Hindi' }
        ]
      }
    ]
  };

  return (
    <IKVideoPlayer
      ikOptions={ikOptions}
      source={source}
    />
  );
}
```
{% /linetab %}

{% linetab title="Vue" %}
```html
<template>
  <IKVideoPlayer
    :ikOptions="ikOptions"
    :source="source"
  />
</template>

<script setup>
import { IKVideoPlayer } from '@imagekit/video-player/vue';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID'
};

const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  textTracks: [
    {
      autoGenerate: true,
      default: true,
      maxChars: 60,
      highlightWords: true,
      translations: [
        { langCode: 'fr', label: 'French' },
        { langCode: 'de', label: 'German' },
        { langCode: 'hi', label: 'Hindi' }
      ]
    }
  ]
};
</script>
```
{% /linetab %}

{% linetab title="Astro" %}
```astro
---
import { IKVideoPlayer } from '@imagekit/video-player/astro';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID'
};

const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  textTracks: [
    {
      autoGenerate: true,
      default: true,
      maxChars: 60,
      highlightWords: true,
      translations: [
        { langCode: 'fr', label: 'French' },
        { langCode: 'de', label: 'German' },
        { langCode: 'hi', label: 'Hindi' }
      ]
    }
  ]
};
---

<IKVideoPlayer
  ikOptions={ikOptions}
  source={source}
/>
```
{% /linetab %}

{% /linetabs %}

Try the video player with auto-generated subtitles and translations:

{% ikvideoplayer config="subtitles-demo" /%}

### Standard WebVTT track

Use your own pre-created subtitle files by providing the ImageKit-powered URL to your WebVTT (`.vtt`) file. Upload VTT files to ImageKit as raw files, then reference them in your player configuration.

{% linetabs %}

{% linetab title="JavaScript" %}
```javascript
import { videoPlayer } from '@imagekit/video-player';
import '@imagekit/video-player/styles.css';

const player = videoPlayer('my-video', {
  imagekitId: 'YOUR_IMAGEKIT_ID'
});

player.src({
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  textTracks: [
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/subtitles-en.vtt',
      kind: 'subtitles',
      srclang: 'en',
      label: 'English',
      default: true
    },
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/subtitles-es.vtt',
      kind: 'subtitles',
      srclang: 'es',
      label: 'Spanish'
    }
  ]
});
```
{% /linetab %}

{% linetab title="React" %}
```jsx
import { IKVideoPlayer } from '@imagekit/video-player/react';
import '@imagekit/video-player/styles.css';

export default function App() {
  const ikOptions = {
    imagekitId: 'YOUR_IMAGEKIT_ID'
  };

  const source = {
    src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
    textTracks: [
      {
        src: 'https://ik.imagekit.io/<your-imagekit-id>/subtitles-en.vtt',
        kind: 'subtitles',
        srclang: 'en',
        label: 'English',
        default: true
      },
      {
        src: 'https://ik.imagekit.io/<your-imagekit-id>/subtitles-es.vtt',
        kind: 'subtitles',
        srclang: 'es',
        label: 'Spanish'
      }
    ]
  };

  return (
    <IKVideoPlayer
      ikOptions={ikOptions}
      source={source}
    />
  );
}
```
{% /linetab %}

{% linetab title="Vue" %}
```html
<template>
  <IKVideoPlayer
    :ikOptions="ikOptions"
    :source="source"
  />
</template>

<script setup>
import { IKVideoPlayer } from '@imagekit/video-player/vue';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID'
};

const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  textTracks: [
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/subtitles-en.vtt',
      kind: 'subtitles',
      srclang: 'en',
      label: 'English',
      default: true
    },
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/subtitles-es.vtt',
      kind: 'subtitles',
      srclang: 'es',
      label: 'Spanish'
    }
  ]
};
</script>
```
{% /linetab %}

{% linetab title="Astro" %}
```astro
---
import { IKVideoPlayer } from '@imagekit/video-player/astro';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID'
};

const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  textTracks: [
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/subtitles-en.vtt',
      kind: 'subtitles',
      srclang: 'en',
      label: 'English',
      default: true
    },
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/subtitles-es.vtt',
      kind: 'subtitles',
      srclang: 'es',
      label: 'Spanish'
    }
  ]
};
---

<IKVideoPlayer
  ikOptions={ikOptions}
  source={source}
/>
```
{% /linetab %}

{% /linetabs %}

#### Standard WebVTT track options

{% table %}
- **Parameter** {% width="50%" %}
- **Description** {% width="50%" %}
---
- src  
  `string`
- ImageKit-powered URL to `.vtt` file
---
- kind  
  `'subtitles' | 'captions'`
- Type of text track.  
  Default: `'subtitles'`
---
- srclang  
  `string`
- Language code (e.g., 'en', 'fr')
---
- label  
  `string`
- Display label for the text track in the subtitle menu
---
- default  
  `boolean`
- Whether to activate this track by default
{% /table %}

### Combining auto-generated and manual tracks

You can mix auto-generated subtitles with manual WebVTT files in the same `textTracks` array, giving viewers more subtitle options:

```javascript
textTracks: [
  {
    autoGenerate: true, // AI-generated with word highlighting
    default: true,
    maxChars: 60,
    highlightWords: true
  },
  {
    src: 'https://ik.imagekit.io/<your-imagekit-id>/subtitles-custom.vtt',
    kind: 'subtitles',
    srclang: 'en',
    label: 'English (Professional)'
  }
]
```

#### Auto-generated text track options

{% table %}
- **Parameter** {% width="50%" %}
- **Description** {% width="50%" %}
---
- autoGenerate  
  `true`
- Must be `true` to enable auto-generated subtitles
---
- showAutoGenerated  
  `boolean`
- Whether to display auto-generated subtitles in the subtitle menu.  
  Default: `true`
---
- autoGeneratedLabel  
  `string`
- Custom display label for auto-generated subtitles in the subtitle menu.  
  Default: `<detected language> (auto-generated)`, e.g., `English (auto-generated)`
---
- default  
  `boolean`
- Whether to activate this track by default
---
- maxChars  
  `number`
- Maximum characters per subtitle line. Controls the pace of subtitles by defining how many characters appear on each subtitle frame.  
  Default: `60`
---
- highlightWords  
  `boolean`
- Enable word-level highlighting to show exactly when each individual word gets spoken in the video, similar to karaoke.  
  Default: `false`
---
- translations  
  `object[]`
- Array of translation options. Each translation object has:

  ```javascript
  {
    // Language code (e.g., 'en', 'es', 'fr', 'de', 'hi', 'ja', 'zh')
    // See supported languages for the complete list
    langCode: string;
    // Custom display label in subtitle menu
    label?: string;
    // Activate this track by default
    default?: boolean;
  }
  ```

  Note: `maxChars` and `highlightWords` only apply to original transcription, not translations. See the complete list of [supported languages](/video-player/supported-languages) for all available language codes.
{% /table %}

## Chapters

Chapters divide your video into sections with visual markers on the progress bar. Users can click the chapter button in the player control bar to view a list of chapters and quickly navigate to key sections, improving content discoverability and user experience.

{% callout style="info" %}
**Why use chapters?** Chapters help viewers navigate long-form content, skip to relevant sections, and understand video structure at a glance. They're especially useful for tutorials, webinars, and educational content.
{% /callout %}

### Chapter configuration options

Configure chapters using the `chapters` parameter when [setting up your video source](/video-player/overview#setting-up-video-source). You can configure chapters in three ways:

#### 1. Auto-generate with AI

Set `chapters: true` to automatically generate chapter markers using ImageKit's AI analysis. Chapters are generated in the video's original language. If you have added translations in your `textTracks` [configuration](/video-player/subtitles-and-chapters#auto-generated-text-track-options), chapters are also generated in those translated languages. See [extension unit pricing](/how-pricing-works#extension-units-pricing) for details.

{% linetabs %}

{% linetab title="JavaScript" %}
```javascript
import { videoPlayer } from '@imagekit/video-player';
import '@imagekit/video-player/styles.css';

const player = videoPlayer('my-video', {
  imagekitId: 'YOUR_IMAGEKIT_ID'
});

player.src({
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  chapters: true // AI-powered chapter generation
});
```
{% /linetab %}

{% linetab title="React" %}
```jsx
import { IKVideoPlayer } from '@imagekit/video-player/react';
import '@imagekit/video-player/styles.css';

export default function App() {
  const ikOptions = {
    imagekitId: 'YOUR_IMAGEKIT_ID'
  };

  const source = {
    src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
    chapters: true // AI-powered chapter generation
  };

  return (
    <IKVideoPlayer
      ikOptions={ikOptions}
      source={source}
    />
  );
}
```
{% /linetab %}

{% linetab title="Vue" %}
```html
<template>
  <IKVideoPlayer
    :ikOptions="ikOptions"
    :source="source"
  />
</template>

<script setup>
import { IKVideoPlayer } from '@imagekit/video-player/vue';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID'
};

const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  chapters: true // AI-powered chapter generation
};
</script>
```
{% /linetab %}

{% linetab title="Astro" %}
```astro
---
import { IKVideoPlayer } from '@imagekit/video-player/astro';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID'
};

const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  chapters: true // AI-powered chapter generation
};
---

<IKVideoPlayer
  ikOptions={ikOptions}
  source={source}
/>
```
{% /linetab %}

{% /linetabs %}

{% ikvideoplayer config="chapters-auto-demo" /%}

#### 2. Manual chapter definition

Define chapters directly by specifying start times (in seconds) as keys and chapter titles as values:

{% linetabs %}

{% linetab title="JavaScript" %}
```javascript
player.src({
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  chapters: {
    0: 'Introduction',
    146: 'Main Content',
    302: 'Advanced Topics',
    443: 'Q&A Session',
    563: 'Conclusion'
  }
});
```
{% /linetab %}

{% linetab title="React" %}
```jsx
const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  chapters: {
    0: 'Introduction',
    146: 'Main Content',
    302: 'Advanced Topics',
    443: 'Q&A Session',
    563: 'Conclusion'
  }
};
```
{% /linetab %}

{% linetab title="Vue" %}
```javascript
const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  chapters: {
    0: 'Introduction',
    146: 'Main Content',
    302: 'Advanced Topics',
    443: 'Q&A Session',
    563: 'Conclusion'
  }
};
```
{% /linetab %}

{% linetab title="Astro" %}
```javascript
const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  chapters: {
    0: 'Introduction',
    146: 'Main Content',
    302: 'Advanced Topics',
    443: 'Q&A Session',
    563: 'Conclusion'
  }
};
```
{% /linetab %}

{% /linetabs %}

{% ikvideoplayer config="chapters-manual-demo" /%}

#### 3. Load from WebVTT file

Load chapters from an external WebVTT file for easier management and reusability:

{% linetabs %}

{% linetab title="JavaScript" %}
```javascript
player.src({
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  chapters: { 
    url: 'https://ik.imagekit.io/<your-imagekit-id>/chapters.vtt' 
  }
});
```
{% /linetab %}

{% linetab title="React" %}
```jsx
const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  chapters: { 
    url: 'https://ik.imagekit.io/<your-imagekit-id>/chapters.vtt' 
  }
};
```
{% /linetab %}

{% linetab title="Vue" %}
```javascript
const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  chapters: { 
    url: 'https://ik.imagekit.io/<your-imagekit-id>/chapters.vtt' 
  }
};
```
{% /linetab %}

{% linetab title="Astro" %}
```javascript
const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  chapters: {
    url: 'https://ik.imagekit.io/<your-imagekit-id>/chapters.vtt'
  }
};
```
{% /linetab %}

{% /linetabs %}

Your WebVTT file should follow the standard format. Here's a sample:

```vtt
WEBVTT

00:00:00.000 --> 00:02:26.470
Introduction

00:02:26.470 --> 00:05:02.140
Main Content

00:05:02.140 --> 00:07:23.060
Advanced Topics

00:07:23.060 --> 00:09:22.810
Q&A Session

00:09:22.810 --> 00:11:43.120
Conclusion
```

{% ikvideoplayer config="chapters-url-demo" /%}

## Best practices

### For subtitles and captions

- **Use auto-generation for quick deployment**: ImageKit's AI transcription is accurate and supports 50+ languages, making it ideal for rapid content deployment.
- **Combine methods for professional content**: Use auto-generated subtitles for quick turnaround, then add professionally edited VTT files for critical business content.
- **Enable word highlighting for engagement**: The `highlightWords` feature creates a karaoke-like experience that boosts viewer engagement, especially for educational content.
- **Optimize reading pace**: Adjust `maxChars` (default: 60) based on your audience—fewer characters per line for younger viewers or complex content.
- **Provide multiple language options**: Use the `translations` array to reach global audiences without manual translation work.

### For chapters

- **Keep chapter titles concise**: Use short, descriptive titles that fit well in the chapter menu (aim for 3-6 words).
- **Strategic timing**: Place chapter markers at natural content transitions, not in the middle of sentences or actions.
- **Use auto-generation first**: Let AI analyze your video structure, then refine manually if needed.
- **Consider viewer intent**: For tutorials, chapter at each major step. For presentations, chapter at topic changes.

## Related features

- **[Supported Languages](/video-player/supported-languages)**: Complete list of languages supported for AI translation
- **[Playlist & Recommendations](/video-player/playlist-and-recommendations)**: Create playlists and show video recommendations
- **[Video Player Overview](/video-player/overview)**: Complete guide to ImageKit's video player features
- **[Adaptive Bitrate Streaming](/adaptive-bitrate-streaming)**: Learn about HLS and MPEG-DASH support
- **[Video Transformations](/video-transformation)**: Apply transformations to your videos


---

# Source: /video-player/supported-languages

---
title: Supported Languages
description: Complete list of languages supported for translation in ImageKit Video Player subtitles and chapters.
---

ImageKit Video Player supports **100+ languages** for translation. Use the language codes below when configuring translations in your `textTracks` [configuration](/video-player/subtitles-and-chapters#auto-generated-text-track-options).

## Supported Languages

{% table %}
- **Language Code** {% width="20%" %}
- **Language Name** {% width="80%" %}
---
- `en`
- English
---
- `es`
- Spanish
---
- `fr`
- French
---
- `de`
- German
---
- `it`
- Italian
---
- `pt`
- Portuguese
---
- `nl`
- Dutch
---
- `hi`
- Hindi
---
- `ja`
- Japanese
---
- `zh`
- Chinese
---
- `fi`
- Finnish
---
- `ko`
- Korean
---
- `pl`
- Polish
---
- `ru`
- Russian
---
- `tr`
- Turkish
---
- `uk`
- Ukrainian
---
- `vi`
- Vietnamese
---
- `af`
- Afrikaans
---
- `sq`
- Albanian
---
- `am`
- Amharic
---
- `ar`
- Arabic
---
- `hy`
- Armenian
---
- `as`
- Assamese
---
- `az`
- Azerbaijani
---
- `ba`
- Bashkir
---
- `eu`
- Basque
---
- `be`
- Belarusian
---
- `bn`
- Bengali
---
- `bs`
- Bosnian
---
- `br`
- Breton
---
- `bg`
- Bulgarian
---
- `my`
- Burmese
---
- `ca`
- Catalan
---
- `hr`
- Croatian
---
- `cs`
- Czech
---
- `da`
- Danish
---
- `et`
- Estonian
---
- `fo`
- Faroese
---
- `gl`
- Galician
---
- `ka`
- Georgian
---
- `el`
- Greek
---
- `gu`
- Gujarati
---
- `ht`
- Haitian
---
- `ha`
- Hausa
---
- `haw`
- Hawaiian
---
- `he`
- Hebrew
---
- `hu`
- Hungarian
---
- `is`
- Icelandic
---
- `id`
- Indonesian
---
- `jw`
- Javanese
---
- `kn`
- Kannada
---
- `kk`
- Kazakh
---
- `km`
- Khmer
---
- `lo`
- Lao
---
- `la`
- Latin
---
- `lv`
- Latvian
---
- `ln`
- Lingala
---
- `lt`
- Lithuanian
---
- `lb`
- Luxembourgish
---
- `mk`
- Macedonian
---
- `mg`
- Malagasy
---
- `ms`
- Malay
---
- `ml`
- Malayalam
---
- `mt`
- Maltese
---
- `mi`
- Maori
---
- `mr`
- Marathi
---
- `mn`
- Mongolian
---
- `ne`
- Nepali
---
- `no`
- Norwegian
---
- `nn`
- Norwegian Nynorsk
---
- `oc`
- Occitan
---
- `pa`
- Panjabi
---
- `ps`
- Pashto
---
- `fa`
- Persian
---
- `ro`
- Romanian
---
- `sa`
- Sanskrit
---
- `sr`
- Serbian
---
- `sn`
- Shona
---
- `sd`
- Sindhi
---
- `si`
- Sinhala
---
- `sk`
- Slovak
---
- `sl`
- Slovenian
---
- `so`
- Somali
---
- `su`
- Sundanese
---
- `sw`
- Swahili
---
- `sv`
- Swedish
---
- `tl`
- Tagalog
---
- `tg`
- Tajik
---
- `ta`
- Tamil
---
- `tt`
- Tatar
---
- `te`
- Telugu
---
- `th`
- Thai
---
- `bo`
- Tibetan
---
- `tk`
- Turkmen
---
- `ur`
- Urdu
---
- `uz`
- Uzbek
---
- `cy`
- Welsh
---
- `yi`
- Yiddish
---
- `yo`
- Yoruba
{% /table %}

## Usage Example

Use these language codes when configuring translations in your video player:

```javascript
textTracks: [
  {
    autoGenerate: true,
    translations: [
      { langCode: 'fr', label: 'French' },
      { langCode: 'de', label: 'German' },
      { langCode: 'hi', label: 'Hindi' },
      { langCode: 'ja', label: 'Japanese' }
    ]
  }
]
```

## Related Documentation

- **[Subtitles & Chapters](/video-player/subtitles-and-chapters)**: Complete guide to configuring subtitles, captions, and chapters
- **[Video Player Overview](/video-player/overview)**: Learn about all Video Player features


---

# Source: /video-player/shoppable-videos

---
title: Shoppable videos
description: Learn how to add product overlays and hotspots to videos using ImageKit Video Player.
---

Shoppable videos let you turn video content into interactive shopping experiences. Display product bars alongside your videos, highlight products at specific moments, and enable users to click through to purchase pages—all while maintaining engagement with your content.

{% ikvideoplayer 
  imagekitId="ikmedia" 
  src="https://ik.imagekit.io/ikmedia/docs/video-player/shoppable/video.mp4"
  config="shoppable-demo"
/%}

## Key features

- **Product bar display**: Show a customizable sidebar with product images, names, and details that sits alongside your video player
- **Time-based highlighting**: Automatically highlight products when they appear in your video content
- **Interactive overlays**: Add clickable hotspots directly on the video to pinpoint product locations in each frame
- **Flexible interactions**: Configure hover and click behaviors—navigate to product pages, switch images, seek to timestamps, or show custom overlays
- **Post-play carousel**: Keep viewers engaged after the video ends with a product carousel overlay
- **Consistent branding**: Apply [ImageKit transformations](/image-transformation) to standardize product images across size, format, quality, and effects

{% callout style="info" %}
**Use case:** Shoppable videos work best for fashion lookbooks, product demos, influencer content, and any video where viewers might want to purchase featured items.
{% /callout %}

## Setting up shoppable videos

Configure shoppable functionality through the `shoppable` parameter when [setting up video source](/video-player/overview#setting-up-video-source). The parameter accepts an object with UI configuration and a products array defining what to display and when.

### Shoppable options

Configure the shoppable video component's appearance and behavior:

{% table %}
- **Parameter** {% width="50%" %}
- **Description** {% width="50%" %}
---
- products **(required)**  
  `object[]`
- Array of products to display in the products bar. See [Product options](#product-options) below.
---
- startState  
  `'closed' | 'open' | 'openOnPlay'`
- Initial state of the product bar when the video loads.  
  Default: `'openOnPlay'`
---
- toggleIconUrl  
  `string`
- URL of the icon used to toggle the product bar visibility
---
- width  
  `number`
- Width of the product bar as a percentage of the player's total width.  
  Default: `20`
---
- autoClose  
  `number`
- Number of seconds before the product bar automatically closes after no user interaction.  
  Default: `2`
---
- transformation  
  `object[]`
- ImageKit transformations to apply to all product images in the products bar. Use this to standardize size, format, quality, or add brand overlays and effects. See [Image Transformations](/image-transformation).
---
- showPostPlayOverlay  
  `boolean`
- Whether to display a product carousel overlay after the video ends.  
  Default: `false`
---
{% /table %}

### Product options

Define products in the `products` array. Each product object contains product information, when it appears in the video, interaction behavior, and optional video hotspots.

{% callout style="info" %}
**Tip:** Use `highlightTime` to automatically draw attention to products when they're visible in your video. Combine with `onHover` for preview images and `onClick` for purchase navigation.
{% /callout %}

{% table %}
- **Parameter** {% width="50%" %}
- **Description** {% width="50%" %}
---
- productId **(required)**  
  `number`
- Unique identifier for the product.
---
- productName **(required)**  
  `string`
- Name of the product.
---
- imageUrl **(required)**  
  `string`
- ImageKit-powered URL of the product image.
---
- highlightTime  
  `object`
- Time range when the product appears in the video.

  ```javascript
  {
    // Start time in seconds
    start: number;
    // End time in seconds
    end: number;
  }
  ```
---
- onClick  
  `object`
- Behavior when clicking the product in the products bar.

  ```javascript
  {
    // Action to perform
    action: 'overlay' | 'seek' | 'goto' | 'switch';
    // Optional pause behavior
    pause?: boolean | number;
    // Action-specific arguments
    args: {
      time?: string;        // For 'seek' action
      url?: string;         // For 'goto' or 'switch' action
      message?: string;     // For 'overlay' action
    };
  }
  ```
---
- onHover  
  `object`
- Behavior when hovering over the product in the products bar. Same structure as `onClick`:

  ```javascript
  {
    // Action to perform
    action: 'overlay' | 'seek' | 'goto' | 'switch';
    // Optional pause behavior
    pause?: boolean | number;
    // Action-specific arguments
    args: {
      time?: string;        // For 'seek' action
      url?: string;         // For 'goto' or 'switch' action
      message?: string;     // For 'overlay' action
    };
  }
  ```
---
- hotspots  
  `object[]`
- Array of clickable hotspots on the video itself. The hotspot appears when a user clicks a product from the products bar and the video pauses at the defined time.

  ```javascript
  {
    // Time when the hotspot appears (e.g., "00:02")
    time: string;
    // X position (e.g., "50%")
    x: string;
    // Y position (e.g., "50%")
    y: string;
    // URL to navigate to when clicked
    clickUrl: string;
    // Optional tooltip position
    tooltipPosition?: 'left' | 'right' | 'top' | 'bottom';
  }
  ```
{% /table %}

## Example

{% linetabs %}
{% linetab title="JavaScript" %}
```javascript
import { videoPlayer } from '@imagekit/video-player';
import '@imagekit/video-player/styles.css';

const player = videoPlayer('my-video', {
  imagekitId: 'YOUR_IMAGEKIT_ID'
});

player.src({
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  shoppable: {
    products: [
      {
        productId: 1,
        productName: 'Sunglasses',
        imageUrl: 'https://ik.imagekit.io/<your-imagekit-id>/product1.jpg',
        highlightTime: { start: 0, end: 5 },
        onClick: {
          action: 'goto',
          pause: true,
          args: { url: 'https://example.com/product/1' }
        }
      },
      {
        productId: 2,
        productName: 'Green Dress',
        imageUrl: 'https://ik.imagekit.io/<your-imagekit-id>/product2.jpg',
        highlightTime: { start: 2, end: 8 },
        onClick: {
          action: 'goto',
          pause: true,
          args: { url: 'https://example.com/product/2' }
        }
      },
      {
        productId: 3,
        productName: 'Brown Bag',
        imageUrl: 'https://ik.imagekit.io/<your-imagekit-id>/product3.jpg',
        highlightTime: { start: 7, end: 11 },
        onHover: {
          action: 'switch',
          args: {
            url: 'https://ik.imagekit.io/<your-imagekit-id>/product3-alt.jpg'
          }
        },
        onClick: {
          action: 'goto',
          pause: true,
          args: { url: 'https://example.com/product/3' }
        }
      }
    ],
    startState: 'openOnPlay',
    autoClose: 2,
    width: 20,
    transformation: [{ width: 200, height: 200 }]
  }
});
```
{% /linetab %}

{% linetab title="React" %}
```jsx
import { IKVideoPlayer } from '@imagekit/video-player/react';
import '@imagekit/video-player/styles.css';

function App() {
  const ikOptions = {
    imagekitId: 'YOUR_IMAGEKIT_ID'
  };

  const source = {
    src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  shoppable: {
    products: [
      {
        productId: 1,
        productName: 'Sunglasses',
          imageUrl: 'https://ik.imagekit.io/<your-imagekit-id>/product1.jpg',
        highlightTime: { start: 0, end: 5 },
          onClick: {
            action: 'goto',
            pause: true,
            args: { url: 'https://example.com/product/1' }
          }
        },
        {
          productId: 2,
          productName: 'Green Dress',
          imageUrl: 'https://ik.imagekit.io/<your-imagekit-id>/product2.jpg',
          highlightTime: { start: 2, end: 8 },
          onClick: {
            action: 'goto',
            pause: true,
            args: { url: 'https://example.com/product/2' }
          }
        },
        {
          productId: 3,
          productName: 'Brown Bag',
          imageUrl: 'https://ik.imagekit.io/<your-imagekit-id>/product3.jpg',
          highlightTime: { start: 7, end: 11 },
        onHover: {
            action: 'switch',
            args: {
              url: 'https://ik.imagekit.io/<your-imagekit-id>/product3-alt.jpg'
            }
        },
        onClick: {
          action: 'goto',
          pause: true,
            args: { url: 'https://example.com/product/3' }
        }
      }
      ],
      startState: 'openOnPlay',
      autoClose: 2,
      width: 20,
      transformation: [{ width: 200, height: 200 }]
    }
  };

  return (
    <IKVideoPlayer
      ikOptions={ikOptions}
      source={source}
    />
  );
}
```
{% /linetab %}

{% linetab title="Vue" %}
```jsx
<template>
  <IKVideoPlayer
    :ikOptions="ikOptions"
    :source="source"
  />
</template>

<script setup>
import { IKVideoPlayer } from '@imagekit/video-player/vue';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID'
};

const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  shoppable: {
    products: [
      {
        productId: 1,
        productName: 'Sunglasses',
        imageUrl: 'https://ik.imagekit.io/<your-imagekit-id>/product1.jpg',
        highlightTime: { start: 0, end: 5 },
        onClick: {
          action: 'goto',
          pause: true,
          args: { url: 'https://example.com/product/1' }
        }
      },
      {
        productId: 2,
        productName: 'Green Dress',
        imageUrl: 'https://ik.imagekit.io/<your-imagekit-id>/product2.jpg',
        highlightTime: { start: 2, end: 8 },
        onClick: {
          action: 'goto',
          pause: true,
          args: { url: 'https://example.com/product/2' }
        }
      },
      {
        productId: 3,
        productName: 'Brown Bag',
        imageUrl: 'https://ik.imagekit.io/<your-imagekit-id>/product3.jpg',
        highlightTime: { start: 7, end: 11 },
        onHover: {
          action: 'switch',
          args: {
            url: 'https://ik.imagekit.io/<your-imagekit-id>/product3-alt.jpg'
          }
        },
        onClick: {
          action: 'goto',
          pause: true,
          args: { url: 'https://example.com/product/3' }
        }
      }
    ],
    startState: 'openOnPlay',
    autoClose: 2,
    width: 20,
    transformation: [{ width: 200, height: 200 }]
  }
};
</script>
```
{% /linetab %}

{% linetab title="Astro" %}
```astro
---
import { IKVideoPlayer } from '@imagekit/video-player/astro';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID'
};

const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  shoppable: {
    products: [
      {
        productId: 1,
        productName: 'Sunglasses',
        imageUrl: 'https://ik.imagekit.io/<your-imagekit-id>/product1.jpg',
        highlightTime: { start: 0, end: 5 },
        onClick: {
          action: 'goto',
          pause: true,
          args: { url: 'https://example.com/product/1' }
        }
      },
      {
        productId: 2,
        productName: 'Green Dress',
        imageUrl: 'https://ik.imagekit.io/<your-imagekit-id>/product2.jpg',
        highlightTime: { start: 2, end: 8 },
        onClick: {
          action: 'goto',
          pause: true,
          args: { url: 'https://example.com/product/2' }
        }
      },
      {
        productId: 3,
        productName: 'Brown Bag',
        imageUrl: 'https://ik.imagekit.io/<your-imagekit-id>/product3.jpg',
        highlightTime: { start: 7, end: 11 },
        onHover: {
          action: 'switch',
          args: {
            url: 'https://ik.imagekit.io/<your-imagekit-id>/product3-alt.jpg'
          }
        },
        onClick: {
          action: 'goto',
          pause: true,
          args: { url: 'https://example.com/product/3' }
        }
      }
    ],
    startState: 'openOnPlay',
    autoClose: 2,
    width: 20,
    transformation: [{ width: 200, height: 200 }]
  }
};
---

<IKVideoPlayer
  ikOptions={ikOptions}
  source={source}
/>
```
{% /linetab %}
{% /linetabs %}

## Best practices

- **Time products strategically**: Set `highlightTime` ranges when products are clearly visible in the video. Overlapping times are fine—viewers can see multiple products simultaneously.
- **Use clear product images**: Apply consistent transformations (like `{ width: 200, height: 200 }`) to ensure all product images are the same size and properly formatted.
- **Combine hover and click**: Use `onHover` with `action: 'switch'` to show alternate product views, and `onClick` with `action: 'goto'` to navigate to product pages.
- **Test interaction timing**: Set appropriate `pause` durations. Pausing for 2-3 seconds on click gives users time to read product details before navigating away.
- **Enable post-play overlay**: Set `showPostPlayOverlay: true` to display a product carousel after the video ends, giving viewers one more chance to explore products.
- **Add video hotspots**: Use hotspots to highlight product locations directly on the video frame, making it easier for viewers to identify which item you're showcasing.
- **Optimize for mobile**: Keep product bar width reasonable (`width: 20-25`) to ensure the video remains visible on smaller screens.

## Related features

- **[Video player overview](/video-player/overview)**: Learn about basic video player setup and configuration
- **[Subtitles & chapters](/video-player/subtitles-and-chapters)**: Add text tracks and chapter markers to your videos
- **[Playlist & recommendations](/video-player/playlist-and-recommendations)**: Create playlists or show recommended videos
- **[Image transformations](/image-transformation)**: Learn about transforming product images for consistent appearance


---

# Source: /video-player/playlist-and-recommendations

---
title: Playlist & recommendations
description: Learn how to create playlists and show video recommendations using ImageKit Video Player.
---

Create engaging video experiences with playlists that play multiple videos in sequence, or show personalized recommendations when a video ends. Both features help keep viewers engaged and increase watch time.

## Playlist

Playlists let you queue multiple videos with a scrollable widget that viewers can use to navigate between videos. Perfect for tutorial series, episodic content, or curated collections.

{% ikvideoplayer config="playlist-demo" /%}

{% callout style="info" %}
**Tip:** Use the `info` property in source options to provide titles and descriptions for each video. These appear in the playlist widget and upcoming video previews.
{% /callout %}

### Playlist Setup

{% linetabs %}

{% linetab title="JavaScript" %}
The `player.playlist()` method accepts a `sources` array and `options` object.

```javascript
import { videoPlayer } from '@imagekit/video-player';
import '@imagekit/video-player/styles.css';

const player = videoPlayer('my-video', {
  imagekitId: 'YOUR_IMAGEKIT_ID'
});

const playlistManager = player.playlist({
  sources: [
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/video1.mp4',
      // ... Rest of the SourceOptions
    },
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/video2.mp4'
    }
  ],
  options: {
    autoAdvance: 3, // Auto-advance after 3 seconds
    repeat: true, // Loop playlist
    presentUpcoming: 10, // Show "next up" 10 seconds before end
    widgetProps: {
      direction: 'vertical' // or 'horizontal'
    }
  }
});

// Load and play the first video
playlistManager.loadFirstItem();
```
{% /linetab %}

{% linetab title="React" %}
The `playlist` prop accepts a `sources` array and `options` object.

```jsx
import { IKVideoPlayer } from '@imagekit/video-player/react';
import '@imagekit/video-player/styles.css';

function App() {
  const ikOptions = {
    imagekitId: 'YOUR_IMAGEKIT_ID'
  };

  const playlist = {
    sources: [
      {
        src: 'https://ik.imagekit.io/<your-imagekit-id>/video1.mp4',
        // ... Rest of the SourceOptions
      },
      {
        src: 'https://ik.imagekit.io/<your-imagekit-id>/video2.mp4'
      }
    ],
    options: {
      autoAdvance: 3,
      repeat: true,
      presentUpcoming: 10,
      widgetProps: {
        direction: 'vertical' // or 'horizontal'
      }
    }
  };

  return (
    <IKVideoPlayer
      ikOptions={ikOptions}
      playlist={playlist}
    />
  );
}
```
{% /linetab %}

{% linetab title="Vue" %}
The `playlist` prop accepts a `sources` array and `options` object.

```jsx
<template>
  <IKVideoPlayer
    :ikOptions="ikOptions"
    :playlist="playlist"
  />
</template>

<script setup>
import { IKVideoPlayer } from '@imagekit/video-player/vue';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID'
};

const playlist = {
  sources: [
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/video1.mp4',
      // ... Rest of the SourceOptions
    },
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/video2.mp4'
    }
  ],
  options: {
    autoAdvance: 3,
    repeat: true,
    presentUpcoming: 10,
    widgetProps: {
      direction: 'vertical' // or 'horizontal'
    }
  }
};
</script>
```
{% /linetab %}

{% linetab title="Astro" %}
The `playlist` prop accepts a `sources` array and `options` object.

```astro
---
import { IKVideoPlayer } from '@imagekit/video-player/astro';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID'
};

const playlist = {
  sources: [
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/video1.mp4',
      // ... Rest of the SourceOptions
    },
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/video2.mp4'
    }
  ],
  options: {
    autoAdvance: 3,
    repeat: true,
    presentUpcoming: 10,
    widgetProps: {
      direction: 'vertical' // or 'horizontal'
    }
  }
};
---

<IKVideoPlayer
  ikOptions={ikOptions}
  playlist={playlist}
/>
```
{% /linetab %}

{% /linetabs %}

{% table %}
- **Parameter** {% width="50%" %}
- **Description** {% width="50%" %}
---
- sources  
  `object[]`
- Array of video sources. See [Source options](/video-player/overview#source-options) for more details.
---
- options  
  `object`
- Playlist configuration options (see [Playlist options](#playlist-options) below).
{% /table %}

### Playlist options

{% table %}
- **Parameter** {% width="50%" %}
- **Description** {% width="50%" %}
---
- autoAdvance  
  `number | false`
- Number of seconds to wait before automatically advancing to the next video, or `false` to disable auto-advance. Set to `0` to advance immediately when the current video ends.
---
- repeat  
  `boolean`
- Automatically restart the playlist from the beginning when it reaches the end.  
  Default: `false`
---
- presentUpcoming  
  `boolean | number`
- Display a thumbnail preview of the upcoming video. Set to `true` to show 10 seconds before the current video ends, or specify a number for a custom delay in seconds.
---
- widgetProps  
  `object`
- Configuration options for the playlist widget.

  ```javascript
  {
    // Position of the widget relative to the player
    direction: 'vertical' | 'horizontal';
  }
  ```

  Default: `{ direction: 'vertical' }` (widget on the right side; use `'horizontal'` to display below the player)
{% /table %}

### Playlist manager methods

After calling `player.playlist(options)`, you get a `PlaylistManager` instance with the following methods:

{% table %}
- **Method** {% width="50%" %}
- **Description** {% width="50%" %}
---
- loadFirstItem()  
  `boolean`
- Set the first video in the playlist as the current source (does not start playback). Returns `true` if successfully set, `false` otherwise.
---
- loadNextItem()  
  `boolean`
- Set the next video in the playlist as the current source (does not start playback). Returns `true` if successfully set, `false` otherwise.
---
- loadPreviousItem()  
  `boolean`
- Set the previous video in the playlist as the current source (does not start playback). Returns `true` if successfully set, `false` otherwise.
---
- playAtIndex(index: number)  
  `void`
- Play a specific video in the playlist by index (0-based).
---
- playNext()  
  `void`
- Play the next video in the playlist.
---
- playPrevious()  
  `void`
- Play the previous video in the playlist.
---
- getItems()  
  `object[]`
- Get an array of all playlist items. Returns an array of [Source options](/video-player/overview#source-options) objects.
---
- autoAdvanceDelay(delay?: number | false)  
  `number | null | void`
- Get or set the auto-advance delay. Get if no parameter, set if parameter provided.
  
  **Return values:**
  - `null` → auto-advance disabled/not configured
  - `0` → enabled with immediate advance (no delay)
  - `> 0` → enabled, wait N seconds
{% /table %}


## Recommendations

Recommendations display suggested videos when the current video ends, encouraging viewers to continue watching. Great for suggesting related content, next episodes, or personalized picks.

{% ikvideoplayer config="recommendations-demo" /%}

### Recommendations setup

Add recommendation sources to the `recommendations` array when configuring the video source. Each recommendation source is a [Source options](/video-player/overview#source-options) object.

{% linetabs %}

{% linetab title="JavaScript" %}
```javascript
player.src({
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  recommendations: [
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/video2.mp4',
      info: { title: 'Recommended Video 1' },
      // ... Rest of the SourceOptions
    },
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/video3.mp4',
      info: { title: 'Recommended Video 2' }
    }
  ]
});
```
{% /linetab %}

{% linetab title="React" %}
```jsx
import { IKVideoPlayer } from '@imagekit/video-player/react';
import '@imagekit/video-player/styles.css';

function App() {
  const ikOptions = {
    imagekitId: 'YOUR_IMAGEKIT_ID'
  };

  const source = {
    src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
    recommendations: [
      {
        src: 'https://ik.imagekit.io/<your-imagekit-id>/video2.mp4',
        info: { title: 'Recommended Video 1' },
        // ... Rest of the SourceOptions
      },
      {
        src: 'https://ik.imagekit.io/<your-imagekit-id>/video3.mp4',
        info: { title: 'Recommended Video 2' }
      }
    ]
  };

  return (
    <IKVideoPlayer
      ikOptions={ikOptions}
      source={source}
    />
  );
}
```
{% /linetab %}

{% linetab title="Vue" %}
```jsx
<template>
  <IKVideoPlayer
    :ikOptions="ikOptions"
    :source="source"
  />
</template>

<script setup>
import { IKVideoPlayer } from '@imagekit/video-player/vue';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID'
};

const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  recommendations: [
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/video2.mp4',
      info: { title: 'Recommended Video 1' },
      // ... Rest of the SourceOptions
    },
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/video3.mp4',
      info: { title: 'Recommended Video 2' }
    }
  ]
};
</script>
```
{% /linetab %}

{% linetab title="Astro" %}
```astro
---
import { IKVideoPlayer } from '@imagekit/video-player/astro';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID'
};

const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  recommendations: [
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/video2.mp4',
      info: { title: 'Recommended Video 1' },
      // ... Rest of the SourceOptions
    },
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/video3.mp4',
      info: { title: 'Recommended Video 2' }
    }
  ]
};
---

<IKVideoPlayer
  ikOptions={ikOptions}
  source={source}
/>
```
{% /linetab %}

{% /linetabs %}

### Recommendations in playlists

If you explicitly specify recommendations for sources in your playlist and `autoAdvance` is `false`, those recommendations are displayed in the recommendations pane. If a viewer selects one of the recommendations, they exit the playlist context.

```javascript
const playlistManager = player.playlist({
  sources: [
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/video1.mp4',
      info: { title: 'Video 1' },
      recommendations: [
        {
          src: 'https://ik.imagekit.io/<your-imagekit-id>/video4.mp4',
          info: { title: 'Recommended after Video 1' }
        }
      ]
    },
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/video2.mp4',
      info: { title: 'Video 2' }
    }
  ],
  options: {
    autoAdvance: false // Disable auto-advance to show recommendations
  }
});
```

{% callout style="info" %}
**Note:** When `autoAdvance` is enabled in playlists, recommendations are not shown because the player automatically moves to the next video in the queue.
{% /callout %}

## Best practices

- **Add video metadata**: Always include `info.title` and `info.description` for playlist videos. This helps viewers understand what's coming next and makes the playlist widget more informative.
- **Use appropriate auto-advance timing**: Set `autoAdvance` to 3-5 seconds to give viewers time to decide if they want to continue or choose a different video. Setting it to `0` works well for seamless playlists.
- **Enable upcoming previews**: Use `presentUpcoming: 10` to show what's next 10 seconds before the current video ends, giving viewers a smooth transition.
- **Choose the right widget direction**: Use `direction: 'vertical'` for desktop-focused experiences with wide screens, and `direction: 'horizontal'` for mobile-friendly layouts.
- **Limit recommendation count**: Show 3-5 recommendations maximum. Too many choices can overwhelm viewers and reduce engagement.
- **Leverage playlist manager**: Use `playlistManager.getItems()` and `playlistManager.playAtIndex()` to build custom navigation or chapter selection interfaces.
- **Combine with global transformations**: Apply consistent transformations at the player level to ensure all playlist videos have uniform quality and formatting.

## Related features

- **[Video player overview](/video-player/overview)**: Learn about basic video player setup and source configuration
- **[Subtitles & chapters](/video-player/subtitles-and-chapters)**: Add text tracks and chapter markers to playlist videos
- **[Shoppable videos](/video-player/shoppable-videos)**: Make playlist videos shoppable with product overlays
- **[Video transformations](/video-transformation)**: Apply transformations consistently across all playlist videos


---

# Source: /dam/overview

---
title: Digital Asset Management
description: Move beyond Drive and Dropbox to a DAM that customizes content organization, simplifies asset search, and streamlines how teams collaborate every day.
---

ImageKit offers a built-in full-fledged Digital Asset Management (DAM) system. Get a single, cloud-based repository to streamline the storage, management, and distribution of product images, videos, banners, sales decks, social media and advertising graphics, and more. Level up your current asset storage to ImageKit's DAM.

{% video loop=true controls=false autoplay=true playsinline=true muted=true src="https://ik.imagekit.io/ikmedia/Graphics/2024%20Website%20Graphics/Centralised%20DAM/A%20secure%20home%20for%20all%20your%20assets.mp4?updatedAt=17140475241531&tr=w-1250" /%}

## Interactive Demo

{% storylane url="https://app.storylane.io/demo/7d7gfswompqq" /%}

## Features Overview

ImageKit DAM provides the following features:

- [Upload assets](/dam/upload-assets) - You can upload images, videos, PSD, AI, or any file in the media library using the intuitive user interface (and also using the API). You can upload assets in bulk, drag and drop assets, or from external sources like Google Drive, Dropbox, OneDrive, Box, and more.
- [Manage assets](/dam/manage-assets) - Organize your assets in folders and subfolders. Create [virtual collections](/dam/media-collection) to group assets based on your requirements. Add tags manually or use AI to categorize them. Create custom metadata fields to store additional information about the assets. Use [AI tasks](/dam/ai-tasks) to automate controlled vocabulary tagging and custom metadata updates.
- [Search assets](/dam/search) - Search millions of assets in a fraction of a second. ImageKit DAM provides a powerful search experience, from simple auto-suggestions to advanced search queries. You can also use AI-powered visual search to find assets based on their content.
- [Saved searches and bookmarks](/dam/saved-searches-and-bookmarks) - Save your frequently used search queries and filters for quick access, and bookmark any links for easy future reference.
- [Generate images via text prompt](/dam/generate-images-via-text-prompt) - Effortlessly create unique visuals by simply typing text within ImageKit's Digital Asset Management (DAM) platform.
- [Access control and collaboration](/dam/sharing-and-collaboration) - Share assets with your team members or external stakeholders. Set permissions on folders, collections, or individual files to control who can view, edit, or delete them. [Add comments to assets](/dam/comments-on-assets) to provide feedback or context. Receive notifications on new comments and mentions on threads you are watching and when assets are shared with you in the [Notification center](/dam/notification-center).
- Publish assets - [Embed videos](/dam/embed-video), images, and other assets to your website or app. Create [public sharable links](/dam/public-links) of files, folders, or virtual collections to share with your team or external stakeholders.
- [Edit assets](/dam/edit-images) - Remove background, crop, resize, or add basic text/image overlays with a few clicks.
- [Embed Media library in your CMS](/dam/embeddable-media-library-widget) - Embed ImageKit media library in your CMS or any other web application to manage assets directly from your application.
- [Desktop app for DAM](/dam/app) - Upload, browse, search, and drag and drop files to your system or applications directly from your desktop.
- [History and Audit logs](/dam/history-and-audit-logs) - View the history of all the changes made to an asset. View audit logs to see who made the changes and when.
- [Backup](#backup-media-library) - You can configure automatic backup of your assets to your AWS S3 bucket.
- [Path policy](/dam/path-policy) - Define path-level configurations for custom metadata fields; modify and validate upload API request parameters, and validate media library API request parameters.

## Supported file types

ImageKit DAM supports all kinds of files, including images, videos, PSD, AI, PDF, DOC, XLS, PPT, and others.


## Points to consider before using the DAM
ImageKit DAM offers many different features, as mentioned below. However, before getting to the features and how they work, it is essential to answer a few questions about how you and your team will use the DAM and consider a few points to make the most of it.

### DAM Users
A DAM is meant to work with both internal and external stakeholders. However, not everyone needs to log in to the DAM. We have covered some cases below.

You can add and manage users and groups from the [User Management](/user-management) page.

- Does someone need access to upload, manage files, or share content - Add them as a user to the DAM.
- If they need a view-only access, 
    - Will they need access to [advanced search](/dam/search#advanced-searching) to find specific files? Add them as a user to the DAM. 
    - Would it be okay to share a small number of files and folders using links with them without the ability to search? There is no need to add them to the DAM, as you can use [Public Links](/dam/public-links). External PR agencies or marketing agencies can fall into this category.

### Access control in the DAM

To maintain security, follow the principle of least access. Users should start with access to nothing and then be granted access to only specific files and folders useful to them.

- Except for Account Administrators or DAM managers who need access to the entire DAM, everyone else should be added as a [Media Library Restricted User](/user-management#user-roles).
- Add all restricted users to relevant [user groups or teams](/user-management#user-groups), such as the Marketing, Graphics, Technology team, etc. Team members often have the exact access requirements, and using these groups makes granting access easier.
- Grant individuals or teams the lowest [access level](/dam/sharing-and-collaboration#permissions) to complete their work. Access should only be given to specific folders to prevent misuse, accidental deletions, or overwrites. For example, your graphics team would want access to upload files to a folder and can be given Contribute access. But, your technology team might only need access to view these files and should be given view-only access.

{% callout style="info" %}
You can also monitor changes in your DAM at an account and asset level using [DAM audit Logs](/dam/history-and-audit-logs).
{% /callout %}

### What is stored in the DAM
As a general rule, the DAM should contain anything that should be available centrally to multiple team members or will be needed for a decent amount of time. For example, a Photoshop file that can be used to create multiple banners in the future can be stored in the DAM, and the entire graphics team will have access to it. 

However, let's say you recorded some raw video footage to create a final video for your Instagram channel, and the raw videos are useless after the final video has been produced. If that's the case, then the raw footage can be omitted from the DAM, and only the final video can be uploaded to the DAM.

You can also define specific constraints on permitted file types (e.g., allowing only MP4 files in a specific folder), set maximum file size limits, or pre-process files before they are stored using [upload functions within Path Policies](/dam/path-policy#examples). This prevents your storage from being cluttered with unoptimized files and ensures that all uploaded assets meet your technical standards before they are even stored.

### File naming and versioning
You can set ImageKit to create unique file names to prevent accidental overwrites. Or, if you want to preserve the file names and version history, like while iterating on a banner, you can set ImageKit to create a new file version when a file with the same name is uploaded. You can also reject the file upload if a file with the same name exists in the folder where you are uploading it. 

These [upload settings](/dam/upload-assets#upload-settings) can be enforced at the account level or modified at the time of upload. Which setting to select depends on your business requirements and workflows. 

### Organizing content in the DAM
- Start by creating [folders](/dam/upload-assets#create-new-folder) for your teams to work on. Do not upload content directly to the root of the DAM.
- Folders can be arranged in several different ways. The method you adopt should depend on how your teams work daily and which structure will make it easier for them to accomplish their goals. Here are a few options, starting with the team, the project, or the content type as the base folder.

![Folder Structure Ideas](https://ik.imagekit.io/ikmedia/docs_images/media-library/overview/Folder_structure_ideas.png?updatedAt=1718032279369)

- What will make it easier for your team to search for specific files? Do you often have to look for content associated with a specific product ID, banners associated with a specific city, or some other parameter that cannot be part of the file or folder name? If so, you can simplify the search using [Custom Metadata](/dam/custom-metadata). This allows you to associate searchable structured data with your assets, aligning with how your teams search for files.

- Different asset types require specific metadata. For example, a product image needs a Product ID, whereas a promotional banner might only require the campaign name and year. You can create custom metadata fields and use [Path policies](/dam/path-policy) to define which fields are applicable or mandatory at the folder level. This allows you to manage diverse asset types within a single DAM while maintaining a highly organized, customized structure for each asset type.

{% callout style="info" %}
ImageKit also offers [AI-based text and visual search](/dam/search#visual-search), an [autocompleter](/dam/search#search-autocomplete), and automatic [AI-powered image tagging](/dam/tagging-media-assets#business-specific-tagging-using-ai-tasks) to make organizing and finding assets easier. Check these out, along with custom metadata, to implement the right organization and search methods for your teams.
{% /callout %}

### Protect Critical Assets
Once your files are in use, you want to prevent accidental changes or deletions. To safeguard critical content, you can implement [validate functions within Path policies](/dam/path-policy#examples) to prevent unauthorized or accidental changes. These functions allow you to enforce strict rules at the folder level, effectively blocking users from deleting, renaming, or modifying high-value files. By establishing these guardrails, you ensure that core brand assets remain permanent and consistent, protecting the integrity of your library.

## Integrating DAM with internal apps & CMS
ImageKit offers a couple of ways to integrate the ImageKit DAM directly with your internal CMS and applications.

### Integration using the embeddable Media Library widget

The [Media Library widget](https://github.com/imagekit-developer/embeddable-media-library) makes it easy to integrate ImageKit DAM into your CMS or any web application. You can access all assets stored in your Media Library, along with all search and collaboration options, and insert them directly in your existing CMS or application using this widget. You can [learn more about this widget here](/dam/embeddable-media-library-widget).

### Integration using Headless DAM APIs

For more advanced custom integrations, you can also use ImageKit DAM as a headless DAM using its APIs. You can use the ImageKit API to programmatically upload, organize, search, and manage assets. You can also use the ImageKit SDKs to integrate ImageKit DAM with your application. You can find the [API reference](/api-reference) here.

## DAM File Events

ImageKit can send real-time notifications to your configured webhook URL when changes happen to files in DAM. This allows you to keep your systems in sync with ImageKit DAM automatically.

Before receiving file-related events, you need to [configure webhooks](/webhooks) in your ImageKit account.

The following DAM file events are available:

- `file.created`
- `file.updated`
- `file.deleted`
- `file-version.created`
- `file-version.deleted`

### file.created

This event is triggered when a file is uploaded successfully to DAM.

Example payload looks like below:

```js
{
  "id": "d646f6cc-6383-4fbd-b4ec-eddd5867a5c2",
  "created_at": "2026-03-31T10:56:59.090Z",
  "type": "file.created",
  "data": {
    "type": "file",
    "name": "10.webp",
    "createdAt": "2026-03-31T10:56:58.663Z",
    "updatedAt": "2026-03-31T10:56:59.090Z",
    "fileId": "69cba87a323984bad7b8fbdc",
    "tags": null,
    "AITags": null,
    "versionInfo": {
      "id": "69cba87a323984bad7b8fbdc",
      "name": "Version 1"
    },
    "embeddedMetadata": {
      "ImageWidth": 461,
      "ImageHeight": 600,
      "ImageSize": "461x600",
      "Megapixels": 0.277
    },
    "isPublished": true,
    "customCoordinates": null,
    "customMetadata": {},
    "isPrivateFile": false,
    "url": "https://ik.imagekit.io/rtsmrscto/check%203/10.webp?updatedAt=1774954619090",
    "thumbnail": "https://ik.imagekit.io/rtsmrscto/check%203/10.webp?updatedAt=1774954619090&tr=n-ik_ml_thumbnail",
    "fileType": "image",
    "filePath": "/check 3/10.webp",
    "height": 600,
    "width": 461,
    "size": 30164,
    "hasAlpha": false,
    "mime": "image/webp"
  }
}
```


### file.updated

This event is triggered when a file is updated successfully. The payload inside `data` reflects the current state of the file.

Example payload looks like below:

```js
{
  "id": "d646f6cc-6383-4fbd-b4ec-eddd5867a5c2",
  "created_at": "2026-03-31T10:56:59.090Z",
  "type": "file.updated",
  "data": {
    "type": "file",
    "name": "10.webp",
    "createdAt": "2026-03-31T10:56:58.663Z",
    "updatedAt": "2026-03-31T10:56:59.090Z",
    "fileId": "69cba87a323984bad7b8fbdc",
    "tags": null,
    "AITags": null,
    "versionInfo": {
      "id": "69cba87a323984bad7b8fbdc",
      "name": "Version 1"
    },
    "embeddedMetadata": {
      "ImageWidth": 461,
      "ImageHeight": 600,
      "ImageSize": "461x600",
      "Megapixels": 0.277
    },
    "isPublished": true,
    "customCoordinates": null,
    "customMetadata": {},
    "isPrivateFile": false,
    "url": "https://ik.imagekit.io/rtsmrscto/check%203/10.webp?updatedAt=1774954619090",
    "thumbnail": "https://ik.imagekit.io/rtsmrscto/check%203/10.webp?updatedAt=1774954619090&tr=n-ik_ml_thumbnail",
    "fileType": "image",
    "filePath": "/check 3/10.webp",
    "height": 600,
    "width": 461,
    "size": 30164,
    "hasAlpha": false,
    "mime": "image/webp"
  }
}
```


### file.deleted

This event is triggered when a file is deleted from DAM.

Example payload looks like below:

```js
{
  "id": "85c4d6d0-2ac3-4e30-99c8-014ced4e66d0",
  "created_at": "2026-03-31T08:00:20.071Z",
  "type": "file.deleted",
  "data": {
    "fileId": "69b3cc1d39bcd959c57bd45d"
  }
}
```


### file-version.created

This event is triggered when a [new version](/dam/asset-versioning) of a file is created in DAM. The payload inside `data` reflects the current state of the file version.

Example payload looks like below:

```js
{
  "id": "6fc3172f-e3b0-47f1-a226-5b56e4ea3540",
  "created_at": "2026-03-31T11:00:59.141Z",
  "type": "file-version.created",
  "data": {
    "type": "file-version",
    "name": "10.webp",
    "createdAt": "2026-03-31T11:00:59.141Z",
    "updatedAt": "2026-03-31T11:00:59.141Z",
    "fileId": "69cba87a323984bad7b8fbdc",
    "tags": null,
    "AITags": null,
    "versionInfo": {
      "id": "69cba87a323984bad7b8fbdc",
      "name": "Version 1"
    },
    "embeddedMetadata": {
      "ImageWidth": 461,
      "ImageHeight": 600,
      "ImageSize": "461x600",
      "Megapixels": 0.277
    },
    "isPublished": true,
    "customCoordinates": null,
    "customMetadata": {},
    "isPrivateFile": false,
    "url": "https://ik.imagekit.io/rtsmrscto/check%203/10.webp?ik-obj-version=d.lgDXw1__DLy5HQyPXX9IyAMXtS1K3K&updatedAt=1774954859141",
    "thumbnail": "https://ik.imagekit.io/rtsmrscto/check%203/10.webp?ik-obj-version=d.lgDXw1__DLy5HQyPXX9IyAMXtS1K3K&updatedAt=1774954859141&tr=n-ik_ml_thumbnail",
    "fileType": "image",
    "filePath": "/check 3/10.webp",
    "height": 600,
    "width": 461,
    "size": 30164,
    "hasAlpha": false,
    "mime": "image/webp"
  }
}
```

### file-version.deleted

This event is triggered when a file version is deleted from DAM.

Example payload looks like below:

```js
{
  "id": "85c4d6d0-2ac3-4e30-99c8-014ced4e66d0",
  "created_at": "2026-03-31T08:00:20.071Z",
  "type": "file-version.deleted",
  "data": {
    "fileId": "69b3cc1d39bcd959c57bd45d",
    "versionId": "69b3cc3d39bcd959c57bfe5d"
  }
}
```

## Desktop app for creative teams

ImageKit provides a [native app](/dam/app) that allows users to quickly access its Digital Asset Management (DAM) platform on Windows and MacOS and use the assets in the DAM with applications such as Photoshop, Figma, Canva, and more. 

The app enables you to browse and search assets, drag and drop them in the application of your choice, create new folders, upload files and folders, and perform operations such as copying file URLs and downloading files. You can also select and open assets directly on the web platform for advanced operations. With drag-and-drop functionality, you can quickly move files between the app and other applications, ensuring a seamless workflow.

## Backup Media Library

You can backup all media library assets in your S3 bucket by setting up an active backup.

Go to the [backup settings page](https://imagekit.io/dashboard/settings/backup-bucket).

![Configure Media library backup](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/backup-bucket-form.png?tr=w-1600>)

Here you have to enter the S3 bucket credentials with write permission.

Learn how to grant write access to an S3 bucket - [https://aws.amazon.com/blogs/security/writing-iam-policies-how-to-grant-access-to-an-amazon-s3-bucket/](https://aws.amazon.com/blogs/security/writing-iam-policies-how-to-grant-access-to-an-amazon-s3-bucket/)

Once the settings are saved, all newly uploaded files will also be uploaded to your backup bucket.

## FAQs

#### How do I restore previously uploaded files in the media library?

All newly uploaded files are automatically uploaded to your backup bucket. For old files, please raise a support ticket at [support@imagekit.io](mailto:support@imagekit.io). Based on the number of objects, additional charges may apply.

#### What happens if you overwrite an existing file?

ImageKit will overwrite the file in your backup bucket at the same location.

#### What happens when you delete a file or folder in the media library?

ImageKit will not delete the file or folder from the backup bucket.

#### What happens if you copy/move a file or folder in the media library?

ImageKit will not copy or move the files or folder in your backup bucket.

## AI extensions pricing

Using AI-powered [image generation](/dam/generate-images-via-text-prompt), [background removal](/dam/edit-images#ai-powered-background-removal), [auto-tagging](/dam/tagging-media-assets#ai-powered-auto-tagging), use of [AI Tasks](/dam/ai-tasks), or other AI extensions using the [ImageKit Editor](/dam/edit-images#imagekit-editor) consumes extension units. Your ImageKit plan includes a fixed amount of extension units that can be used to execute different extensions. Different extensions consume different amounts of extension units.

You can access the [full list of extensions and the extension units they consume](/docs/how-pricing-works#extension-units-pricing) here.

{% callout style="info" %}
**Maximum limit on extension usage** \
There is a maximum limit on how many extension units you can consume in a month. For free plans, the limit is [650 units](https://imagekit.io/plans/). For paid plans, refer to the [subscription details](https://imagekit.io/dashboard/billing/subscriptions) in the dashboard.
{% /callout %}


---

# Source: /dam/upload-assets

---
title: Upload assets
description: Learn how to upload files from the dashboard, use the Upload API, and migrate files using Rclone.
---

Depending on your use case, you can upload media assets to ImageKit using the following methods:

- **From the dashboard** - This is the easiest way to upload media assets to ImageKit. If you have a small number of assets, you can upload them directly from the dashboard. The UI lets you import assets from your local machine, a public URL, Dropbox, Google Drive, OneDrive, Unsplash, and Box. You can also upload the entire folders using this option. You can also [embed the Media Library as a widget](/dam/embeddable-media-library-widget) in your internal CMS and applications, so users don't have to switch to the ImageKit dashboard for media uploads.
- **Programmatically using API** - If you have a large number of assets and want a high degree of customization, you can use the [Upload API](/api-reference/upload-file/upload-file) to upload assets to ImageKit. Check out [quick start guides](/quick-start-guides) for different technologies.
- **Bulk migration using Rclone** - Rclone is a command-line program to manage and sync your files on 70+ cloud storage. ImageKit provides integration with Rclone and lets you upload assets to and from ImageKit DAM. [Learn more](/dam/bulk-upload-using-rclone).


Within the dashboard, navigate to the [Media Library](https://imagekit.io/dashboard/media-library) section. Click the New button in the top right corner and select File or Folder Upload.

![File upload button](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/new-file-upload.png?tr=w-1600)

You can upload files from your local machine, a public URL, Dropbox, Google Drive, OneDrive, Unsplash, Box, etc.

![Upload files from the dashboard](https://ik.imagekit.io/ikmedia/docs_images/media-library/overview/upload-files/upload-file.png?tr=w-1200)

By default, files are uploaded to the location you have navigated to in the media library. You can also create a new folder and upload files to that folder. But you can change all this in the upload dialog.
 
{% youtube 
 src="https://www.youtube.com/embed/NcI9guObk-M?si=eyVkcDmGvpf7fnqQ" 
 title="Uploading and downloading files in ImageKit" /%}

## Drag and drop files

You can also drag and drop files from your local machine to the media library.

{% youtube 
 src="https://www.youtube.com/embed/h8SZnU0pk1w?si=0o1N1bOxM9Vo9gHF"
 title="Drag and drop files" /%}

## Upload entire folder

You can also upload an entire folder by selecting the folder upload option.

![Upload folder](<https://ik.imagekit.io/ikmedia/docs_images/media-library/overview/upload-files/upload-folder-button.png?tr=w-1600>)

Learn about different [upload settings](#upload-settings) available during upload.

## Create new folder

Click on the New button on the top right corner and select New folder option. This will open a popup. Enter the folder name and click the submit. The new folder will be created in your current directory.

{% youtube 
    src="https://www.youtube.com/embed/cS2Hxld1jqk?si=r3kKcgwmj6DaDbUi" 
    title="Creating a new folder in ImageKit" /%}

## Upload settings

During upload, besides file name, you can set many other parameters like tags, auto AI tagging, AI background removal, custom metadata etc. You can apply pre-transformation to modify the images & videos before they are uploaded to ImageKit. You can apply post-transformation to eagerly transform the images & videos once upload is complete. All the parameters that are available in the [Upload API](/api-reference/upload-file/upload-file) are available in the dashboard as well.

You can configure the default upload settings in the [Media Library settings](https://imagekit.io/dashboard/settings/media-library). These settings will be applied to all the uploads from the dashboard.

![Default upload parameters](https://ik.imagekit.io/ikmedia/docs_images/extensions/default-upload-parameters.png?tr=w-1200)

During upload, you have the option to override these settings for the current batch of files. Click on the "Common settings" button to set the parameters for the current batch of files.

![Common settings for current batch of files](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/common-setting-button.png?tr=w-1600)

You also have the option to set the parameters for individual files. Click on the "Settings" icon for the file you want to set the parameters for.

![Settings for individual files](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/file-edit-button.png)

Here is the list of parameters that you can set during upload:

### Extensions

Extensions let you perform certain advanced operations on your assets during upload. To include an extension as an upload parameter, choose the corresponding extension checkbox and configure it as necessary. Extensions may consume additional extension units. Learn more about [pricing of extension units here](/how-pricing-works#extension-units-pricing).

![Extensions](https://ik.imagekit.io/ikmedia/docs_images/extensions/extension.png)

### Saved extensions

[Saved extensions](/dam/saved-extensions) are reusable extension configurations that can be applied during upload. Instead of configuring extensions repeatedly, you can select pre-configured saved extensions.

![Saved extension in upload settings](https://ikmedia.imagekit.io/docs_images/media-library/ai-tasks/upload-settings.png?updatedAt=1767860195861&tr=w-1600)

All new uploads will automatically use the selected saved extensions. You can also override this during individual uploads by selecting different saved extensions in the upload dialog.

### Custom focus area

Define an important area in the image during upload. This is an optional field and is only relevant for image-type files.

![Custom focus area](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/custom-focus-area.png?tr=w-1600)

{% callout style="info" %}
A custom focus area, like other upload parameters, is optional. However, if configured, all four fields x-coordinate, y-coordinate, height, and width become mandatory.
{% /callout %}

### Generate unique filenames with random suffixes

When this setting is activated, ImageKit automatically appends a random suffix to the file name. This prevents overwriting of existing files by ensuring each file name is unique.

### Overwrite files during upload

If a file with an identical name already exists at the destination, activating this setting will create a new version of the file. Conversely, if this setting is off and a file with the same name exists, an error will be generated.

### Set files as private during upload

This setting allows you to mark files as private. When this setting is enabled, the file is set as private, which limits access to the original file URL and unnamed transformations without signed URLs. Without the signed URL, only named transformations can be applied to private assets.

### Ensure files are published on upload

This option enables you to designate files as either published or unpublished. When activated, the file is marked as published. Files or file versions that are not published can only be accessed through the media library. [Learn more](/dam/drafts) about the draft assets.

### Overwrite AI tags during upload

If this feature is enabled and a file with the same name already exists at the target destination, the existing AI tags of the file will be replaced with new ones or removed if no tagging extension is applied. Conversely, if this setting is off, the existing AI tags of the file will be preserved in the new version.

### Overwrite user-set tags during upload

If this feature is enabled and a file with the same name already exists at the target destination, the user-set tags of the file will be replaced with new ones or removed if no tags are provided. Conversely, if this setting is off, the existing user-set tags of the file will be preserved in the new version.

### Overwrite custom metadata during the upload

If this feature is enabled and a file with the same name already exists at the target destination, the custom metadata of the file will be replaced with a new one or removed if no custom metadata is provided. Conversely, if this setting is off, the existing custom metadata of the file will be preserved in the new version.

### Pre-transformation

[Pre-transformation](/dam/pre-and-post-transformation-on-upload#pre-transformation) lets you modify image or video files before they're uploaded. You can only request a single pre-transformation on an asset. This feature is applicable exclusively to image and video files and any valid supported [image transformation](/image-transformation) or [video transformation](/video-transformation) can be applied to their respective files.

![Pre transformation](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/pre-transformation.png?tr=w-1600)

### Post transformation

[Post-transformations](/dam/pre-and-post-transformation-on-upload#post-transformation) help you eagerly generate transformations after an image or video file has been uploaded to ensure fast delivery to your users. This feature is applicable exclusively to image and video files. You can apply several post-transformations to an asset, with a maximum limit of five allowed post-transformations.

![Post transformation](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/post-transformation.png?tr=w-1600)

### Custom metadata

[Custom metadata](/dam/custom-metadata) fields can be used to store any type of data about your images in key-value pairs during upload. Before setting any custom metadata on an asset you have to create the field from media library settings or using custom metadata fields API.

### Tags

ImageKit enables you to include tags during the upload of assets, this setting is not available in the default upload parameters within the media library settings. Tags can be chosen from an auto-completer or created as new ones.

![Tags](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/tag-during-upload.png?tr=w-1600)

### Webhook URL

You can include a `webhookUrl` parameter during file upload. The final status of extensions after they have completed execution will be delivered to this endpoint as a POST request. This setting is not available in the default upload parameters within the media library settings. [Learn more](/webhooks) about receiving webhook notifications.

### File name

The file name cannot be configured as a default upload setting. During upload, file name is automatically set to the original file name. However, you can change it.

## Upload Widget
While ImageKit’s API can be integrated on the frontend to create a custom upload functionality, ImageKit also provides a ready-to-use upload widget using [Uppy](https://uppy.io/). You can find more about this [ImageKit file upload widget](https://github.com/imagekit-developer/imagekit-uppy-plugin) here. 

This widget lets the user pick files from the local file system, URLs, Dropbox, Google Drive, Instagram, etc., and upload them to your ImageKit Media Library.


---

# Source: /dam/generate-images-via-text-prompt

---
title: Generate Images Using Text Prompts in DAM
description: Easily create images from text prompts within ImageKit's Digital Asset Management (DAM) platform.
---

With ImageKit's latest feature, you can effortlessly generate images by simply typing in text prompts within the Digital Asset Management (DAM) platform. Create unique visuals, browse and search through your generated image history, upload them to your media library, and perform various actions on these images—all within a few clicks.

{% callout style="info" %}
**Note:** Behind the scene, it uses [AI transformations](/ai-transformations#generate-image-via-text-prompt) to generate images from your text prompts. Generating images consumes extension units. Learn more about pricing [here](/how-pricing-works#extension-units-pricing).
{% /callout %}

## How to Generate Images

To start creating images from text prompts:

1. Click on the **"Generate Images"** banner at the top of the DAM or select it from the **"New"** button.
2. (Optional) In the advanced settings, choose the number of images you want to generate and select the desired dimensions.
3. Enter your text prompt in the provided box.
4. Click **"Generate"**. Your images will be created and displayed once they're ready. It usually takes 20-30 seconds to generate images.

![Generate image via text prompt and advanced settings](https://ik.imagekit.io/ikmedia/docs_images/generate-images/generate-images.png?tr=w-1600)

## Browse and Search Your Generated Images

You can view the history of all generated images, search them by the text prompt used, and filter them by creation date or the user who generated them.

![List & search generated images](https://ik.imagekit.io/ikmedia/docs_images/generate-images/generated-image-history.png?tr=w-1600)

Click on the image or the "Expand image" icon to view more details of the generated image. In this view, you can perform actions such as deleting the image, saving it to the media library, copying the image URL, downloading it, or sharing the URL with others who have access to the media library. Moreover, you can navigate to the next or previous image in the list.

![Expanded view](https://ik.imagekit.io/ikmedia/docs_images/generate-images/generate-image-expand-view.png?tr=w-1600)

## Audit Logs

All actions related to image generation and deletion within the DAM are recorded in the [central audit logs](/central-audit-logs). Use these logs to track your image generation history.

## Access Control and Permissions

Only users with access to the DAM can use this feature.

A restricted user can generate images using text prompts but can only view and delete images they have generated. They can upload generated images to the media library if they have "Can Contribute" access to the relevant folders.


---

# Source: /dam/bulk-upload-using-rclone

---
title: Bulk upload using Rclone
description: Rclone is a command-line program to manage and sync files on 70+ cloud storage. ImageKit integrates with Rclone and lets you upload assets to and from ImageKit DAM.
---

Rclone is a command-line program to manage and sync files on 70+ cloud storage.

* [Configure Rclone](#configure-rclone)
* [Rclone commands reference](https://rclone.org/commands/) to manage and sync files.
* [ImageKit backend config reference](https://rclone.org/imagekit/)

## Configure Rclone

Download the latest version of Rclone from the [official website](https://rclone.org/downloads/) and follow the [installation instructions](https://rclone.org/install/). 

Before you begin, get your `urlEndpoint`, `publicKey`, and `privateKey` from your [ImageKit dashboard](https://imagekit.io/dashboard/developer/api-keys).

Run the following command to configure Rclone with ImageKit:

1. Open your command line interface and run `rclone config`.
2. Choose `n` for a new remote.
3. Name your new remote (eg: `imagekit-media-library`)
4. Select the number corresponding to `ImageKit.io` when prompted for storage type.

![](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/rclone/rclone-config-cmd.png?tr=w-300)

5. Enter your `urlEndpoint`, `publicKey`, and `privateKey` when prompted.

After you've completed the above steps, you should see a remote added, as shown below. Finally, select `q` to exit the interactive config session.

![](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/rclone/rclone-remotes.png?tr=w-300)

{% callout style="warning" %}
A few things to keep in mind when using Rclone with ImageKit:
1. Avoid the `sync` command, as it will delete files in the destination that are not in the source.
2. Avoid copying files to the root folder `/` inside ImageKit, as it can accidentally overwrite existing files. Always create specific folders and then copy files to them.
3. Pass the `--progress --no-check-dest` flag to see the progress of the file transfer and avoid checking the destination to speed up the process.
{% /callout %}

## Migrate files & folders from local file system to ImageKit

Rclone allows you to sync and transfer all your media assets from a local filesystem to your ImageKit's Media Library.

Let's say you want to copy all the files in a local folder at `/path/to/imagekit/folder` to ImageKit inside a new folder i.e., `testing`

```bash
cd /path/to/local/folder
rclone copy . imagekit-media-library:/testing
```

If you want to copy a single file, the command would look like this:

```bash
rclone copy /path/to/local/file.jpg imagekit-media-library:/testing
```

If the `testing` folder doesn't exist in ImageKit, it will be created automatically.

## Migrate files & folders from ImageKit to the local file system

Rclone also allows you to sync and bring all your media assets from ImageKit's Media Library to your local filesystem.

Let's say you want to copy all the files in ImageKit's folder `testing` to the local folder `/path/to/local/folder`. Ensure `/path/to/local/folder` exists before running the command.

```bash
rclone copy imagekit-media-library:/testing /path/to/local/folder
```

## Listing files in ImageKit

You can list all the files in a folder in ImageKit using the following command:

```bash
rclone ls imagekit-media-library:/testing
```
## Migrate files from S3 to ImageKit

Rclone also allows you to sync and bring all your media assets from S3 to ImageKit's Media Library.

Let's say you want to copy all the files in the S3 bucket `my-bucket` to ImageKit inside a new folder, i.e. `testing`.

First, configure your [Amazon S3](https://rclone.org/s3/) bucket as a remote in Rclone.

```bash
rclone copy s3:my-bucket imagekit-media-library:/testing
```


---

# Source: /dam/manage-assets

---
title: Manage files and folders
description: Learn how to copy, move, rename, share, and delete files and folders in the Media Library.
---

{% youtube 
 src="https://www.youtube.com/embed/9jsiS8siwzE?si=OU4LI5eM80Zjdeme"
 title="Copy multiple files" /%}

## Copy and move files

[Select single or multiple files](#select-multiple-files-and-folders) and right-click to open the context menu options. Click on the "Copy" or "Move" menu option and select the destination folder.

![Copy and move option in dropdown;width=400](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/copy-move-dropdown.png?tr=w-800>)

![Selecting destination for selected files from drawer](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/copy-move-drawer.png?tr=w-1600)

In a copy operation, the 'Include file version' option lets you copy all versions of the source files to the destination.

{% callout style="info" %}
**Notes**

1. Old files are deleted during the move operation. If you don't want the old files to be deleted, copy them instead of moving them.
2. **Copy Operation:** On completion of a copy file operation, access control and permission levels for the source file remain unchanged. If a file with the same name exists at the destination location, new file versions will be created, and the ownership, access control, and permissions present at the destination location's file will persist. If no file exists in the destination folder, the copied asset's ownership is set to the user who did the copy operation. Additionally, the destination location’s permissions from shared parent folders would come into effect.
3. **Move Operation:** If a file with the same name exists at the destination location, new file versions will be created, and the ownership, access control, and permissions present at the destination location's file will persist. If the source file were added to any media collection, the destination file would now be added to those media collections. If no file exists in the destination folder, the moved asset's ownership, access control, and permissions remain unchanged. Additionally, the destination location’s permissions from shared parent folders would come into effect.
{% /callout %}


## Copy and move folder

[Select single or multiple files](#select-multiple-files-and-folders) and right-click to open the context menu options. Click on the "Copy" or "Move" menu option and select the destination folder.

![Copy and move controls](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/copy-move-folder-dropdown.png?tr=w-1600)

![New destination for copying/moving the selected folders](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/copy-move-folder-drawer.png?tr=w-1600>)

{% callout style="info" %}
**Notes**

1. Old folders are deleted during the move operation. If you don't want the old folders to be deleted, copy them instead of moving them.
2. **Copy Operation:** On completion of a copy folder operation, access control and permission levels for the source folder remain unchanged. If a folder with the same name exists at the destination location, the ownership, access control, and permissions present at the destination location's folder would persist. If no folder exists in the destination folder, the copied asset's ownership is set to the user who did the copy operation. The nested folders would also be copied similarly. Additionally, the destination location’s permissions from shared parent folders would come into effect.
3. **Move Operation:** If a folder with the same name exists at the destination location, the ownership, access control, and permissions present at the destination location's folder would persist. If the source folder were added to any media collection, the destination folder would also now be added to those media collections, along with any existing media collections it was added to. If no folder exists in the destination folder, the moved asset's ownership, access control, and permissions remain unchanged. The nested folders would also be moved similarly. Additionally, the destination location’s permissions from shared parent folders would come into effect.
{% /callout %}

## Rename files

After you upload a file, you can rename it in the Media Library.

Select a file and right-click to open the options dropdown. Click on the "Rename" menu item.

![Context menu;width=400](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/rename-dropdown.png?tr=w-800>)

It will open a modal where you can enter the new file name.

![Rename file](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/rename-file-modal.png?tr=w-1600>)

While renaming, you can also purge the CDN cache for the URL with the old file name.

{% callout style="warning" %}
**Old URLs will stop working** \
When you rename a file, the URL also changes, which means the old URL will stop working. It could be cached for a while, but it will eventually stop working.
{% /callout %}

## Rename folder
 After you create a folder, you can rename it in the Media Library.

 Select a folder and right-click to open the options dropdown. Click on the "Rename" menu item.

![Context menu;width=400](<https://ik.imagekit.io/ikmedia/docs_images/media-library/rename-folder-context.png>)

It will open a modal where you can enter the new folder name.

![Rename folder modal](<https://ik.imagekit.io/ikmedia/docs_images/media-library/rename-folder-modal.png>)

While renaming, you can also purge the CDN cache for old nested files and their versions' URLs.

{% callout style="warning" %}
**Old URLs will stop working** \
When you rename a folder, the URLs for nested files also change, which means the old URLs may still work temporarily if cached, but they will eventually stop working.
{% /callout %}


## Delete files and folders

[Select single or multiple files and folders](#select-multiple-files-and-folders) you want to delete and right-click to open the options dropdown. Click on the "Delete" menu item. This will open a confirmation popup. Upon confirmation, the file will be permanently deleted from the Media Library.

{% youtube src="https://www.youtube.com/embed/yiLwkleMLlQ?si=mbwaM41lKbyR0g0b" /%}

## Delete entire media library

Under [Media Library settings](https://imagekit.io/dashboard/settings/media-library), you can find an option to delete the entire Media Library. This will delete all the files and folders in the Media Library, making the action irreversible.

![Delete Media Library](<https://ik.imagekit.io/ikmedia/docs_images/media-library/delete-entire-media-library.png?tr=w-1600>)

If you encounter any issues while deleting the entire Media Library, please contact our [support team](mailto:support@imagekit.io).

## Share files and folders

[Select a single file or folder](#select-multiple-files-and-folders) you want to share, right-click to open the options dropdown, and click on the "Share" menu item. This would open a popup where you can take the following actions:

* View information about currently shared permission levels and access with users and user groups.
* View information about Media Collections in which the asset is added.
* View information about the parent folder through which the user can access the asset.
* Share the asset with users and user groups and set their permission level.
* Update the permission level of existing users and user groups.
* Revoke access to the asset for restricted Media Library users and user groups.

When a file or folder is shared with a user, they will receive an email and a notification in their [Notification Center](/dam/notification-center) to inform them of the operation.

Learn about [sharing and collaboration](/dam/sharing-and-collaboration) to understand different permission levels.

![Share file or folder](<https://ik.imagekit.io/ikmedia/docs_images/media-library/sharing-files-folder.png?tr=w-1600>)

## Select multiple files and folders

You can do any of the following:

* **Select an item** - Click the item.
* **Select multiple items** - Press and hold the {% kbd %}⌘ Command{% /kbd %} key or {% kbd %}ctrl{% /kbd %} key , then click the items (they don’t need to be next to each other).
* **Select multiple adjacent items** - Click the first item, then press the {% kbd %}⇧ Shift{% /kbd %} key and click the last item. All items in between are included in the selection.  \
 You can also click near the first item, press and hold the trackpad or mouse button, and then drag over all items you want to select.
* **Deselect one item when multiple items are selected** - {% kbd %}⌘ Command{% /kbd %} or {% kbd %}ctrl{% /kbd %} and click the item.

![Select multiple files and folders](<https://ik.imagekit.io/ikmedia/docs_images/media-library/overview/copy-and-move-files/select-multiple-items.png?tr=w-1600>)


---

# Source: /dam/media-collection

---
title: Media Collections
description: Learn how to create, manage, and use media collections in the ImageKit Digital Asset Management product.
---

Media Collections provide a simple and dynamic way to create logical groupings of files and folders, regardless of their folder structure. A file or folder in any directory can be added to one or more media collections. Since they are logical groupings, the asset's actual location and URL remain the same, and there is no duplication.

You can easily add or remove assets from media collections and set the collection's permission level for users according to your business requirements. This makes it easier for the administrator to manage assets, share them with different users or user groups, and manage their permissions without having to delete, duplicate, or move them, which would otherwise break the asset's URL or result in a bloated asset library. 

For example, you can create a media collection of the latest brand assets, logos, videos, decks, etc., that may be used by different teams across the organization or even external PR agencies. A marketing team can centrally manage and keep the collection up-to-date. Everyone else who needs access to these assets can get it from one central collection instead of several different files and folders.

## Create a new media collection

Navigate to the media collections page by clicking "Media collections" in the menu bar. Once you are here, click on the "New" button in the top right corner. This would open a popup where you can enter the name of the media collection and click on "Submit." A new media collection will be created. A media collection's name should be unique across the organization account and can consist of alphanumeric characters, underscores, and hyphens.

Any Media Library Restricted Access user can create a new media collection.

## Add assets to media collections

In the ImageKit Media Library, select and right-click the files and folders you want to add to media collections and click on the "Add to media collections" option. You can only add assets if you have at least "contribute" permission to a media collection. A popup window would appear, allowing you to search for and select the media collections to which you wanted to add the assets. Only the media collections you can "contribute" to will appear in the list. After selecting the media collections, click on "Submit." 

You can also create a new media collection through the option given in this popup.

If you add a folder and its subfolder or file to a media collection, both will be added. You can also set separate permission levels for them.

Note that you cannot upload files or folders directly to a media collection. You have to upload the asset to the Media Library and then add it to a collection.

{% callout style="info" %}
**Limit**
- You can only add 100 assets to 50 media collections at a time.
- You can add an asset to at most 50 media collections.
{% /callout %}

## Remove assets from media collections

A restricted access user only needs "Manage" permission on a collection to remove assets from it. There are two ways to remove an asset from media collections-

1. **Remove multiple assets from media collection**
 Navigate into the media collection from where you want to remove assets. Select and right-click to open the dropdown, then click on "Remove from media collection." A confirmation popup would open. Click "Submit" to remove the selected assets from the media collection.

2. **Remove asset from multiple media media collections**
 Select and right-click on the asset you want to remove from media collections. You can view the list of media collections to which the asset was added. For this, you should have the "Manage" permission. Remove the media collections from which you want to remove the assets and click "Submit."

The access and permissions of a folder cascade to its subfolders and files. If you remove an asset from a media collection, it may still be associated with media collections if its parent is added to them.

{% callout style="info" %}
**Limit**
* You can only remove 100 assets from a media collection at a time.
* You can only remove an asset from 50 media collections at a time.
{% /callout %}

## Rename a media collection

After you have created a media collection, you can rename it. Select the media collection you want to rename and right-click to open the dropdown menu. Click on the "Rename" option to open a popup where you can enter the new name for the selected media collection. On clicking "Submit", the media collection will be renamed. The new name should be unique and can consist of alphanumeric characters, underscores, and hyphens.

The assets added to a media collection or the users or user groups with whom it is shared are unaffected by renaming it. 

## Delete media collections

Right-click after selecting the media collections you want to delete. Click on the "Delete" option in the dropdown menu. This would open a confirmation popup. Click on "Submit" to delete the media collections permanently. Deleting a media collection does not delete the files and folders that have been added to it. Once deleted, the access to assets given to users and user groups through the media collection is removed.

## Search media collections

To find a media collection by its name, click on the search bar and start typing the collection name.

All media collections whose names either match exactly or begin with or contain the words given in the query will be returned. The search for the media collection's name is case-insensitive.


## Download media collections as zip

ImageKit allows you to download multiple media collections and all of their contents, including files, folders, and sub-folders, as a single zip file. The downloaded zip file preserves the folder structure of the media collections.

{% callout style="info" %}
**Download limits** \
A maximum of 2000 files and folders can be downloaded in a single zip file.
The total size of the assets to be downloaded cannot exceed 10 GB.
{% /callout %}

Right-click on the selected media collections and click on the "Download (as zip)" option. In the popup dialogue box, you may apply an optional transformation to all the images in the selected media collections. Static and video files are not modified.

You can wait for the download to begin or continue your work and navigate to the [Downloads page](https://imagekit.io/dashboard/media-library/downloads) later to view details and the status of your download requests.

## Share media collections

Right-click on the media collection you want to share and click on the "Share" option in the dropdown menu. This would open a popup where you can take the following actions:

* View information about currently shared permission levels and access.
* Share the media collection with users and user groups and set their permission level.
* Update the permission level of existing users and user groups.
* Revoke access to the media collection for restricted media library users and user groups.

When a media collection is shared with a user, they will receive an email and a notification in their [Notification Center](/dam/notification-center) to inform them of the operation.

A user with "Can view" or higher permissions to a media collection can view all assets in that media collection, even if they don't have "Can view" permission on those assets. However, they can only modify those assets if they have also been directly shared with the users with "Can contribute" or "Can manage" permission. Learn about [sharing and collaboration](/dam/sharing-and-collaboration) to understand different permission levels.

![Share media collection](<https://ik.imagekit.io/ikmedia/docs_images/media-library/sharing-media-collection.png?tr=w-1600>)


---

# Source: /dam/search

---
title: Search
description: Find the right assets quickly using the powerful search functionality in ImageKit DAM.
---

ImageKit DAM provides a powerful search functionality that lets you quickly find the right assets. Most of the time, [search autocomplete](#search-autocomplete) is enough to find the right asset, but for more complex searches, you can use the [advanced search](#advanced-searching) functionality. 

To make it even easier, ImageKit DAM also provides [AI-powered visual search](#visual-search) that allows you to search for images based on their visual content and helps you find similar images.

## Search autocomplete

Search autocomplete helps you find the right assets quickly, even if you don't remember the exact name. The search bar will show suggestions based on the asset name and tag names as you type. You can click on any suggestion to navigate to that asset directly. Search results are also highlighted, when possible, to help you understand why a particular asset was suggested.

For example, search results showing files & folders that have `blog` in their name:

![Search autocomplete example](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/dam_autocompleter-2.png?tr=w-1600)

In the example below, the search query is `red sports car`, but the results also include assets with these words appearing, entirely or partly, in any order in the name. This allows you to find the right asset even if you don't remember the exact name.

![Search autocomplete](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/dam_autocompleter-3.png?tr=w-1600)

Search results showing assets with one or more tags matching the search query, i.e., `building`:

![Search autocomplete example with matching tags](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/dam_autocompleter.png?tr=w-1600)

The match is case insensitive, and the search results are sorted based on the relevance of the search query.

You can narrow search results by using quick filters `Folders`, `Files`, `Collections`, and `Tags`.

The toggle at the top, "Include files with matching tags," allows you to control whether the search results should include files with matching tags.

## Advanced searching

Click on the filter icon in the search bar to access the advanced search mode. This mode allows you to create complex search queries to find the exact file(s) you are looking for. 

{% youtube src="https://www.youtube.com/embed/lGu8CBxLRqs?si=75FbErjXfdMFdckx" /%}

The advanced search mode allows searching based on -

* Name
* Tags
* File size
* Dimensions (applicable for images)
* Format
* Private images
* Transparency (applicable for images)
* Created by (email of the uploader)
* First upload date
* Last modified date

For example, let's say you want to find a file -

* That was uploaded within the last month.
* And has either the `banner` or the `summer-collection` tag set.
* And the dimension is larger than `1024x768`.

You can set these filters in the advanced search UI to get all files that match the above search criteria.

![Advanced file seaching - example 1](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/advanced-search-example.png?tr=w-1600)

### Grouping of multiple search queries

You can also create more complex queries by combining multiple search parameters and changing how they are grouped.

![Grouping multiple queries using AND/OR operator](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/advanced-search-and-or.png?tr=w-1600)

There are two places where you can add a new search query -

1. Clicking on the `+` icon next to an existing filter lets you combine other search parameters in the same filter.
2. Clicking on `+ Add Filter` link lets you add another filter in parallel to the existing one. This new filter can be combined either to narrow (`and` operator) or to expand (`or` operator) the results from other search filters.

### Limiting search to specific folder

If you want to restrict the search to a specific folder instead of the entire media library, navigate to the desired folder, open the advanced search, and check the "Limit search to this folder" option. This will ensure the search is limited to the current folder and its subfolders.

![Limiting search to specific folder](https://ik.imagekit.io/ikmedia/docs_images/media-library/limit_search_to_specific_location.png?tr=w-1600)

## Visual Search

{% callout style="info" %}
This feature is only available in custom enterprise pricing plans.
For more information, please contact the [support team](mailto:support@imagekit.io) or your ImageKit Customer Success Manager.
{% /callout %}

Visual search allows you to search for similar images based on visual content. Instead of relying on text-based keywords or metadata, you can search based on visual elements like colors, shapes, textures, and any other information derived from the image.

By searching visually rather than by name or metadata, you can:

* Easily locate images without needing to remember the tags or names of the files.
* Search for similar images in your media library.
* Identify duplicates in your media library with ease.
* Discover images in your media library through visual characteristics.
* Group visually similar images together for better organization.
* Enhance the discoverability of your assets.

You can perform a visual search from the dashboard either by text or by image.

## Searching by Text

You can type in a word or a phrase to find images that visually match it.
    
For example, you can type in `summer dresses`; all the images related to `summer dresses` will be retrieved from your media library.


![Enter text phrase to search](https://ik.imagekit.io/ikmedia/docs_images/media-library/text_search.png?tr=w-1600)


![Visual search results using text input](https://ik.imagekit.io/ikmedia/docs_images/media-library/text_search_results.png?tr=w-1600)

## Searching by Image
You can find matches based on the image you upload.


![Upload image to search](https://ik.imagekit.io/ikmedia/docs_images/media-library/search_by_image.png?tr=w-1600)


For example, uploading the image from [this URL](https://ik.imagekit.io/demo/img/photo-1491972690050-ba117db4dc09_9_0DBlXmS.jpeg) will retrieve images related to a woman wearing a red shirt with sunglasses.


![Visual search results for image uploaded](https://ik.imagekit.io/ikmedia/docs_images/media-library/image_search_results.png?tr=w-1600)


## Searching by Image URL
You can find matches based on the image URL you provide.


![Search by Image URL](https://ik.imagekit.io/ikmedia/docs_images/media-library/search_by_image_url.png?tr=w-1600)

For example, entering [this URL](https://ik.imagekit.io/demo/img/allison-huang-_u8KhAZRGHs-unsplash_rn6D9ksWC.jpg) in the input box will retrieve images related to a scenic view of a beach with a house.


![Visual search results by image URL](https://ik.imagekit.io/ikmedia/docs_images/media-library/image_url_search_results.png?tr=w-1600)

## Finding similar images

Visual Search lets you easily and quickly identify duplicate assets or find similar images in your media library.

You can do this directly from the File details page in the Media Library.

![Find similar button in file details page](https://ik.imagekit.io/ikmedia/docs_images/media-library/file_details_page.png?tr=w-1600)

Use the "Find similar" button to execute a visual search using the image URL.

![Visual search results for images similar to the file selected above](https://ik.imagekit.io/ikmedia/docs_images/media-library/similar_image_search.png?tr=w-1600)

The search results will include all images that match the context of the image you are trying to find similar ones to. Any duplicate files will appear at the start of the search results.

### Limitations of Visual Search

* Visual search is compatible only with the following image formats: JPEG, PNG, WebP, GIF, AVIF, and SVG.
* Images exceeding 25MB will not be included in the search results.
* For the "Search by Image" feature, images larger than 10MB cannot be uploaded; however, you can search for images up to 25MB using the image URL.
* Visual search results will not include file versions.
* The "Find Similar" operation for files already uploaded to the Media Library is unavailable for file versions.


---

# Source: /dam/saved-searches-and-bookmarks

---
title: Saved searches and bookmarks
description: Learn how to save and manage your search queries and bookmark links in the ImageKit Digital Asset Management (DAM).
---

## Saved searches 
You can save search queries and filters applied in the media library and media collection within ImageKit Digital Asset Management (DAM). Once saved, you can quickly access your search results.

### How to save a search? 
Whenever a search is executed, you will see an option to save the search next to the search result information. Click on it, enter a name for the saved search, select its visibility, and save it. A saved search can either be visible to all users who have access to the DAM or kept private for the user who saved it.

![Save a search](https://ik.imagekit.io/ikmedia/docs_images/media-library/save-search.png?tr=w-1600)

{% callout style="info" %}
An account can have a maximum of 1,000 saved searches.
{% /callout %}

### View and search for saved searches
You can view all saved searches by clicking on the "Saved searches" option in the nav bar. You can search for a saved search using its name; substring matching is supported.

![View saved search](https://ik.imagekit.io/ikmedia/docs_images/media-library/view-saved-search.png?tr=w-1600)

### Managing saved searches 
After saving a search, you can edit or delete it. You can change the name of the saved search or delete it, but only the user who created it can modify its visibility (either "Only to me" or "Shared with everyone" who has access to the DAM).

![Manage saved search](https://ik.imagekit.io/ikmedia/docs_images/media-library/manage-saved-search.png?tr=w-1600)

### Pinning saved searches

You can pin important or frequently used saved searches to keep them at the top for quick access. Note that pinning a saved search is personal to each user and does not apply to all users in the account.

{% callout style="info" %}
You can pin a maximum of 8 saved searches.
{% /callout %}

## Bookmarks
Bookmarks allow you to save important links for easy reference and access from within the DAM.

To create a bookmark, click on the "Add bookmark" button from the bookmark drawer in the nav bar and enter a name and link. Bookmarks are accessible to all users who have access to the DAM. Once created, you can edit the name and link, and you can also delete bookmarks. You can search for a bookmark using its name or link with substring matching.

![View bookmarks](https://ik.imagekit.io/ikmedia/docs_images/media-library/bookmarks.png?tr=w-1600)

{% callout style="info" %}
An account can have a maximum of 1,000 bookmarks.
{% /callout %}

## Audit logs
All actions related to creating, updating, and deleting saved searches and bookmarks within the DAM are recorded in the [central audit logs](/central-audit-logs). These logs can be used to track your bookmarks and saved searches.


---

# Source: /dam/edit-images

---
title: Edit images
description: Leverage built-in image editor and background removal to make last-minute changes to images in the Media Library.
---

ImageKit provides a powerful browser-based image editor that allows you to edit images directly inside the DAM. You can resize, crop, rotate, and add frames, text overlays, and image overlays with the help of stickers. You can also remove the background from images with AI.

Apart from these UI-based editors, you can use any of the [50+ real-time image transformations](/image-transformation) in the image URL and use them directly on your website and app.

## ImageKit Editor

The **ImageKit Editor** is the newest way to edit images in your Media Library. It provides a browser-based interface for visually applying ImageKit transformations, without needing to manually construct transformation URLs.

{% callout style="info" %}
All image transformations done using the ImageKit editor are free, except AI-powered transformations such as change background, generative fill, and more that consume extension units. To learn more about extension unit pricing, refer to [this documentation](/how-pricing-works#extension-units-pricing).
{% /callout %}

### How to Access
You can open the editor either from the right-click menu or the action bar. Right-click on any supported image file (JPG, PNG, WebP, AVIF) and select **“ImageKit Editor”**, or select one or more images and choose the **“ImageKit Editor”** option in the header toolbar. The editor then opens in a modal window with the selected images preloaded.

|                                                                                                                     |                                                                                              |
| ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| ![](https://ik.imagekit.io/pwliscd3n/docs_images/ai-editor/editor-from-right-click.png?updatedAt=1756841508102) | ![](https://ik.imagekit.io/pwliscd3n/docs_images/ai-editor/editor-from-header.png?updatedAt=1756841512076) |


### Editing Workflow
When you launch the editor from the Media Library, your chosen images appear directly in the interface. From there, you can apply transformations such as resizing, cropping, focus, or quality adjustments. As you make changes, the preview updates instantly in the editor, reflecting the exact ImageKit transformation parameters that power the URL-based system. You can combine multiple transformations—for example, crop, resize, and quality adjustments—to refine your image until it looks exactly the way you need.

![](https://ik.imagekit.io/pwliscd3n/docs_images/ai-editor/editor-transformation-showcase.png?updatedAt=1756841508327)

Once the transformations are applied, you can decide how to use the results. The editor allows you to copy the transformed URL for immediate use in your website or app, download the edited image directly, bulk download multiple images together as a ZIP file, or export a CSV containing the list of transformed URLs. Your original file always remains safe in the Media Library. 

The editor simply generates transformation URLs in the browser, giving you a visual editing workflow that translates seamlessly into ready-to-use ImageKit links (for example, `tr=w-400,h-300,q-80`).

<!-- {% youtube src="https://www.youtube.com/embed/XXXXXXXX" /%} -->
<!-- *Add video here.* -->

## Built-in image editor (Legacy)

Right-click any image file in the Media Library and select the "Edit image" option.

{% youtube src="https://www.youtube.com/embed/QFOvZwOkMWs?si=jmtVgXxckmn3LMgL" /%}

## AI-powered background removal

Right-click any image file in the Media Library and select the "Remove background" option. The AI-powered background removal tool will automatically remove the background from the image in a few seconds. Once the background is removed, a new version will be added under the same image, becoming the current version. The original image before background removal can be accessed from the version dropdown at the top of the asset detail page

{% callout style="info" %}
This operation consumes extension units. To learn more about extension unit pricing, refer to [this documentation](/how-pricing-works#extension-units-pricing).
{% /callout %}

{% youtube src="https://www.youtube.com/embed/QFOvZwOkMWs?si=jmtVgXxckmn3LMgL&amp;start=35" /%}

## Custom focus area

ImageKit's real-time image manipulation allows you to resize and crop images. While cropping, you can control which part of the image is centered. Media Library allows you to define a focus area on the uploaded image files and crop around it using the `fo-custom` URL parameter.

Right-click any image file in the Media Library and select the "Custom Focus Area" option. Resize and place the rectangle correctly on the image to define the focus area.

{% youtube src="https://www.youtube.com/embed/5bD-vRyK-UI?si=zc2DWCVlXcsRFGY4" /%}


---

# Source: /dam/tagging-media-assets

---
title: Tagging media assets
description: Learn how to add tags to your files to organize and manage them more effectively in the media library.
---

Tags are keywords or labels that you can assign to your files to organize and manage them more effectively. Tags help you quickly find files.

## Add tags on files

You can add tags to files [at the time of upload](/dam/upload-assets#tags) or after uploading them. Tags can only be added to files and not to folders or collections.

To add/edit tags on a file, right-click to open the context menu and select the "Tags" option. You can add, edit, or delete tags from the file. 

While adding tags, as you type, you will see suggestions based on the tags already present in the Media Library. You can select from the suggestions or add a new tag. Learn more about [managing suggested tags](#managing-suggested-tags). Suggestions are shown to minimize the chance of team members creating similar tags with different spellings or capitalization.

{% youtube src="https://www.youtube.com/embed/Jk3MVkd0DKs?si=VVrGgc8sBzdSMDe3" /%}

## AI-powered auto-tagging

ImageKit DAM provides AI-powered auto-tagging that automatically assigns tags to your files based on their content. The auto-tagging feature uses machine-learning algorithms to analyze the file's content and assign relevant tags. This feature helps you organize and search for files more effectively.

{% callout style="info" %}
This operation consumes extension units. To learn more about extension unit pricing, refer to [this documentation](/how-pricing-works#extension-units-pricing).
{% /callout %}

To add tags using AI, click the "Add auto tags" option from the image's context menu or detail page. To view the AI tags, open the asset detail page and look under the "Tags" section. 

![AI-powered auto tagging](https://ik.imagekit.io/ikmedia/docs_images/media-library/auto-ai-tagging.png?tr=w-1600)

ImageKit leverages powerful label detection APIs by [Google Cloud Vision](https://cloud.google.com/vision/docs/labels) and [Amazon Rekognition](https://docs.aws.amazon.com/rekognition/latest/dg/labels-detect-labels-image.html) to provide accurate and relevant tags for your files. Select the maximum number of tags you want to add to the file and click the "Add auto tags" button.

Once the tags are added, you can view them in the tags section of the asset detail page.

![See AI tags](https://ik.imagekit.io/ikmedia/docs_images/media-library/ai-tags-added.png?tr=w-1600)

### Watch and learn how to add AI tags to your files

{% youtube src="https://www.youtube.com/embed/K1LU5f6gEvY?si=zogMI0nmyp01sda6" /%}

## Business-specific tagging using AI tasks

ImageKit offers **[AI tasks](/dam/ai-tasks)** to use modern LLMs to automate media management at scale. You can use these AI tasks to apply tags that are relevant to your business and workflows, using natural-language instructions and predefined vocabularies.

For example, you can get tags for answers to questions like “Is there a male or a female model in this image?”, “What is the kind of collar of this t-shirt - round, polo, or v-neck?, “Is this a full sleeve or a half sleeve t-shirt?”

### Auto-tagging vs AI tasks

| Feature | Auto-tagging | AI tasks |
|---------|-------------|----------|
| **Tag source** | Google/Amazon vision APIs suggest generic tags | You control the kind of information for which tags need to be generated |
| **What it sets** | Tags only | Tags AND custom metadata fields |
| **Control** | No control over tags added | Complete control via controlled vocabularies |
| **Best for** | Quick discovery and general categorization | Product catalogs, compliance, structured data |

**Example difference:**

Auto-tagging gives: `["clothing", "fashion", "outdoor"]`, which only provides generic classification

AI tasks allow you to extract a specific piece of information with your pre-defined vocabulary:
```js
{
  "type": "select_tags",
  "instruction": "What is the kind of collar of this t-shirt?",
  "vocabulary": ["round collar", "polo collar", "v-neck collar"]
}
// Returns only values from YOUR list: ["polo collar"]
```

### Common use cases

* **E-commerce product catalogs:**
Categorize by product type, color, season; set metadata fields like `color` or `style_category` from your controlled vocabulary list.
* **Brand compliance:**
Check images against brand guidelines and set approval status automatically based on your business rules.
* **Editorial workflows:**
Prioritize content by quality assessment and manage rights metadata with yes/no conditional logic.

[**Learn more about AI tasks for tagging with controlled vocabularies →**](/dam/ai-tasks)

## Searching using tags

As you type in the search bar, ImageKit automatically shows assets with one or more tags matching the search query.

![Search autocomplete example with matching tags](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/dam_autocompleter.png?tr=w-1600)

Learn more about [searching](/dam/search) in ImageKit DAM.

## Managing suggested tags

You can manage suggested tags in the [Media Library settings](https://imagekit.io/dashboard/settings/media-library). You can see the list and delete any suggested tags you don't want to use.

![Manage suggested tags](https://ik.imagekit.io/ikmedia/docs_images/media-library/suggested-tag-management.png?tr=w-1600)


---

# Source: /dam/custom-metadata

---
title: Custom Metadata
description: Attach structured metadata to assets in your ImageKit DAM to add additional information, customize asset organization, and simplify the search.
---

Custom metadata allows you to add extra information to your files, folders, and collections in ImageKit DAM.

For example, you can store information like Brand, SKU ID, Product Category, and other relevant information for your use case. Later, you can [search assets](#searching-using-custom-metadata) based on the values of these custom metadata fields.

Before you can set custom metadata on assets (files, folders, and collections), you need to [create the fields](#creating-custom-metadata-fields).

## Creating custom metadata fields

Go to the [Media Library settings](https://imagekit.io/dashboard/settings/media-library) and click on the "Custom Metadata" tab. Click on the "Add new" button to create a new field.

![Create custom metadata field](https://ik.imagekit.io/ikmedia/docs_images/media-library/create-field.png?tr=w-1600)

* **Field Label**: Enter the label for the field. This will be displayed in the custom metadata form on the asset details page. This is only for display purposes and can be changed later.
* **Field Name**: Enter the field's name. This is used during the API calls to get and set the custom metadata, and it cannot be changed later.
* **Field Type**: Select the type of field. It can be Text, Textarea, Number, Date, Boolean, SingleSelect, MultiSelect. Based on the field type, validations are applied at the time of [setting the custom metadata](#setting-custom-metadata-for-files). The Field Type cannot be changed later.

You can set additional options based on the field type, such as its default value and whether it's a mandatory field. 

You also have to add the options for SingleSelect and MultiSelect fields. For Text fields, you can also set minimum and maximum length. For Number fields, you can set minimum and maximum values. For Date fields, you can set minimum and maximum dates.

### Adding options for SingleSelect and MultiSelect fields

For fields of type SingleSelect and MultiSelect, you can manually enter options or import them using a CSV file.

{% callout style="info" %}
If the custom metadata field has more than 100 options, you can only import and/or modify options using a CSV file.
{% /callout %}

#### Manual entry of options

You can add options individually by specifying:

- The data type of the option (String, Number, or Boolean).
- The value of the option.

You can also download the currently defined options in CSV format.

![Adding options for SingleSelect and MultiSelect fields](https://ik.imagekit.io/ikmedia/docs_images/media-library/add-options-for-singleselect-and-multiselect-fields.png?tr=w-1600)

#### Bulk import options using CSV upload

You can upload a CSV file to add multiple select options at once. The CSV should have the following format:

```csv
Type,Value
string,option_one
number,42
boolean,true
```

The uploaded options will completely override any existing list rather than values being added incrementally to the current list.

Additionally, you can export your current options in CSV format. This allows you to keep a backup of your metadata configuration, which can be useful for version control, rollback planning, or restoring options later if unintended changes occur.

You can also download the CSV template to get started with the correct structure.

![Adding options using CSV for SingleSelect and MultiSelect fields](https://ik.imagekit.io/ikmedia/docs_images/media-library/add-options-for-singleselect-and-multiselect-fields-using-csv.png?tr=w-1600)

## Setting custom metadata for files

Assuming you have created the necessary custom metadata fields, you can set custom metadata for files by editing the asset details or [at the time of upload](/dam/upload-assets#custom-metadata).

To set custom metadata for a file, go to the asset details page by double-clicking or right-clicking on the asset and selecting "Details" from the context menu.

On the asset details page, you will see a "Custom metadata" section on the right, where you can set values for the custom metadata fields.

![Set custom metadata for files](https://ik.imagekit.io/ikmedia/docs_images/media-library/setting-custom-metadata.png?tr=w-1600)

## Setting custom metadata for folders

You can set custom metadata for folders during folder creation or by editing the folder details.

To set custom metadata for a folder, go to the folder details page by double-clicking on it or right-clicking on it and selecting "Folder details" from the context menu. This will open a dialog where you can see and update the custom metadata fields.

![Set custom metadata for folders](https://ik.imagekit.io/ikmedia/docs_images/media-library/set-cm-field-on-folder.png?tr=w-1600)

## Setting custom metadata for collections

Like folders, collections can have custom metadata associated with them at the time of creation or editing of the collection details.

![Set custom metadata for collections](https://ik.imagekit.io/ikmedia/docs_images/media-library/set-cm-field-on-collection.png?tr=w-1600)

## Automating custom metadata using AI tasks
ImageKit offers **[AI tasks](/dam/ai-tasks)** to use modern LLMs to automate media management at scale. You can use these AI tasks to set custom metadata fields automatically, using natural-language instructions and predefined vocabularies. This helps eliminate manual effort and errors while automating media management at scale.

For example, you can set the metadata field "gender" for your product images using the answer to a question like “Is there a male or a female model in this image?”.

You can [**learn more about AI tasks for automatically setting metadata**](/dam/ai-tasks) here.

## Searching using custom metadata

You can search for assets based on custom metadata fields using advanced search. Select any defined custom metadata field and set the search criteria to filter the assets.

![Searching using custom metadata](https://ik.imagekit.io/ikmedia/docs_images/media-library/search-using-custom-metadata-fields.png?tr=w-1600)


---

# Source: /dam/ai-tasks

---
title: AI Tasks
description: Use modern LLMs to automate media management at scale. Use them to apply business-specific tags and automate custom metadata fields for improved organization or quality checks on your media assets, with natural-language instructions and predefined vocabularies.
---

## What are AI tasks?

AI tasks are standalone actions that can run on your image assets, using modern LLMs to visually analyze an image and turn that information into reliable metadata. You ask any business-specific question in plain English, and the AI selects answers only from your approved vocabulary. This can help your tags and custom fields stay consistent, schema-safe, and ready for DAM workflows at scale, or can also be used to QC assets as per your business requirements.

**Key features:**

- **Analyze using natural language instructions:** No complex regex or coding required. You can set up questions to be asked in plain English. For example, you can ask, “Is there any person in this picture?”
- **Custom vocabulary:** Unlike generic AI tagging, you can also specify the vocabulary AI should stick to while answering the question, making it the same as the vocabulary your team and processes should use internally. For example, you can define that the AI should respond with “T-Shirt,” “Tshirt,” or just “Tee” when asked to identify the apparel item in an image, to match your business's vocabulary.
- **Works at scale:** Process thousands of assets in seconds during upload or via bulk updates or by using these AI tasks via [Saved extensions](/dam/saved-extensions) in [Path policies](/dam/path-policy).
- **Eliminate human bias:**  Ensure the same logic is applied to every asset, improving search and filtering without human mistakes or bias during evaluation.

{% callout style="info" %}
AI tasks consume extension units. Learn about [extension unit pricing](/how-pricing-works#extension-units-pricing) here.
{% /callout %}

## Use cases
Most businesses across industries that manage their assets with ImageKit DAM use AI tasks to solve real-world metadata management, QC, and automation at scale. Given below are examples of use cases across different industries.

1. **Add very specific tags and metadata to your images:** This is the primary use case of AI tasks - to organize your assets using business-specific, customized tags and metadata on your images. Unlike generic AI tagging solutions that will add not-so-useful, generic tags to your images, You can ask questions in plain English that make sense for your business and teams’ processes. For example, this is how different industries benefit using AI tags

    - **E-commerce:** Instead of generic tags like “t-shirt” on your images, you can use AI tasks for customized product and attribute categorization using questions like “Is there a male or a female model in this image?”, “What is the kind of collar of this t-shirt - round, polo, or v-neck?, “Is this a full sleeve or a half sleeve t-shirt?”

    - **Automotive:** AI tasks can be used for body style classification, PII detection, and more, using questions such as “Is this the shot of the interior or exterior of the car?”, “Does this image show the car front seats, the rear seats, or the boot space?”, “Is there any person standing next to the car or sitting inside the car?” “Is this image taken in a studio, on a city road, or on an outdoor trail?”
    
    - **Travel and Hospitality:** AI tasks can help with room or space classification, amenity detection (pool, balcony, workspace), and view categorization using questions such as “Identify the part of the hotel shown in the image?”, “Is this a shot from outside the hotel or inside the hotel?”, “Is there a twin bed or a double bed in the room?”.
    
    - **News and Media:** AI tasks can accelerate categorization, PII flagging, and QC of assets resulting in faster time to market. One can ask questions such as “Does this image contain a person’s face?”, “Is there a known celebrity in this image?”, “Does this image contain any NSFW content?”, and more.

2. **Image QC:** Not only can AI tasks help you organize the assets correctly as explained above, you can also use them to run standard quality checks on your images. While the end result of these AI tasks would still be some specific tags and metadata, you can use these tags and metadata to search for assets that need a manual review, or automatically reject them if they do not meet the quality standards set for images in your organization. For example, you can use AI tasks to ask questions such as -
    - Identify if the images show any celebrities?
    - Is the image quality blurred or grainy?
    - Is the car in the image completely visible, or is it getting cropped out?

You can use the AI Task action "yes_no" (explained below) and, depending on positive or negative answers to the above questions, add tags such as "needs review" or "production-ready" to your images.

3. **Automatic subsequent processes and automations:** Accurate, business-specific tagging is the most important piece to get right for automating publishing processes at scale. Once your assets are tagged correctly, the steps that follow - either via the dashboard or programmatically using ImageKit’s DAM APIs- remain consistent at scale. For example, once AI tasks run on all your images and add suitable business-specific tags and metadata, you can reliably find assets that depict a “round neck”, “t-shirt”, on a “man”,  in a “studio setup”. You can then use these assets to create personalized banners with text and image overlays, or send them in a push notification to a user looking for t-shirts on your website. This improves time-to-market for your assets and campaigns, helps you find the right assets every time, and elevates the experience for your end users. 

Since AI tasks can run across thousands of assets without manual intervention, your business can classify assets correctly in seconds instead of taking weeks for the same, and always struggling with manual errors. 

## How AI tasks work
AI tasks analyze images and apply metadata based on your business rules.

Within an AI task, you can configure multiple sub-tasks to run in one go, with each sub-task handling a different aspect of categorization. Consider each sub-task to be one question and action that you want to ask the LLM to evaluate on your image. Each question you want to ask becomes a separate sub-task within the same AI task.

Each sub-task of an AI task has three components:

1. **Instruction** - A clear, natural language question or instruction that tells the AI what aspect of the image to evaluate. For example, "Does this image show the car front seats, the rear seats, or the boot space?".

2. **Actions** - What happens with the AI's analysis, how many tags get added, which metadata fields get set, or how does the conditional logic execute. This is defined primarily using the [action type](#ai-task-actions), along with other action-specific configuration options. For example, to add tags based on the question "Does this image show the car front seats, the rear seats, or the boot space?", the type will be `select_tags`.

3. **Vocabulary** - An optional, predefined list of possible values the AI can select from. This is your controlled vocabulary or business taxonomy. AI can only choose from the values you define (1-30 items per vocabulary). For example, for the question "Does this image show the car front seats, the rear seats, or the boot space?", the vocabulary can be "front","rear", and "boot".

AI tasks can only be a part of a Saved Extension. So, you first need to create a [Saved Extension](/dam/saved-extensions), either from your dashboard from Settings → Media Library → Saved Extensions, or using the [Saved Extension API](/api-reference/digital-asset-management-dam/saved-extensions/create-extension). Within the saved extension, you can define the AI task along with its sub-tasks using a JSON configuration.

For example, a saved extension with one AI task with two sub-tasks will look like this

```js
{
  "name": "ai-tasks", //fixed value to identify AI tasks
  "tasks": [ 
    {  //sub-task 1
      "type": "select_tags", 
      "instruction": "What is the body style of the vehicle shown in this image?", 
      "vocabulary": ["sedan","suv","hatchback"],
    },
    { //sub-task 2
      "type": "select_metadata",
      "instruction": "What is the primary color of the vehicle's exterior?",
      "vocabulary": ["white","black","silver"]
      "field": "color"
    }
  ]
}
```

{% callout style="info" %}
We have included complete examples for different actions and different industries in this documentation to make it easier for you to copy-paste and modify the AI task configurations as per your requirements.

Alternatively, your technology team, or [ImageKit's support team](mailto:support@imagekit.io), or your dedicated Customer Success Manager, can also help you configure the AI tasks.
{% /callout %}

## AI Task Actions

AI tasks support three task types, each designed for different metadata management needs:

| Task Type | What It Does | When to Use |
|-----------|--------------|-------------|
| [select_tags](#select-tags) | Selects and applies tags from your vocabulary | Categorization, product attributes, building searchable taxonomies, or applying multiple labels |
| [select_metadata](#select-metadata) | Sets custom metadata field values from your vocabulary | Structured data like color, season, type, status, or single/multi-select dropdown fields |
| [yes_no](#yes/no) | Asks yes/no questions and executes conditional actions | Quality checks, compliance verification, binary classifications, or conditional workflows |

### Select tags

Analyzes the image and adds relevant tags from your controlled vocabulary. The AI compares what it sees in the image against your instruction, selects matching tags from your vocabulary while respecting min/max selection constraints, and adds the selected tags to the file. For example, an image of a living room might receive tags: `["sofa", "chair", "table", "lamp"]`.

**Configuration:**
```js
{
  "type": "select_tags",
  "instruction": "What types of furniture are visible in this image?",
  "vocabulary": ["sofa", "chair", "table", "desk", "bed", "shelving", "cabinet", "lamp"],
  "min_selections": 1,
  "max_selections": 4
}
```

**Parameters:**

| Parameter        | Type   | Required | Description                                                                    |
| ---------------- | ------ | -------- | ------------------------------------------------------------------------------ |
| `type`           | string | Yes      | Must be `"select_tags"`                                                        |
| `instruction`    | string | Yes      | Question or instruction (1-2000 characters)                                    |
| `vocabulary`     | array  | No      | Possible tag values (1-30 items, max 500 chars combined, no `%` character)   |
| `min_selections` | number | No       | Minimum tags to select (≥ 0). Default: no minimum                              |
| `max_selections` | number | No       | Maximum tags to select (≥ 1). Default: no maximum                              |


### Select metadata

Analyzes the image and sets a custom metadata field value from your vocabulary. The AI evaluates the image against your instruction, selects the best matching value(s) from vocabulary, validates against field type constraints, and sets the custom metadata field. For example, a metadata field `lighting` might be set to `"golden-hour"`.

**Configuration:**
```js
{
  "type": "select_metadata",
  "instruction": "What is the dominant lighting condition in this image?",
  "field": "lighting",
  "vocabulary": ["natural-daylight", "golden-hour", "overcast", "indoor-artificial", "low-light", "night"],
  "min_selections": 1,
  "max_selections": 1
}
```

**Parameters:**

| Parameter        | Type   | Required | Description                                                                    |
| ---------------- | ------ | -------- | ------------------------------------------------------------------------------ |
| `type`           | string | Yes      | Must be `"select_metadata"`                                                    |
| `instruction`    | string | Yes      | Question or instruction (1-2000 characters)                                    |
| `field`          | string | Yes      | Custom metadata field name (must already exist in your media library)          |
| `vocabulary`     | array  | No      | Possible values matching field type (1-30 items)                              |
| `min_selections` | number | No       | Minimum values to select (≥ 0). Default: no minimum                            |
| `max_selections` | number | No       | Maximum values to select (≥ 1). Default: no maximum                            |

{% callout style="warning" %}
**Important:**  
1. The custom metadata field must exist before using it in AI tasks. Create fields using the [Custom Metadata Fields API](/api-reference#create-custom-metadata-field) or in your dashboard under Settings → Media Library → Custom Metadata Fields.
2. Your vocabulary must match the field's schema definition. If you later change the field schema, AI tasks may fail to set values. Check the asset history to see why values were or weren't set.
{% /callout %}


### Yes/No

Asks a yes/no question about the image and executes different actions based on the answer. The AI evaluates the image and returns one of three responses: **Yes**, **No**, or **Unknown** (when the AI cannot confidently determine the answer). Each response can trigger different actions—tags added/removed and metadata set/unset.

For example, a high-quality image might receive tags `["print-ready", "high-quality", "approved"]` and metadata updates for quality status. If the AI cannot confidently assess quality, the `on_unknown` actions execute instead (e.g., tagging for manual review).

**Configuration:**
```js
{
  "type": "yes_no",
  "instruction": "Does this image meet quality standards for print publication (sharp focus, good lighting, high resolution)?",
  "on_yes": {
    "add_tags": ["print-ready", "high-quality", "approved"],
    "set_metadata": [
      { "field": "quality_status", "value": "approved" },
      { "field": "print_approved", "value": true }
    ]
  },
  "on_no": {
    "add_tags": ["web-only", "needs-improvement"],
    "remove_tags": ["print-ready", "approved"],
    "set_metadata": [
      { "field": "quality_status", "value": "rejected" },
      { "field": "print_approved", "value": false }
    ]
  },
  "on_unknown": {
    "add_tags": ["needs-review"],
    "set_metadata": [
      { "field": "quality_status", "value": "pending" }
    ]
  }
}
```

**Parameters:**

| Parameter     | Type   | Required | Description                                                              |
| ------------- | ------ | -------- | ------------------------------------------------------------------------ |
| `type`        | string | Yes      | Must be `"yes_no"`                                                       |
| `instruction` | string | Yes      | Yes/no question (1-2000 characters)                                      |
| `on_yes`      | object | No*      | Actions to execute if AI determines answer is "yes"                      |
| `on_no`       | object | No*      | Actions to execute if AI determines answer is "no"                       |
| `on_unknown`  | object | No       | Actions to execute if AI cannot confidently determine yes or no          |

{% callout style="info" %} 
At least one of `on_yes` or `on_no` is required.
{% /callout %}

**Action objects:**

Each action object for `on_yes`, `on_no`, and `on_unknown` can include:

```js
{
  "add_tags": ["tag1", "tag2"],
  "remove_tags": ["tag3", "tag4"],
  "set_metadata": [
    { "field": "field_name", "value": "some_value" }
  ],
  "unset_metadata": [
    { "field": "field_to_remove" }
  ]
}
```

| Property          | Type  | Description                                                                       |
| ----------------- | ----- | --------------------------------------------------------------------------------- |
| `add_tags`        | array | Tags to add to the file                                                           |
| `remove_tags`     | array | Tags to remove from the file                                                      |
| `set_metadata`    | array | Array of objects with `field` (string) and `value` (any) to set metadata fields  |
| `unset_metadata`  | array | Array of objects with `field` (string) to remove metadata fields                 |


## Example: Fashion e-commerce

This comprehensive example combines all three task types for a fashion retailer:

```js
{
  "name": "ai-tasks",
  "tasks": [
    {
      "type": "select_tags",
      "instruction": "What types of clothing or accessories are visible in this product image?",
      "vocabulary": [
        "dress", "shirt", "blouse", "t-shirt", "sweater", "jacket", 
        "coat", "pants", "jeans", "skirt", "shorts", "shoes", 
        "boots", "sneakers", "bag", "belt", "hat", "scarf", "jewelry"
      ],
      "min_selections": 1,
      "max_selections": 5
    },
    {
      "type": "select_metadata",
      "instruction": "What is the primary color of the main product?",
      "field": "primary_color",
      "vocabulary": [
        "black", "white", "gray", "beige", "brown", 
        "red", "pink", "orange", "yellow", "green", 
        "blue", "navy", "purple", "multi-color", "metallic"
      ],
      "min_selections": 1,
      "max_selections": 1
    },
    {
      "type": "select_metadata",
      "instruction": "What season or weather is this product suitable for?",
      "field": "season",
      "vocabulary": ["spring", "summer", "fall", "winter", "all-season"],
      "min_selections": 1,
      "max_selections": 2
    },
    {
      "type": "yes_no",
      "instruction": "Is this a formal or dressy item (suitable for office, weddings, formal events)?",
      "on_yes": {
        "add_tags": ["formal", "dressy", "occasion-wear"],
        "set_metadata": [
          { "field": "style_category", "value": "formal" },
          { "field": "dress_code", "value": "business-formal" }
        ]
      },
      "on_no": {
        "add_tags": ["casual", "everyday"],
        "set_metadata": [
          { "field": "style_category", "value": "casual" },
          { "field": "dress_code", "value": "casual" }
        ]
      }
    },
    {
      "type": "yes_no",
      "instruction": "Does this product appear to be luxury or high-end (designer labels, premium materials, high-end styling)?",
      "on_yes": {
        "add_tags": ["luxury", "premium", "designer"],
        "remove_tags": ["budget", "value"],
        "set_metadata": [
          { "field": "price_tier", "value": "premium" },
          { "field": "target_market", "value": "luxury" }
        ]
      },
      "on_no": {
        "add_tags": ["accessible", "value"],
        "remove_tags": ["luxury", "premium"],
        "set_metadata": [
          { "field": "price_tier", "value": "standard" },
          { "field": "target_market", "value": "mass-market" }
        ]
      }
    }
  ]
}
```

This configuration gives you complete product categorization in one upload. Each product image automatically gets tagged with product types, assigned a primary color, categorized by season, classified by style (formal vs. casual), and marked as luxury or standard—all without manual intervention. Upload thousands of products, and every single one gets consistent, searchable metadata that your team and customers can immediately filter and browse.

## Example: Travel Industry
This example adds only tags to the images for a travel company.

```js
{
  "name": "ai-tasks",
  "tasks": [
    {
      "type": "select_tags",
      "instruction": "In which city is this place located? If you are not able to identify the city, don't provide any tag.",
      "max_selections": 1
    },
    {
      "type": "select_tags",
      "instruction": "In which country is this place located? If you are not able to identify the city, don't provide any tag.",
      "max_selections": 1
    },
    {
      "type": "select_tags",
      "instruction": "What is the landscape in this image? Add any suitable tags to the image",
      "max_selections": 5
    },
    {
      "type": "select_tags",
      "instruction": "At what time of the day has this picture been taken possibly?",
      "vocabulary": [
        "morning", "afternoon", "evening", "night"
      ],
      "max_selections": 1
    },
    {
      "type": "select_tags",
      "instruction": "Does this image consist of no people, only one people, or two, or three or more?",
      "vocabulary": [
        "no people", "one people", "two people", "three people", "more people"
      ],
      "max_selections": 1
    },
    {
      "type": "select_tags",
      "instruction": "Does this image consist of a male or a female or both male and female or no people?",
      "vocabulary": [
        "male", "female", "both male and female", "no people"
      ],
      "max_selections": 1
    },
    {
      "type": "select_tags",
      "instruction": "Does this image consist of a group of solo travellers, a couple, or a family, or no people?",
      "vocabulary": [
        "solo travellers", "family", "couple", "no people"
      ],
      "max_selections": 1
    },
    {
      "type": "select_tags",
      "instruction": "If there is a famous monument in this image, then identify it. If you can't identify it, then don't add any tag.",
      "max_selections": 1
    }
  ]
}
```
## Example: Automotive (Cars)
This example adds only tags to the images for an automotive company.

```js
{
  "name": "ai-tasks",
  "tasks": [
    {
      "type": "select_tags",
      "instruction": "What is the body style of the vehicle shown in this image?",
      "vocabulary": [
        "sedan", "suv", "hatchback", "coupe","convertible","pickup truck", "minivan","luxury","sports car","wagon"
      ],
      "max_selections": 1
    },
    {
      "type": "select_tags",
      "instruction": "Which part of the car is primarily featured in this image?",
      "vocabulary": [
        "full exterior", "front view","rear view", "side profile", "dashboard", "steering wheel", "front seats", "rear seats", "trunk/boot", "engine bay", "wheel/rim", "headlight", "infotainment screen"
      ],
      "max_selections": 1
    },
    {
      "type": "select_tags",
      "instruction": "If the brand (make) of the car is clearly visible or recognizable, identify it. If not recognizable, do not add a tag.",
      "max_selections": 1
    },
    {
      "type": "select_tags",
      "instruction": "What is the primary color of the vehicle's exterior?",
      "vocabulary": [
        "white", "black", "silver", "grey", "blue", "red", "green", "yellow", "orange", "brown"
      ],
      "max_selections": 1
    },
    {
      "type": "select_tags",
      "instruction": "Is the image taken in an indoor setting (showroom/garage) or an outdoor setting?",
      "vocabulary": [
        "indoor - showroom", "indoor - garage", "outdoor - city/road", "outdoor - nature/offroad", "studio - plain background"
      ],
      "max_selections": 1
    },
    {
      "type": "select_tags",
      "instruction": "Are there any people present in or around the vehicle?",
      "vocabulary": [
        "no people", "driver only", "driver and passengers", "person standing outside", "model posing with car"
      ],
      "max_selections": 1
    },
    {
      "type": "select_tags",
      "instruction": "Does the vehicle appear to be a new/modern model or a vintage/classic car?",
      "vocabulary": [
        "modern",
        "vintage/classic"
      ],
      "max_selections": 1
    },
    {
      "type": "select_tags",
      "instruction": "Identify any specific features visible in the image.",
      "vocabulary": [
        "sunroof", "alloy wheels", "leather seats", "digital instrument cluster", "spoiler", "roof rails", "led headlights"
      ],
      "max_selections": 3
    }
  ]
}
```

## Applying AI tasks

You can apply AI tasks through the dashboard UI or programmatically via API, both at upload time or to existing files. You can also automate AI task application using [Path policies](/dam/path-policy) based on destination in the Media Library.

### Using the UI

To use AI tasks through the dashboard, first [create a saved extension](/dam/saved-extensions) with your AI tasks configuration.

At upload, open settings and select the saved extension from the Extensions list.

![Apply Saved Extensions at the time of upload](https://ik.imagekit.io/ikmedia/docs_images/media-library/ai-tasks/upload-file.png?tr=w-1600&v=1)

For existing files, select files in Media Library → Right-click → **Apply Saved extensions** → Choose your AI tasks extension → Apply

![Apply Saved Extensions to existing assets](https://ik.imagekit.io/ikmedia/docs_images/media-library/ai-tasks/ai-tasks-apply-existing-assets.png?tr=w-1600&v=1)

### Programmatically using API

{% linetabs %}
{% linetab title="At the time of uploading files" %}

Apply AI tasks when [uploading new files](/docs/api-reference/upload-file/upload-file). Include AI tasks in the `extensions` parameter:

{% tabs %}
{% tab title="cURL" %}
```bash
curl -X POST 'https://upload.imagekit.io/api/v1/files/upload' \
  -u your_private_key: \
  -F 'file=@image.jpg' \
  -F 'fileName=image.jpg' \
  -F 'extensions=[{
    "name": "ai-tasks",
    "tasks": [
      {
        "type": "select_tags",
        "instruction": "What product categories are visible in this image?",
        "vocabulary": ["apparel", "footwear", "accessories", "bags", "jewelry"],
        "max_selections": 2
      },
      {
        "type": "select_metadata",
        "instruction": "What is the dominant color?",
        "field": "primary_color",
        "vocabulary": ["black", "white", "red", "blue", "green", "beige", "brown", "multi-color"],
        "max_selections": 1
      }
    ]
  }]'
```
{% /tab %}

{% tab title="Node.js" %}
```javascript
import ImageKit from '@imagekit/nodejs';
import fs from 'fs';

const client = new ImageKit({
  privateKey: "your_private_api_key"
});

try {
  const result = await client.files.upload({
    file: fs.createReadStream('path/to/image.jpg'),
    fileName: 'image.jpg',
    extensions: [
      {
        name: 'ai-tasks',
        tasks: [
          {
            type: 'select_tags',
            instruction: 'What product categories are visible in this image?',
            vocabulary: ['apparel', 'footwear', 'accessories', 'bags', 'jewelry'],
            max_selections: 2
          },
          {
            type: 'select_metadata',
            instruction: 'What is the dominant color?',
            field: 'primary_color',
            vocabulary: ['black', 'white', 'red', 'blue', 'green', 'beige', 'brown', 'multi-color'],
            max_selections: 1
          }
        ]
      }
    ]
  });
  console.log(result);
} catch (error) {
  console.log(error);
}
```
{% /tab %}

{% tab title="Python" %}
```python
from imagekitio import ImageKit

client = ImageKit(
    private_key="your_private_api_key"
)

with open("path/to/image.jpg", "rb") as file:
    upload = client.files.upload(
        file=file,
        file_name="image.jpg",
        extensions=[
            {
                "name": "ai-tasks",
                "tasks": [
                    {
                        "type": "select_tags",
                        "instruction": "What product categories are visible in this image?",
                        "vocabulary": ["apparel", "footwear", "accessories", "bags", "jewelry"],
                        "max_selections": 2
                    },
                    {
                        "type": "select_metadata",
                        "instruction": "What is the dominant color?",
                        "field": "primary_color",
                        "vocabulary": ["black", "white", "red", "blue", "green", "beige", "brown", "multi-color"],
                        "max_selections": 1
                    }
                ]
            }
        ]
    )

print(upload)
```
{% /tab %}

{% tab title="Ruby" %}
```ruby
require 'imagekitio'

client = Imagekitio::Client.new(
  private_key: 'your_private_api_key'
)

result = client.files.upload(
  file: Pathname('path/to/image.jpg'),
  file_name: 'image.jpg',
  extensions: [
    {
      name: 'ai-tasks',
      tasks: [
        {
          type: 'select_tags',
          instruction: 'What product categories are visible in this image?',
          vocabulary: ['apparel', 'footwear', 'accessories', 'bags', 'jewelry'],
          max_selections: 2
        },
        {
          type: 'select_metadata',
          instruction: 'What is the dominant color?',
          field: 'primary_color',
          vocabulary: ['black', 'white', 'red', 'blue', 'green', 'beige', 'brown', 'multi-color'],
          max_selections: 1
        }
      ]
    }
  ]
)

puts result
```
{% /tab %}

{% tab title="Go" %}
```go
package main

import (
	"context"
	"fmt"
	"os"

	"github.com/imagekit-developer/imagekit-go/v2"
	"github.com/imagekit-developer/imagekit-go/v2/option"
	"github.com/imagekit-developer/imagekit-go/v2/shared"
)

func main() {
	client := imagekit.NewClient(
		option.WithPrivateKey("your_private_api_key"),
	)

	file, err := os.Open("path/to/image.jpg")
	if err != nil {
		panic(err.Error())
	}
	defer file.Close()

	upload, err := client.Files.Upload(
		context.TODO(),
		imagekit.FileUploadParams{
			File:     file,
			FileName: "image.jpg",
			Extensions: []shared.ExtensionUnionParam{
				{
					OfAITasks: &shared.ExtensionAITasksParam{
						Tasks: []shared.ExtensionAITasksTaskUnionParam{
							{
								OfSelectTags: &shared.ExtensionAITasksTaskSelectTagsParam{
									Instruction:   "What product categories are visible in this image?",
									Vocabulary:    []string{"apparel", "footwear", "accessories", "bags", "jewelry"},
									MaxSelections: imagekit.Int(2),
								},
							},
							{
								OfSelectMetadata: &shared.ExtensionAITasksTaskSelectMetadataParam{
									Instruction:   "What is the dominant color?",
									Field:         "primary_color",
									Vocabulary: []shared.ExtensionAITasksTaskSelectMetadataVocabularyUnionParam{
										{OfString: imagekit.String("black")},
										{OfString: imagekit.String("white")},
										{OfString: imagekit.String("red")},
										{OfString: imagekit.String("blue")},
										{OfString: imagekit.String("green")},
										{OfString: imagekit.String("beige")},
										{OfString: imagekit.String("brown")},
										{OfString: imagekit.String("multi-color")},
									},
									MaxSelections: imagekit.Int(1),
								},
							},
						},
					},
				},
			},
		},
	)
	if err != nil {
		panic(err.Error())
	}

	fmt.Println(upload)
}
```
{% /tab %}

{% tab title="Java" %}

```java
import io.imagekit.client.ImageKitClient;
import io.imagekit.client.okhttp.ImageKitOkHttpClient;
import io.imagekit.models.files.FileUploadParams;
import io.imagekit.models.files.FileUploadResponse;
import io.imagekit.models.files.ExtensionItem;
import java.nio.file.Paths;
import java.util.List;

ImageKitClient client = ImageKitOkHttpClient.builder()
    .privateKey("your_private_key")
    .build();

FileUploadParams params = FileUploadParams.builder()
    .file(Paths.get("path/to/image.jpg"))
    .fileName("image.jpg")
    .addExtension(
        ExtensionItem.AiTasks.builder()
            .name("ai-tasks")
            .addTask(
                ExtensionItem.AiTasks.Task.SelectTags.builder()
                    .type(ExtensionItem.AiTasks.Task.SelectTags.Type.SELECT_TAGS)
                    .instruction("What product categories are visible in this image?")
                    .vocabulary(List.of("apparel", "footwear", "accessories", "bags", "jewelry"))
                    .maxSelections(2L)
                    .build()
            )
            .addTask(
                ExtensionItem.AiTasks.Task.SelectMetadata.builder()
                    .type(ExtensionItem.AiTasks.Task.SelectMetadata.Type.SELECT_METADATA)
                    .instruction("What is the dominant color?")
                    .field("primary_color")
                    .vocabulary(List.of("black", "white", "red", "blue", "green", "beige", "brown", "multi-color"))
                    .maxSelections(1L)
                    .build()
            )
            .build()
    )
    .build();

FileUploadResponse response = client.files().upload(params);
System.out.println(response);
```

{% /tab %}

{% tab title=".Net" %}
```csharp
using Imagekit;
using Imagekit.Models;

ImageKitClient client = new() { PrivateKey = "your_private_key" };

using var fileStream = System.IO.File.OpenRead("path/to/image.jpg");
var response = await client.Files.Upload(new()
{
    File = fileStream,
    FileName = "image.jpg",
    Extensions =
    [
        new ExtensionItemAITasks(
        [
            new ExtensionItemAITasksTaskSelectTags()
            {
                Instruction = "What product categories are visible in this image?",
                MaxSelections = 2,
                Vocabulary = ["apparel", "footwear", "accessories", "bags", "jewelry"],
            },
            new ExtensionItemAITasksTaskSelectMetadata()
            {
                Instruction = "What is the dominant color?",
                Field = "primary_color",
                MaxSelections = 1,
                Vocabulary = ["black", "white", "red", "blue", "green", "beige", "brown", "multi-color"],
            },
        ]),
    ],
});

Console.WriteLine(response);
```
{% /tab %}

{% /tabs %}

{% /linetab %}

{% linetab title="Update existing assets" %}

Using the [update file details](/docs/api-reference/digital-asset-management-dam/managing-assets/update-file-details) API:

{% tabs %}
{% tab title="cURL" %}
```bash
curl -X PATCH 'https://api.imagekit.io/v1/files/fileId/details' \
  -H 'Content-Type: application/json' \
  -u your_private_key: \
  -d '{
  "extensions": [
    {
      "name": "ai-tasks",
      "tasks": [
        {
          "type": "select_tags",
          "instruction": "What product categories are visible in this image?",
          "vocabulary": ["apparel", "footwear", "accessories", "bags", "jewelry"],
          "max_selections": 2
        },
        {
          "type": "select_metadata",
          "instruction": "What is the dominant color?",
          "field": "primary_color",
          "vocabulary": ["black", "white", "red", "blue", "green", "beige", "brown", "multi-color"],
          "max_selections": 1
        }
      ]
    }
  ]
}'
```
{% /tab %}

{% tab title="Node.js" %}
```javascript
import ImageKit from '@imagekit/nodejs';

const client = new ImageKit({
  privateKey: "your_private_api_key"
});

try {
  const result = await client.files.update('fileId', {
    extensions: [
      {
        name: 'ai-tasks',
        tasks: [
          {
            type: 'select_tags',
            instruction: 'What product categories are visible in this image?',
            vocabulary: ['apparel', 'footwear', 'accessories', 'bags', 'jewelry'],
            max_selections: 2
          },
          {
            type: 'select_metadata',
            instruction: 'What is the dominant color?',
            field: 'primary_color',
            vocabulary: ['black', 'white', 'red', 'blue', 'green', 'beige', 'brown', 'multi-color'],
            max_selections: 1
          }
        ]
      }
    ]
  });
  console.log(result);
} catch (error) {
  console.log(error);
}
```
{% /tab %}

{% tab title="Python" %}
```python
from imagekitio import ImageKit

client = ImageKit(
    private_key="your_private_api_key"
)

result = client.files.update(
    file_id="fileId",
    extensions=[
        {
            "name": "ai-tasks",
            "tasks": [
                {
                    "type": "select_tags",
                    "instruction": "What product categories are visible in this image?",
                    "vocabulary": ["apparel", "footwear", "accessories", "bags", "jewelry"],
                    "max_selections": 2
                },
                {
                    "type": "select_metadata",
                    "instruction": "What is the dominant color?",
                    "field": "primary_color",
                    "vocabulary": ["black", "white", "red", "blue", "green", "beige", "brown", "multi-color"],
                    "max_selections": 1
                }
            ]
        }
    ]
)

print(result)
```
{% /tab %}

{% tab title="Ruby" %}
```ruby
require 'imagekitio'

client = Imagekitio::Client.new(
  private_key: 'your_private_api_key'
)

result = client.files.update(
  'fileId',
  update_file_request: {
    extensions: [
      {
        name: 'ai-tasks',
        tasks: [
          {
            type: 'select_tags',
            instruction: 'What product categories are visible in this image?',
            vocabulary: ['apparel', 'footwear', 'accessories', 'bags', 'jewelry'],
            max_selections: 2
          },
          {
            type: 'select_metadata',
            instruction: 'What is the dominant color?',
            field: 'primary_color',
            vocabulary: ['black', 'white', 'red', 'blue', 'green', 'beige', 'brown', 'multi-color'],
            max_selections: 1
          }
        ]
      }
    ]
  }
)

puts result
```
{% /tab %}

{% tab title="Go" %}
```go
package main

import (
	"context"
	"fmt"

	"github.com/imagekit-developer/imagekit-go/v2"
	"github.com/imagekit-developer/imagekit-go/v2/option"
	"github.com/imagekit-developer/imagekit-go/v2/shared"
)

func main() {
	client := imagekit.NewClient(
		option.WithPrivateKey("your_private_api_key"),
	)

	result, err := client.Files.Update(
		context.TODO(),
		"fileId",
		imagekit.FileUpdateParams{
			Extensions: []shared.ExtensionUnionParam{
				{
					OfAITasks: &shared.ExtensionAITasksParam{
						Tasks: []shared.ExtensionAITasksTaskUnionParam{
							{
								OfSelectTags: &shared.ExtensionAITasksTaskSelectTagsParam{
									Instruction:   "What product categories are visible in this image?",
									Vocabulary:    []string{"apparel", "footwear", "accessories", "bags", "jewelry"},
									MaxSelections: imagekit.Int(2),
								},
							},
							{
								OfSelectMetadata: &shared.ExtensionAITasksTaskSelectMetadataParam{
									Instruction:   "What is the dominant color?",
									Field:         "primary_color",
									Vocabulary: []shared.ExtensionAITasksTaskSelectMetadataVocabularyUnionParam{
										{OfString: imagekit.String("black")},
										{OfString: imagekit.String("white")},
										{OfString: imagekit.String("red")},
										{OfString: imagekit.String("blue")},
										{OfString: imagekit.String("green")},
										{OfString: imagekit.String("beige")},
										{OfString: imagekit.String("brown")},
										{OfString: imagekit.String("multi-color")},
									},
									MaxSelections: imagekit.Int(1),
								},
							},
						},
					},
				},
			},
		},
	)
	if err != nil {
		panic(err.Error())
	}

	fmt.Println(result)
}
```
{% /tab %}

{% tab title="Java" %}

```java
import io.imagekit.client.ImageKitClient;
import io.imagekit.client.okhttp.ImageKitOkHttpClient;
import io.imagekit.models.files.FileUpdateParams;
import io.imagekit.models.files.File;
import io.imagekit.models.files.ExtensionItem;
import java.util.List;

ImageKitClient client = ImageKitOkHttpClient.builder()
    .privateKey("your_private_key")
    .build();

FileUpdateParams params = FileUpdateParams.builder()
    .addExtension(
        ExtensionItem.AiTasks.builder()
            .name("ai-tasks")
            .addTask(
                ExtensionItem.AiTasks.Task.SelectTags.builder()
                    .type(ExtensionItem.AiTasks.Task.SelectTags.Type.SELECT_TAGS)
                    .instruction("What product categories are visible in this image?")
                    .vocabulary(List.of("apparel", "footwear", "accessories", "bags", "jewelry"))
                    .maxSelections(2L)
                    .build()
            )
            .addTask(
                ExtensionItem.AiTasks.Task.SelectMetadata.builder()
                    .type(ExtensionItem.AiTasks.Task.SelectMetadata.Type.SELECT_METADATA)
                    .instruction("What is the dominant color?")
                    .field("primary_color")
                    .vocabulary(List.of("black", "white", "red", "blue", "green", "beige", "brown", "multi-color"))
                    .maxSelections(1L)
                    .build()
            )
            .build()
    )
    .build();

File result = client.files().update("fileId", params);
System.out.println(result);
```

{% /tab %}

{% tab title=".Net" %}
```csharp
using Imagekit;
using Imagekit.Models;

ImageKitClient client = new() { PrivateKey = "your_private_key" };

var result = await client.Files.Update("fileId", new()
{
    Extensions =
    [
        new ExtensionItemAITasks(
        [
            new ExtensionItemAITasksTaskSelectTags()
            {
                Instruction = "What product categories are visible in this image?",
                MaxSelections = 2,
                Vocabulary = ["apparel", "footwear", "accessories", "bags", "jewelry"],
            },
            new ExtensionItemAITasksTaskSelectMetadata()
            {
                Instruction = "What is the dominant color?",
                Field = "primary_color",
                MaxSelections = 1,
                Vocabulary = ["black", "white", "red", "blue", "green", "beige", "brown", "multi-color"],
            },
        ]),
    ],
});

Console.WriteLine(result);
```
{% /tab %}

{% /tabs %}

{% /linetab %}

{% /linetabs %}

{% callout style="info" %}
Both APIs also accept the [saved extension](/dam/saved-extensions) ID if you want to avoid specifying the task configuration JSON with each request.
{% /callout %}

## Restrictions and limits

1. Sub-tasks per AI Task configuration: 1-10 sub-tasks.
2. Vocabulary size: 1-30 items per task.
3. Vocabulary character length (select_tags only): Max 500 characters combined.
4. Instruction length: 1-2000 characters per task.
5. Custom metadata fields (select_metadata): Field must exist before use, vocabulary type must match field type.
6. Yes/no tasks: Must have at least one of `on_yes` or `on_no` defined.
7. Tag values: Cannot contain `%` character.
8. Processing time: Typically 1-5 seconds per image.


## Best practices

1. Start with 1-2 tasks on a small batch, validate results, refine configuration, then scale to production.
2. Keep instructions under 200 characters, be specific and direct. \
   ✅ "What types of furniture are visible?" \
   ❌ "Describe this image" (too broad)
3. For yes/no tasks, phrase instructions as yes/no questions. \
   ✅ "Does this image contain people?" \
   ❌ "Check if people are present" (not a question)
4. Use distinct vocabulary terms without overlap. \
   ✅ `["modern", "traditional", "rustic"]` \
   ❌ `["modern", "very modern", "somewhat modern"]` (ambiguous)
5. Test with sample images before large-scale deployment.
6. Review AI selections regularly and refine instructions based on results.

## Next steps

- [Create custom metadata fields](/dam/custom-metadata-fields) - Set up the fields you'll use with AI tasks.
- [Configure your first AI task](#applying-ai-tasks) - Start with a simple select_tags task.
- [Save your configuration](/dam/saved-extensions) - Create reusable extensions for your workflows.
- [Automate with Path policies](/dam/path-policy) - Set up automatic application based on upload paths.

Need help? Contact support or [join our community](https://community.imagekit.io).


---

# Source: /dam/drafts

---
title: Draft Assets
description: Keep your assets in draft state until you are ready to publish them.
---

Draft or unpublished assets are files and file versions that can only be accessed inside the ImageKit DAM, and their public URLs are not accessible outside of it. This feature is useful when you want to upload files to ImageKit and are still working on it but do not want to make them publicly accessible.

ImageKit allows you to upload files in draft or published state. You can also change the state of any file and its versions already present in the Media Library. You can check the file's state, whether it is published or draft, on its detail page.

![Published or draft status of a file (detail page)](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/published-draft-status.png?tr=w-1600>)

![Published or draft status of a file (list view)](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/published-draft-status-list.png?tr=w-1600>)

## Uploading assets as drafts by default

By default, files are uploaded as published. If you want to ensure that all files uploaded to ImageKit are in the draft or unpublished state, you can configure that option in the Media Library [settings](https://imagekit.io/dashboard/settings/media-library).

![Upload files in draft state by default](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/publish-file-on-upload-setting.png?tr=w-1600>)

## Publish or unpublish files

{% callout style="info" %}
You can only publish or unpublish at most 100 files at once.
{% /callout %}

You can publish or unpublish a single or multiple files at once. Select the files and open the 'Publish or unpublish file' popup. You can check the option to publish or unpublish a file here. If you want this change to apply to all versions of the files, check the 'Include file versions' option. This operation happens asynchronously.

![Publish or unpublish a files](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/publish-unpublish-file-modal.png?tr=w-1600>)

## Search for draft files

You can search for files and file versions in the draft state in the Media Library. Go to the Media Library and click on the search bar. In the advanced search filters, select 'File published' and choose the option to show only unpublished files.

![Search for unpublished files in the Media Library](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/search-unpublished-files.png?tr=w-1600>)

## Understanding the behaviour of URLs on unpublishing a file

When you unpublish a file, the file's public URL will no longer be accessible. In addition, a purge cache request is triggered for the unpublished file. It's important to note that these purge cache requests count towards the quota allocated to your account.

Even if you decide to unpublish only the current version of the file, the cache for all its other versions will also be cleared. However, the cache for file transformations made using path parameters will persist, while any transformations that include query parameters will be purged.

{% callout style="info" %}
Publishing or unpublishing a file version changes its URL.
{% /callout %}

When a file version transitions between the draft and published states, its URL will change accordingly. The URL changes because the `ik-obj-version` query parameter changes after the operation, and the old one is no longer valid. A file version's URL looks like this: `https://ik.imagekit.io/your_imagekit_id/file.jpg?ik-obj-version=iAg8gxkqo_QUBwqNeQrJzuyce2XB7Gc4`


---

# Source: /dam/auto-description

---
title: Adding Description using AI
description: Easily add a description to images within ImageKit's Digital Asset Management (DAM) platform.
---

With ImageKit's latest feature, you can effortlessly add a description to your images by using the AI-powered Auto Description extension.

{% callout style="info" %}
This operation consumes extension units. To learn more about extension unit pricing, refer to [this documentation](/how-pricing-works#extension-units-pricing).
{% /callout %}

## How to Add a Description using AI

1. Click on the Edit icon beside the **Description** field under the **File Info** section.

![Adding description](https://ik.imagekit.io/ikmedia/docs_images/extensions/add-description.png?tr=w-1600)

2. Click on the **AI Auto Description** icon in the corner of the text box.

![Using the auto-description extension](https://ik.imagekit.io/ikmedia/docs_images/extensions/add-auto-description-ext.png?tr=w-1600)

You will have a description generated based on the content of the image.

![Image with auto description](https://ik.imagekit.io/ikmedia/docs_images/extensions/img-with-auto-description.png?tr=w-1600)

{% callout style="info" %}
**Note:** You can also add or update the description manually in the text box.
{% /callout %}

{% callout style="info" %}
**Note:** You can specify the `ai-auto-description` extension during file upload.
{% /callout %}


---

# Source: /dam/history-and-audit-logs

---
title: Asset history and audit logs
description: Get an overview of changes in the ImageKit DAM. Filter out specific events or dive deep into asset-level change history.
---

{% callout style="info" %}
**Enterprise plan only** \
This feature is only available in custom enterprise pricing plans. If your plan has [central audit logs](/central-audit-logs), then this feature is also available.
{% /callout %}

ImageKit provides audit logs for all edit (update and delete) operations performed on DAM assets (files, folders, and media collections).

These logs can be helpful for organization administrators and auditors to diagnose and troubleshoot various issues, like misconfigurations, suspicious activities, etc.

Audit logs will be saved for these features:

- Sharing assets.
- Renaming assets.
- Updating custom metadata for assets.
- Using extensions like [background removal](/dam/edit-images#ai-powered-background-removal).
- Adding, updating or removing [public links](/dam/public-links) for assets.
- Moving assets.
- Deleting assets.
- Adding & removing tags or [auto-tags](/dam/tagging-media-assets#ai-powered-auto-tagging) for a file.
- Creating, Restoring, or Deleting a [file version](/dam/asset-versioning).
- Adding or removing assets from a media collection.
- Using [draft assets](/dam/drafts).

## Audit logs page

![DAM audit logs option in user menu](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/dam-audit-logs-in-menu.png?tr=w-1600)

If you're an administrator, you can access the DAM audit logs from the user menu in the screen's bottom left corner.

![DAM audit logs section](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/dam-audit-logs-screen.png?tr=w-1600)

Here, you can view all the logs in the table and the associated request and response details, such as method, endpoint, etc.

You can also filter these logs based on:

- Operations (like adding tags, renaming an asset, deleting an asset, adding [public links](/dam/public-links), and so on).
- Users (to view the entire history of their actions in the media library).
- Asset Path (e.g.: `/forest/tree.png`).
- Request ID (sent back in the HTTP response headers for API requests to ImageKit).
- Time Interval.

## View File Deletion History

Using the asset path, you can easily track when a file was deleted and view its historical changes.

![Asset Path Filter in DAM audit Logs](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/dam-audit-logs-path.png?tr=w-1600)

{% callout style="info" %}
You can combine the available filters to customize your search in the DAM audit logs.
{% /callout %}

## Asset History

![File Details Screen](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/media-lib-log-history-detail.png?tr=w-1600)

All users with view access to the Media Library can see the historical changes to each **file, folder, or media collection**.

![File History](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/media-lib-asset-history.png?tr=w-1600)

For folders and media collections, you can select the asset and open **"Folder details"** or **"Media collection details"** respectively to show their history.

![Folder History](https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/media-lib-log-folder.png?tr=w-1600)


---

# Source: /dam/pre-and-post-transformation-on-upload

---
title: Pre & Post-upload transformations
description: Transform an image or a video before or immediately after uploading it to the ImageKit DAM.
---

Using ImageKit.io, you can specify pre-transformations and post-transformations on image or video files at the time of upload.

Pre-transformations lets you modify image or video files before they're uploaded.

Post-transformations help you eagerly generate transformations after an image or video file has been uploaded to ensure fast delivery to your users.

## Pre-Transformation

A pre-transformation is applied **before** the file is uploaded to ImageKit's Media Library. You can only request a single pre-transformation on an asset.

Some things you can use a pre-transformation for:

- Features like [PNG compression](/image-optimization) to upload smaller files & save on storage costs.
- Change the height or width of an image or video file
- Add some text or logo to an image (using [overlays on Image](/add-overlays-on-images)) or a video (using [overlays on Video](/add-overlays-on-videos)).
- [Trim](/effects-and-enhancements#trim-edges---t) a video to a max duration.
- [Crop](/image-resize-and-crop#crop-crop-modes--focus) a profile image uploaded by a user.

## Post-Transformation

A post-transformation is applied **after** a file has been successfully in the Media Library. You can request multiple post-transformations on an asset.

These transformations are uploaded in addition to the original asset.

> Note: ImageKit also generates transformations for images and videos when accessed via their transformed URL for the first time. This is the default way to deliver transformed assets on websites and apps. You should use post-transformations only to generate complex transforms for large files readily available for fast delivery or to store the transforms permanently in the Media Library.

Some things you can use post-transformations for:

- Keeping the [thumbnail](/create-video-thumbnails) ready for a video.
- Using [Adaptive Bitrate Streaming](/adaptive-bitrate-streaming) to eagerly generate the best video streams for various devices.
- Create images with high [DPR (device pixel ratio)](/image-resize-and-crop#dpr---dpr) for premium mobile devices.

Supported types of post-transformations:

- For Images

  - `transformation` : See [Image Transformations](/image-transformation).
  - `gif-to-video` : (Only applicable for GIF files) See [GIF to MP4](/vector-and-animated-images#gif-to-video).

- For Videos

  - `abs` : See [Adaptive Bitrate Streaming](/adaptive-bitrate-streaming).
  - `thumbnail` : See [Get thumbnail from a video](/create-video-thumbnails).
  - `transformation` : For all transformations in [Video Transformations](/video-transformation) except ABS & thumbnail.

## How to Use Pre-Transformations and Post-Transformations?

During an [Upload API](/api-reference/upload-file/upload-file) call, specify a pre-transformation or post-transformations under the `transformation` request parameter.

The `transformation` parameter for the Upload API is an object with the following properties:

| Field Name    | Type             | Required                           | Description                                                                                                                                                               |
| ------------- | ---------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pre           | string           | -                                  | Request parameter for Pre-Transformation                                                                                                                                  |
| post          | array of objects | -                                  | Request parameter for Post-Transformation                                                                                                                                 |
| post.type     | string           | Yes                                | Type of required post-transformation. Allowed Values: `abs`, `thumbnail`, `transformation`, `gif-to-video` |
| post.value    | string           | If `post.type` is `transformation` | Value of required post-transformation.                                                                                                                                    |
| post.protocol | string           | If `post.type` is `abs` | ABS Streaming Protocol. Allowed Values: `hls`, `dash`See [Adaptive Bitrate Streaming](/adaptive-bitrate-streaming) for more details. |

> Note: A single pre-transformation is allowed per file, but you can combine multiple parameters (separated by commas) in the pre-transformation string.

For an example, if you want to modify a video to have [height](/video-resize-and-crop#height---h) as 300px, [width](/video-resize-and-crop#width---w) as 400px & have a 5px red [border](/common-video-transformations#border---b) before it's uploaded, you can specify `h-300,w-400,b-5_red` in the `pre` request parameter.

Example of a request with a pre-transformation:

```javascript
// Request Body (multipart/form-data) for Upload API
{
    /*
   ...rest of the Upload API request parameters
   */
    "transformation": {
        "pre": "rt-90"
    }
}
```

Example of a request with multiple post-transformations:

```javascript
// Request Body (multipart/form-data) for Upload API
{
    /*
   ...rest of the Upload API request parameters
   */
    "transformation": {
        "post": [
            {
                "type": "abs",
                "value: "sr-240_360_480_720_1080",
                "protocol": "dash"
            },
            {
                "type": "transformation",
                "value": "h-300"
            },
            {   
                "type": "thumbnail"
            }
        ]
    }
}
```

You can also combine pre-transformations and post-transformations in a single request. For example, we have a request with a pre-transformation to change a video's andto "500px" & then eagerly generate a thumbnail for it using a post-transformation.

```javascript
// Request Body (multipart/form-data) for Upload API
{
    /*
   ...rest of the Upload API request parameters
   */
    "transformation": {
        "pre": "w-500",
        "post": [
            {
                "type": "thumbnail"
            }
        ]
    }
}
```

> Note: Don't forget to stringify the contents of the `post` property before making a request.

## Asynchronous behaviour

- Post-transformations are always async.
- Pre-transformation is sync for image files but async for video files.

You can use [webhooks](/webhooks) to receive success and failure event notifications for pre & post-transformations after they complete execution.

You can integrate these events in your media workflow to ensure that a pre- or post-transformation happens as requested.

{% callout style="info" %}
Before receiving pre & post-transformation-related events, you must [configure webhooks](/webhooks) in your ImageKit account.
{% /callout %}

## Pre-Transformation Events

- `upload.pre-transform.success`
- `upload.pre-transform.error`

### upload.pre-transform.success

This event is triggered when a pre-transform happens successfully.

Example payload looks like below:

```js
{
    "type": "upload.pre-transform.success",
    "id": "c9a09db9-b5e2-49ed-ac2d-dfac88a6457a",
    "created_at": "2023-10-30T14:44:08.165Z",
    "request": {
        "x_request_id": "1bfe7bb6-afb3-4ccf-81f2-6bef7dae48e9",
        "transformation": "rt-90"
    },
    "data": {
        "fileId": "6540dbea002322e4ebe30de2",
        "name": "image_iEyH1dQme.jpg",
        "size": 2300818,
        "versionInfo": {
            "id": "6540dbea002322e4ebe30de2",
            "name": "Version 1"
        },
        "filePath": "/image_iEyH1dQme.jpg",
        "url": "https://stage-ik.imagekit.io/demo/image_iEyH1dQme.jpg",
        "fileType": "image",
        "height": 4608,
        "width": 3456,
        "thumbnailUrl": "https://stage-ik.imagekit.io/demo/tr:n-ik_ml_thumbnail/image_iEyH1dQme.jpg",
        "AITags": null
    }
}
```

Here is the description of all fields.

| Field                  | Description                                                                                                                        |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| type                   | Type of event.                                                                                                                     |
| id                     | Unique identifier of the event.                                                                                                    |
| createdAt              | Timestamp of the event in ISO8601 format.                                                                                          |
| request.x_request_id   | A unique request ID to identify the request.                                                                                           |
| request.transformation | The requested transformation as a string.                                                                                          |
| data                   | Same as the Upload API response. Refer [Upload File API](/api-reference/upload-file/upload-file) for the payload structure. |

### upload.pre-transform.error

Triggered if an error occurs during the pre-transformation. If you face any unexpected errors, contact our [support team](mailto:support@imagekit.io).

Example payload looks like below:

```js
{
    "type": "upload.pre-transform.error",
    "id": "502d1c52-e750-4277-8b64-52d43c2ec022",
    "created_at": "2023-10-31T13:49:28.046Z",
    "request": {
        "x_request_id": "722809dc-d6b7-4357-9262-74cdce554350",
        "transformation": "so-70"
    },
    "data": {
        "name": "vid_aKyz6pCpi.mp4",
        "path": "/myfolder/vid_aKyz6pCpi.mp4",
        "transformation": {
            "error": {
                "reason": "encoding_failed"
            }
        }
    }
}
```

Here is the description of all fields.

| Field                            | Description                                 |
| -------------------------------- | ------------------------------------------- |
| type                             | Type of event.                              |
| id                               | Unique identifier of the event.             |
| createdAt                        | Timestamp of the event in ISO8601 format.   |
| request.x_request_id             | A unique request ID to identify the request.    |
| request.transformation           | The requested transformation as a string.   |
| data.name                        | Name of the file.                           |
| data.path                        | Path of the file.                           |
| data.transformation.error.reason | Reason for the post-transformation failing. |

## Post-transformation Events

- `upload.post-transform.success`
- `upload.post-transform.error`

### upload.post-transform.success

This event is triggered when a post-transform happens successfully. Note that each post-transformation will have it's separate webhook sent.

Example payload looks like below:

```js
{
    "type": "upload.post-transform.success",
    "id": "08c12452-1efb-4c35-a28d-378c94e5674b",
    "created_at": "2023-10-30T15:04:59.462Z",
    "request": {
        "x_request_id": "0658b87f-bce3-41ae-8075-ebc26f44ff30",
        "transformation": {
            "type": "transformation",
            "value": "rt-90"
        }
    },
    "data": {
        "fileId": "653fc60e002322e4ebd5b5b7",
        "url": "http://stage-ik.imagekit.io/demo/video_wCqv9BewP.mp4?tr=rt-90",
        "name": "video_wCqv9BewP.mp4"
    }
}
```

Here is the description of all fields.

| Field                           | Description                                                                                               |
| ------------------------------- | --------------------------------------------------------------------------------------------------------- |
| type                            | Type of event.                                                                                            |
| id                              | Unique identifier of the event.                                                                           |
| createdAt                       | Timestamp of the event in ISO8601 format.                                                                 |
| request.x_request_id            | A unique request ID to identify the request.                                                                  |
| request.transformation.type     | Type of the requested post-transformation. Can be `transformation`, `abs`, `gif-to-video` or `thumbnail`. |
| request.transformation.value    | Value for the requested type of transformation.                                                           |
| request.transformation.protocol | Only applicable if `request.transformation.type` is `abs`. Possible values are `hls`, `dash`.             |
| data.fileId                     | Unique ID of the originally saved file.                                                                   |
| data.url                        | URL of the requested post-transformation.                                                                 |
| data.name                       | Name of the file.                                                                                         |

### upload.post-transform.error

Triggered if an error occurs during the pre-transformation. If you face any unexpected errors, contact our [support team](mailto:support@imagekit.io).

Example payload looks like below:

```js
{
    "type": "upload.post-transform.error",
    "id": "738f13b0-05e9-40cd-a856-8cc3e48b6e94",
    "created_at": "2023-10-31T13:51:10.627Z",
    "request": {
        "x_request_id": "49022ce9-e532-4a6c-8321-52925d519eec",
        "transformation": {
            "type": "transformation",
            "value": "so-70"
        }
    },
    "data": {
        "fileId": "65410644002322e4ebe6c880",
        "url": "http://stage-ik.imagekit.io/demo/vid_93HC1Daow.mp4?tr=so-70",
        "name": "vid_93HC1Daow.mp4",
        "path": "/vid_93HC1Daow.mp4",
        "transformation": {
            "error": {
                "reason": "encoding_failed"
            }
        }
    }
}
```

Here is the description of all fields.

| Field                            | Description                                                                                               |
| -------------------------------- | --------------------------------------------------------------------------------------------------------- |
| type                             | Type of event.                                                                                            |
| id                               | Unique identifier of the event.                                                                           |
| createdAt                        | Timestamp of the event in ISO8601 format.                                                                 |
| request.x_request_id             | A unique request ID to identify the request.                                                                  |
| request.transformation.type      | Type of the requested post-transformation. Can be `transformation`, `abs`, `gif-to-video` or `thumbnail`. |
| request.transformation.value     | Value for the requested type of transformation.                                                           |
| request.transformation.protocol  | Only applicable if `request.transformation.type` is `abs`. Possible values are `hls`, `dash`.             |
| data.fileId                      | Unique ID of the originally saved file.                                                                   |
| data.url                         | URL of the requested post-transformation.                                                                 |
| data.name                        | Name of the file.                                                                                         |
| data.path                        | Path of the file.                                                                                         |
| data.transformation.error.reason | Reason for the post-transformation failing.                                                               |


---

# Source: /dam/path-policy

---
title: Path policy
description: Learn how to enforce content and metadata governance at the folder level using path policies.
---

{% callout style="info" %}
**Enterprise plan only**  
This feature is available only in custom enterprise pricing plans and is currently in beta.
{% /callout %}

Path policies are a powerful feature for governing content within your Media Library. They allow you to apply specific rules and configurations at a folder level, ensuring that your assets are managed consistently and securely across different teams and use-cases.

Think of a path policy as a set of rules you can attach to any folder. Once attached, these rules automatically apply to all files and subfolders within it. This enables you to create a robust, scalable governance framework that adapts to your organization's needs, from enforcing metadata standards for product assets to protecting critical marketing banners from accidental changes.

You can create and manage path policies in the dashboard. Give the policy a name and description, configure the behavior of [custom metadata fields](#custom-metadata-fields-configuration), and optionally add custom JavaScript for the [upload](#upload-function-reference) and [validate](#validate-function-reference) functions.

To apply a path policy to a specific folder, either select the folder from the autocomplete menu on the path policy page, or right-click on any folder and select the policy name from the dropdown.

![Applying path policy from the right-click folder menu](https://ik.imagekit.io/ikmedia/docs_images/media-library/apply-path-policy.png?tr=w-1600)

## Important notes

1. A folder can have only one path policy assigned at a time.
2. When a path policy is applied to a folder, it automatically cascades to all of its subfolders. The effective path policy for any folder is determined by the nearest parent folder that has a policy assigned.
3. If a folder is moved or deleted, the path policy becomes ineffective. You must reapply it to the new location.

## Use-cases

Path policies allow you to solve common governance challenges by creating folder-level rules for your assets. You can enforce metadata standards, automate parts of the upload process, and protect critical assets from unintended changes. 

Here are some of the key problems you can solve:

*   **Enforce consistent metadata across different teams:** Different teams often have different metadata requirements. For example, your marketing team might need fields like `campaign` and `target_audience`, while your product team might need `product_id` and `version`. By assigning separate folders to each team, you can configure required fields, read-only status, and default values at the folder level instead of forcing one global rule.
* [Standardize file uploads](#file-uploads): Use the upload function to enforce naming conventions, restrict file types, prevent overwrites, set default statuses (like “draft”), or enable automated AI tagging and background removal during upload.
* [Protect critical assets](#asset-protection): Use the validate function to block modifications, deletions, or renaming of important files and folders.

## Custom metadata fields configuration

Select the fields from the list, and for each field you can configure the following options:

- **Required:** The field must always be filled in.
- **Read only:** The field’s value is fixed and cannot be modified by users.
- **Default value:** A pre-filled value that is applied if no other value is provided.

![Path policy applied to a folder with a selected custom metadata field](https://ik.imagekit.io/ikmedia/docs_images/media-library/path-policy-select-custom-metadata.png?tr=w-1600)

These settings override the global configuration for custom metadata fields, giving you fine-grained, folder-level control. Custom metadata settings apply to files within the folder. They do not apply to folders themselves.

Only the [custom metadata fields](/dam/custom-metadata) selected in the policy will be available for assets within the folder, both in the Media Library and through the API. If no fields are selected, it effectively disables custom metadata for that folder, and you won't be able to apply any custom metadata to assets within it.

## Examples

The possibilities with path policies are almost limitless. For example, you can:

1. **Automate transformations on upload** — e.g., apply background removal, enable AI auto-tagging, or generate captions.  
2. **Restrict uploads to specific users** based on their email addresses.  
3. **Protect AI tags** by preventing specific tags from being removed.  
4. **Enforce version history** so that file or folder copies always include previous versions.  
5. **Control asset movement** by blocking files or folders from being moved or copied out of a specific location.  
6. **Require cache purging** whenever files or folders are renamed.  

Below are some practical examples with code snippets to show how you can implement path policies.

### File uploads

#### Automatically generate transformations on upload

You can use the **upload function** to eagerly generate image and video transformations at upload time, without making separate transformation requests. This is especially useful for computationally expensive operations, such as AI-based image transformations or adaptive bitrate streaming outputs for videos.

The following upload function uses the [`transformation` parameter](/docs/api-reference/upload-file/upload-file) to generate Adaptive Bitrate Streaming manifests for videos using HLS protocol and the video thumbnail.

By generating these representations upfront, videos added to the Media Library are ready for adaptive streaming shortly after upload. The same pre-generated representations can also be used seamlessly in custom playback implementations.

```javascript
function handler(operation, payload, user) {
      payload.transformation = '{"post":[{"type":"abs", "value": "sr-240_360_480_720_1080", "protocol":"hls"},{"type":"thumbnail"}]}'
            
      return payload;
}
```

#### Enforce naming conventions and file size limits

You can use the **upload function** to validate and modify upload requests before they are processed. This is perfect for enforcing organizational standards at the point of upload.

The following upload function ensures that all files uploaded to the assigned folder follow a strict `product-id_variant-name.jpg` pattern and are no larger than 5MB.

```javascript
function handler(operation, payload, user) {
  // Enforce filename pattern: product-id_variant.jpg
  const validNameRegex = /^[a-z0-9-]+_[a-z0-9]+\.[a-z]{3,4}$/;
  if (!validNameRegex.test(payload.fileName)) {
    throw new Error(
      "Invalid filename. Must follow the pattern 'product-id_variant.ext'."
    );
  }

  // Restrict file type to JPEG/PNG and size to 5MB
  payload.checks = '"file.mime" IN ["image/jpeg","image/png"] AND "file.size" <= 5242880';
  
  return payload;
}
```

#### Automate AI-tagging and caption generation

You can automate content analysis and metadata generation by enabling AI-powered extensions during upload. The `extensions` parameter in the upload function allows you to apply features like [auto-tagging](/dam/tagging-media-assets#ai-powered-auto-tagging), [business-specific tagging using AI tasks](/dam/ai-tasks), and [captioning](/dam/auto-description).

The following `upload` function enables AWS Rekognition for auto-tagging, along with an AI-powered caption generator. This ensures that all assets uploaded to the folder are automatically tagged and described, saving manual effort and improving searchability.

```javascript
function handler(operation, payload, user) {
  // AI-powered auto-tagging and description
  payload.extensions = JSON.stringify([
    {
      name: "aws-auto-tagging",
      maxTags: 10,
      minConfidence: 80,
    },
    {
      name: "ai-auto-description",
    },
  ]);

  return payload;
}
```

#### Prevent accidental overwrites

To protect existing files in a specific folder from being overwritten, you can disable overwriting and ensure a unique filename is always used for new uploads.

```javascript
function handler(operation, payload, user) {
  payload.overwriteFile = "false";
  payload.useUniqueFileName = "true";
  return payload;
}
```

#### Upload assets in a "draft" state

You can ensure all assets uploaded to a specific folder are initially unpublished or in a "draft" state. This is useful for content that requires review before going live.

```javascript
function handler(operation, payload, user) {
  payload.isPublished = "false";
  return payload;
}
```

### Asset protection

#### Block all modifications in a folder

For large teams, protecting critical, live assets from accidental changes is vital. You can use the **validate function** to block potentially destructive operations like deletions or overwrites on specific assets or entire folders.

By applying a path policy to a folder containing critical assets (e.g., a `/live-banners` folder), you can prevent any modifications or deletions within that entire folder. The following validate function blocks any `DeleteFile` and `UpdateFile` operations, effectively making all assets within the folder read-only.

```javascript
function handler(operation, payload, user) {
  if (operation === "DeleteFile" || operation === "UpdateFile") {
    throw new Error(
      "Files in this folder are protected and cannot be modified or deleted."
    );
  }
}
```

#### Prevent renaming files and folders

To maintain a strict folder and file structure, you can block rename operations.

```javascript
function handler(operation, payload, user) {
  if (operation === "RenameFile" || operation === "RenameFolder") {
    throw new Error("Renaming files or folders is not allowed in this directory.");
  }
}
```

## Upload function reference

The **upload function** is a user-defined JavaScript function that runs before a file upload is executed. Use it to validate and/or modify the upload request body. Only the fields you modify are changed, everything else stays the same.

![Upload function](https://ik.imagekit.io/ikmedia/docs_images/media-library/path-policy-upload-function.png?tr=w-1600)

### Upload function signature
```javascript
function handler(operation, payload, user) {
  // Validate and/or modify fields on payload (all values are strings)
  return payload; // return the (optionally) modified payload
}
```

### Upload function arguments

* `operation` is always set to `Upload`.  
* `payload` matches the [Upload API request specification](/api-reference/upload-file/upload-file). All fields are available except the file buffer and the auth-related properties (`token`, `expire`, `signature` and `publicKey`). The `folder` field is read-only. Although `payload` is a JSON object, the Upload API uses multipart form data, so every value arrives as a string (including numbers, booleans, and nested JSON). If you modify any field, convert it back to a string before returning it.
* `user` is a JSON object with user details (`userId`, `userName`, `userEmail`) for dashboard uploads, and `undefined` for API-based uploads.  

Checkout [file upload](#file-uploads) related examples above to learn more.

## Validate function reference

The **validate function** is a user-defined JavaScript function that runs before any Media Library operation is performed. Use it to enforce rules by inspecting the request and throwing an error to reject invalid operations.

![Validate function](https://ik.imagekit.io/ikmedia/docs_images/media-library/path-policy-validate-function.png?tr=w-1600)

### Validate function signature

```javascript
function handler(operation, payload, user) {
  // Inspect payload & operation
  // Throw an error to reject the request. No return value is needed.
  if (operation === 'DeleteFolder') {
      throw new Error("Folder deletion is not allowed under this policy.");
  }
}
```

### Validate function arguments
* `operation` will be a string. Check the mapping below for all possible values.
* `payload` will be a valid JSON containing payload. It will vary based on the value of `operation`.
* `user` is a JSON object with user details (`userId`, `userName`, `userEmail`) for dashboard operations, and `undefined` for API-based operations.  

### Operation and payload

The dashboard UI is built using public-facing DAM APIs. Every action in the dashboard maps to an API. The table below outlines each operation and the corresponding API, along with the `payload` schema.

{% table %}
- **Operation (string)** {% width="50%" %}
- **payload schema** {% width="50%" %}
---
- **UpdateFile**

  For file metadata, tag/AI tag edits, or when extensions are applied.

  API operations:  
  [Update file details](/api-reference/digital-asset-management-dam/managing-assets/update-file-details)  
  [Remove AI tags](/api-reference/digital-asset-management-dam/managing-assets/remove-ai-tags-bulk)
- ```javascript
  {
    // ID of the file being updated
    fileId: string;
    // AI tag names to remove
    removeAITags?: string[];
    // Callback URL for async operations
    webhookUrl?: string;
    // Extension payloads. Check API ref
    extensions?: object[];
    // Full replacement list of tags
    tags?: string[];
    // "x,y,width,height"
    customCoordinates?: string;
    // Key–value map
    customMetadata?: { [k: string]: any };
    // New description
    description?: string;
    // Publication status. Check API ref
    publish?: object;
  }
  ```
---
- **DeleteFile**

  For single or multiple file deletions.

  API operations:  
  [Delete file](/api-reference/digital-asset-management-dam/managing-assets/delete-file)  
  [Delete multiple files](/api-reference/digital-asset-management-dam/managing-assets/delete-multiple-files)
- ```javascript
  {
    // File ID to delete
    fileId: string;
  }
  ```
---
- **CopyFile**

  For copying a file to a new location.

  API operations:  
  [Copy file](/api-reference/digital-asset-management-dam/managing-assets/copy-file)
- ```javascript
  {
    // Full path of the source file
    sourceFilePath: string;
    // Target folder path
    destinationPath: string;
    // Copy all versions
    includeFileVersions?: boolean;
  }
  ```
---
- **MoveFile**

  For moving a file to a new location.

  API operations:  
  [Move file](/api-reference/digital-asset-management-dam/managing-assets/move-file)
- ```javascript
  {
    // Current full path of the file
    sourceFilePath: string;
    // Target folder path
    destinationPath: string;
  }
  ```
---
- **RenameFile**

  For renaming a file.

  API operations:  
  [Rename file](/api-reference/digital-asset-management-dam/managing-assets/rename-file)
- ```javascript
  {
    // Current full path of the file
    filePath: string;
    // New file name (without path)
    newFileName: string;
    // Purge cached variants
    purgeCache?: boolean;
  }
  ```
---
- **DeleteFileVersion**

  For deleting a specific file version.

  API operations:  
  [Delete file version](/api-reference/digital-asset-management-dam/managing-assets/delete-file-version)
- ```javascript
  {
    // File whose version will be deleted
    fileId: string;
    // Version ID to delete
    versionId: string;
  }
  ```
---
- **RestoreFileVersion**

  For restoring a specific file version.

  API operations:  
  [Restore file version](/api-reference/digital-asset-management-dam/managing-assets/restore-file-version)
- ```javascript
  {
    // File to restore a version for
    fileId: string;
    // Version ID to restore
    versionId: string;
  }
  ```
---
- **CreateFolder**

  For creating a new folder.

  API operations:  
  [Create folder](/api-reference/digital-asset-management-dam/managing-folders/create-folder)
- ```javascript
  {
    // Name of the new folder
    folderName: string;
    // Path where the folder will be created
    parentFolderPath: string;
  }
  ```
---
- **DeleteFolder**

  For deleting a folder.

  API operations:  
  [Delete folder](/api-reference/digital-asset-management-dam/managing-folders/delete-folder)
- ```javascript
  {
    // Full path of the folder to delete
    folderPath: string;
  }
  ```
---
- **CopyFolder**

  For copying a folder.

  API operations:  
  [Copy folder](/api-reference/digital-asset-management-dam/managing-folders/copy-folder)
- ```javascript
  {
    // Full path of the source folder
    sourceFolderPath: string;
    // Target parent path
    destinationPath: string;
    // Copy all file versions
    includeFileVersions?: boolean;
  }
  ```
---
- **RenameFolder**

  For renaming a folder.

  API operations:  
  [Rename folder](/api-reference/digital-asset-management-dam/managing-folders/rename-folder)
- ```javascript
  {
    // Current full path of the folder
    folderPath: string;
    // New folder name
    newFolderName: string;
    // Purge old assets cache
    purgeCache?: boolean;
  }
  ```
---
- **MoveFolder**

  For moving a folder.

  API operations:  
  [Move folder](/api-reference/digital-asset-management-dam/managing-folders/move-folder)
- ```javascript
  {
    // Current full path of the folder
    sourceFolderPath: string;
    // Target parent path
    destinationPath: string;
  }
  ```
---
- **AddTags**

  Triggers when tags are added to a file in bulk.

  API operations:    
  [Add tags](/api-reference/digital-asset-management-dam/managing-assets/add-tags-bulk)
- ```javascript
  {
    // File to tag
    fileId: string;
    // Tags to add
    tags: string[];
  }
  ```
---
- **RemoveTags**

  Triggers when tags are removed from a file in bulk.

  API operations:    
  [Remove tags](/api-reference/digital-asset-management-dam/managing-assets/remove-tags-bulk)
- ```javascript
  {
    // File to untag
    fileId: string;
    // Tags to remove
    tags: string[];
  }
  ```
{% /table %}

## Limitations and important notes

1. **Runtime limits:** Each function (`Upload` or `Validate`) must finish within **300 ms** and use no more than **8 MB** of memory. Exceeding either limit results in a `400` error.  
3. **Keep it simple:** Functions cannot import external modules, make network requests, or perform other asynchronous operations. Only plain JavaScript logic is supported.  
4. **Syntax correctness:** The JavaScript code inside the handler must be syntactically valid and follow the correct function signature. Invalid syntax or a mismatched signature will cause errors, blocking API calls and all operations on any folder where the policy is applied.  

   ✅ Correct — The handler defines all required arguments (`operation`, `payload`, `user`) and is syntactically valid:
   
   ```js
    function handler(operation, payload, user) {
      // Your business logic
    }
   ```  

    ❌ Incorrect — Missing an argument:

    ```js
    function handler(operation, payload) {
      if (!payload.fileName.contains("imagekit")) {
        // Your business logic
      }
    }
    ```

4.  **Error handling:** If your function throws an error, the API responds with a `400` error containing the policy name and your error message. Whatever string you pass to `new Error()` becomes the `message` in the response.  
    
    ✅ Correct  

    ```js
    function handler(operation, payload, user) {
      if (!payload.fileName.contains("imagekit")) {
        throw new Error("I don't like this filename, change it.");
      }
    }
    ```  


    ❌ Incorrect  

    ```js
    function handler(operation, payload, user) {
      if (!payload.fileName.contains("imagekit")) {
        // Returning or console.log won't work
        return "I don't like this filename, change it.";
      }
    }
    ```

5.  **Single entry point:** Each function type (Upload / Validate) must have exactly one top-level handler function. Multiple handlers are not supported.
6. **Folder immutability in uploads:** The `payload.folder` path cannot be modified within an `Upload` function.  
7. **Stringified upload body:** All values in the `payload` of an `Upload` function are strings. If you modify a value, it must remain a string. Since the upload API uses multipart form data, every field is treated as a string.
8. **Policy application:** A folder can only have one policy. It cascades automatically to all subfolders, unless a subfolder has its own policy.  
9. **Metadata sync:** If you update a global custom metadata field (e.g., change a dropdown list), you must manually update any path policies using that field to keep default values valid.  
10. **Field deletion:** A custom metadata field cannot be deleted while it is referenced in any path policy.


---

# Source: /dam/saved-extensions

---
title: Saved Extensions
description: Create reusable extension configurations combining AI tasks, auto-tagging, background removal, and more. Easily apply saved extensions across your media library via UI or API.
---

Saved extensions let you create reusable configurations for different ImageKit extensions and apply them across multiple files, either from the dashboard or via APIs. For example, instead of repeatedly selecting the same set of options for background removal or repeatedly creating a long list of sub-tasks within [AI tasks](/dam/ai-tasks), you can create a reusable configuration of these extensions, save it, and reference it by its ID in APIs and the UI.

**Key benefits:**
- Reusability: Define complex configurations once, use everywhere with just their IDs.
- Consistency: Ensure the same processing logic across all files to eliminate manual errors.
- Team collaboration: Share standardized configurations across your organization.
- Simplified API calls: Reference by ID instead of repeating full JSON configuration.

## Supported extension types

Saved extensions work with all ImageKit extensions:

| Extension Type | Common Use Cases |
|----------------|------------------|
| **[AI tasks](/dam/ai-tasks)** | Product categorization, brand compliance, quality control with controlled vocabularies |
| **[Auto-tagging](/dam/tagging-media-assets#ai-powered-auto-tagging)** | General image categorization and discovery with free-form AI tags |
| **[Auto-description](/dam/auto-description)** | Accessibility, SEO, and content management with AI-generated descriptions |
| **[Remove background](/dam/edit-images#ai-powered-background-removal)** | Product photography, e-commerce, and graphic design automation |

The primary benefit of saved extensions is for AI tasks that inherently have complex JSON configurations containing multiple sub-tasks, vocabularies, and conditional logic. Instead of maintaining and adding the entire JSON of an AI task every time, you can simply reference the saved extension ID in the APIs and from the dashboard.

{% callout style="info" %}
We have included sample configurations for different extension types in this documentation and under [AI tasks](/dam/ai-tasks) to make it easier for you to copy-paste and modify the configurations as per your requirements.

Alternatively, your technology team, or [ImageKit's support team](mailto:support@imagekit.io), or your dedicated Customer Success Manager, can also help you configure these extensions.
{% /callout %}


## Managing saved extensions via dashboard

### Creating a saved extension

Go to **Settings → Media Library → Saved Extensions** and click **Add New**.

![Create saved extension](https://ik.imagekit.io/ikmedia/docs_images/media-library/ai-tasks/saved-extension.png?tr=w-1600)

Fill in the form:
- **Name**: Descriptive name for the extension (e.g., "Product Image Classifier")
- **Description**: Explain what this extension does
- **Configuration**: The complete extension JSON. Sample configurations are given below.

Click **Create** to save.

### Sample configurations for Saved Extensions

{% linetabs %}

{% linetab title="Background Removal" %}

```js
{
  "name": "remove-bg",
  "options": {
    "add_shadow": false,
    "semitransparency": true,
    "bg_color": "81d4fa", //if used, bg_image_url must be empty
    "bg_image_url": "<background_image_url>" //if used, bg_color must be empty
  }
}
```

{% /linetab %}

{% linetab title="Auto Tagging" %}

```js
{
  "name": "google-auto-tagging", //or "aws-auto-tagging",
  "minConfidence": 70, //number
  "maxTags": 5 //number
}
```
{% /linetab %}

{% linetab title="Auto Description" %}

```js
{
  "name": "ai-auto-description"
}
```
{% /linetab %}

{% linetab title="AI Tasks" %}
Refer to [AI Tasks documentation](/dam/ai-tasks).

{% /linetab %}

{% /linetabs %}

### Viewing saved extensions

All saved extensions are listed at **Settings → Media Library → Saved Extensions** with their names, descriptions, and IDs.

![Saved extensions list](https://ik.imagekit.io/ikmedia/docs_images/media-library/ai-tasks/saved-extension-list.png?tr=w-1600)

Click any extension to view its full configuration.

### Editing and deleting

Click the three-dot menu on any saved extension to **Edit** or **Delete** it.

{% callout style="warning" %}
Changes to saved extensions apply to future uses only. Files already processed with the old configuration are not affected.
{% /callout %}

## Managing saved extensions via API

Use the Saved Extensions API for programmatic CRUD operations:

- [Create saved extension](/docs/api-reference/digital-asset-management-dam/saved-extensions/create-extension)
- [List saved extensions](/docs/api-reference/digital-asset-management-dam/saved-extensions/list-extensions)
- [Get saved extension details](/docs/api-reference/digital-asset-management-dam/saved-extensions/get-extension)
- [Update saved extension](/docs/api-reference/digital-asset-management-dam/saved-extensions/update-extension)
- [Delete saved extension](/docs/api-reference/digital-asset-management-dam/saved-extensions/delete-extension)

The API returns a unique `id` for each saved extension, which you use in upload and update operations.

## Using saved extensions

### During upload (UI)

When uploading files, expand **Settings** and select saved extensions from the list.

![Upload with saved extensions](https://ikmedia.imagekit.io/docs_images/media-library/ai-tasks/upload-file.png?updatedAt=1767860195865?tr=w-1600)

All selected files will be processed with the chosen saved extensions.

### On existing files (UI)

Select files in Media Library → Right-click → **Apply Saved extensions** → Choose from the list → Apply

![Apply saved extensions](https://ik.imagekit.io/ikmedia/docs_images/media-library/ai-tasks/ai-tasks-apply-existing-assets.png?tr=w-1600)

![Apply to existing files](https://ik.imagekit.io/ikmedia/docs_images/media-library/ai-tasks/ai-tasks-apply-existing-assets-pick.png?tr=w-1600)

### During upload (API)

Reference the saved extension ID in the `extensions` parameter:

```bash
curl -X POST 'https://upload.imagekit.io/api/v2/files/upload' \
  -u private_key: \
  -F 'file=@image.jpg' \
  -F 'fileName=image.jpg' \
  -F 'extensions=[{
    "name": "saved-extension",
    "id": "ext_abc123def456"
  }]'
```

### On existing files (API)

Use the Update File Details API:

```bash
curl -X PATCH 'https://api.imagekit.io/v1/files/:fileId/details' \
  -H 'Content-Type: application/json' \
  -u private_key: \
  -d '{
    "extensions": [{
      "name": "saved-extension",
      "id": "ext_abc123def456"
    }]
  }'
```


---

# Source: /dam/sharing-and-collaboration

---
title: Sharing and collaboration
description: Share assets and media collections with internal users (or groups) and external parties and manage permissions.
---

ImageKit's Digital Asset Management solution allows you to organize, manage, and share your assets in files and folders. Using [Media Collections](/dam/media-collection), you can create virtual groups of assets regardless of their current location in the DAM. This provides a simple way for users to share and collaborate on those assets.

ImageKit allows you to set access and permission levels for each user on your assets as per your organization's needs. Based on your business requirements, you can decide which assets a user can access and what actions they can perform on them.

## Access and permission management

{% callout style="info" %}
A new Media Library Restricted Access user will see an empty Media Library under the "Shared with me" section until any files, folders, or media collections are shared with them.
{% /callout %}

ImageKit allows granular access control on media collections, files, and folders (and therefore their subfolders and files) with selected restricted access users or user groups with different permissions ranging from view-only to manage access.

The account administrator is responsible for setting up the file and folder hierarchy and assigning appropriate permission levels across users and user groups. 

If you can grant a user or a user group "Manage" access to the assets, they would have access to share files, folders, and media collections with other user groups or particular users with any access level. This means that more users would end up with access to assets than what you initially added. Elevated permission levels also allow users to delete resources or carry out other such destructive actions on them.

Users with the following roles or permissions can share assets and media collections with restricted media library users and user groups:

1. Account administrator
2. Developer
3. Media library full access
4. Media library restricted access with "Can manage" permission on an asset

## How to share assets and media collections?
You can share files, folders, and media collections with other restricted media library users and user groups as given below. 

- [Share files and folders](/dam/manage-assets#share-files-and-folders)
- [Share media collection](/dam/media-collection#share-media-collections)

To share an asset or media collection, click the "Share" button in the dropdown menu after selecting it. A popup will appear, allowing you to select the users and user groups and specify their access level under the "User & user groups" tab. You may also view, change, or remove the permissions of existing users and user groups with access to the asset or collection. You can also see the media collections to which the selected asset has been added by clicking on the "Media collection associations" tab in this popup.

This document only covers sharing files with users and user groups already added to your ImageKit DAM. However, you can also share them with users who are not part of your ImageKit DAM by generating a public link. We have covered [Public links](/dam/public-links) separately.

## Understanding access to assets and media collections

{% callout style="info" %}
Access control and permissions can only be managed for Media Library Restricted Access users.
{% /callout %}

They can only perform actions on files and folders that are shared with them based on their permission levels. However, such users can create new media collections.

An asset or media collection can be shared with users in the following ways:

1. **Sharing with users**
 A user can be given access to any asset or media collection. This is useful when giving certain users access to specific resources with appropriate permission levels.

2. **Sharing with user groups**
We usually work as teams; for most requirements, the entire team needs the same access and permissions on assets. You can streamline your workflow by creating user groups with all relevant users and then sharing the assets or media collection with the user group, granting access to all associated users in one go.

3. **By asset or media collection ownership**
 A user who creates a file, folder, or media collection owns that resource, and has the "Can manage" permission on it.

 For example, if a user creates a folder, they can perform all operations that "Can manage" permission level allows on the folder and all the assets inside it. Even if you revoke the access through which they could create the folder in that directory, they would still have the same access to the folder they created and any subfolders and files inside it.

### Understanding how a user's role change affects access

When a user's role is changed from "Media Library Restricted Access" to some other role or when any such user is deleted, they are removed from the user group. If their role is changed back to "Media Library Restricted Access", they would still have access to all the assets and media collections that were previously individually shared with them. However, they won't be added back to any of the user groups they were previously added to.

### Understanding how deleting user groups affects access

When a user group is deleted, users lose access to any files, folders, or media collections they had access to through the group unless it was shared with them directly.

## Recommended workflow

It is important to plan out your DAM workflow carefully. Your media collections, folders, and files should be organised such that your team members have appropriate access and permissions to the right resources.

To help you establish your workflow, we recommend the following steps:

1. Define your teams.
 Consider the various teams in your organization. Do you, for example, have a design, marketing, sales, and technology team? This lets you think about different teams and what permission and access they will need in the next step. Once you have determined that, you can add them to their respective user groups.

2. Organize your assets, folders, and media collections.

A very important aspect of setting up your workflow is creating the right folder structure. Remember that permissions would cascade down to its subfolders, meaning that if you grant a certain level of access to a folder, you can't restrict that access from any of its subfolders or files.

Create separate folders for each team (or user) in the root media library and grant appropriate permissions. Avoid deep nesting of folders, as this will increase the chances of permission escalation by mistakenly giving higher permission to some parent folders. Instead of a deep nested folder structure, use custom metadata for better organization.

You can also add individual assets and folders to a media collection and share the collection with relevant stakeholders with the proper access level. This helps organize and share a lot of scattered assets and folders from one central location.

3. Share assets and media collections with your team members.
Grant the appropriate level of access for each user or user group you want to share it with. Share it with an individual user if they don't have the right access to that asset via their group.

For example, the marketing team will need sufficient permission to add, remove, and modify assets in certain folders. Technology or the sales team might only need read/view permission for specific folders containing brand assets.

If you create a new user with Media Library Restricted Access, the Media Library will appear empty to them initially. They won't be able to upload assets to the Media Library either. You can share a folder with at least "Can contribute" permission so that they can start uploading files to it.

## Permissions

### Understanding permissions on assets and media collections
An asset can be shared with a user in different ways and with varying permission levels. The permission level on the asset would be the highest permission the user derives through all these means. For example, suppose a user is in multiple groups, and the same folder is shared with each group at different permission levels. In that case, the highest of those permission levels applies to the user for that asset.

When you share a folder, its permission level cascades down to all its subfolders and files.

A user or user group's permission level can be increased in a subfolder of a folder to which they already have access, but it cannot be lowered.

If you don't share a file and folder (or any parent of that folder) with a particular user or group by any means, those users will not be able to see that folder or the contents inside it. Even when performing a search on all folders, the results will only include folders where the user has at least view permission. Furthermore, if you don't share any folders with a particular user or user group, then those users won't have access to any assets in the Media Library.

If assets are added to a media collection, and that media collection is shared with a user or user group who otherwise do not have access to that asset, those users will still be able to take all "Can view" permission actions on the assets in that media collection. However, they won't be able to modify those assets unless they have "Can contribute" or "Can manage" permission on them.

{% callout style="info" %}
You cannot share the Home (root) of the media library with any Media Library Restricted Access user.
{% /callout %}

### File and folder permission levels

An ImageKit account user with relevant permissions can view and manage access permissions on an asset (files and folders) for restricted access users and user groups. For an asset, you can assign one of the following permission levels:

1. Can view
2. Can contribute
3. Can manage

The table below summarises the operations that can be performed on media library assets at each permission level:

| Operation                        | Can view | Can contribute | Can manage |
| -------------------------------- | -------- | -------------- | ---------- |
| View & search assets             | ✅        | ✅              | ✅          |
| View file & file version details | ✅        | ✅              | ✅          |
| Download file                    | ✅        | ✅              | ✅          |
| Download assets as zip           | ✅        | ✅              | ✅          |
| View downloads                   | ✅        | ✅              | ✅          |
| View threads and comments        | ✅        | ✅              | ✅          |
| Add new comment and replies      |          | ✅              | ✅          |
| Edit and delete own comments     |          | ✅              | ✅          |
| Modify own reaction on comments  |          | ✅              | ✅          |
| Resolve and unresolve thread     |          | ✅              | ✅          |
| Create new folder                |          | ✅              | ✅          |
| Upload file & new file version   |          | ✅              | ✅          |
| Restore file version             |          | ✅              | ✅          |
| Update custom metadata           |          | ✅              | ✅          |
| Edit tags                        |          | ✅              | ✅          |
| Add auto tags (extension)        |          | ✅              | ✅          |
| Remove background (extension)    |          | ✅              | ✅          |
| Remove tags                      |          | ✅              | ✅          |
| Edit image                       |          | ✅              | ✅          |
| Edit custom focus area           |          | ✅              | ✅          |
| Copy asset                       |          | ✅              | ✅          |
| Add asset to media collections   |          | ✅              | ✅          |
| Delete a comment thread          |          |                | ✅          |
| Rename file                      |          |                | ✅          |
| Move asset                       |          |                | ✅          |
| Publish or unpublish file        |          |                | ✅          |
| Delete file version              |          |                | ✅          |
| Delete asset                     |          |                | ✅          |
| Share asset                      |          |                | ✅          |
| View public links                |          |                | ✅          |
| Create public links              |          |                | ✅          |
| Edit public links                |          |                | ✅          |
| Delete public links              |          |                | ✅          |

### Media collection permission levels

An ImageKit account user with relevant permissions can view and manage access permissions on media collections for restricted media library users and user groups. For a media collection, you can assign one of the following permission levels:

1. Can view
2. Can contribute
3. Can manage

The table below summarises the operations that can be performed on media collections and assets added to them at each permission level:

| Operation                           | No permission | Can view | Can contribute | Can manage |
| ----------------------------------- | ------------- | -------- | -------------- | ---------- |
| Create new media collection         | ✅             | ✅        | ✅              | ✅          |
| View & search media collections     |               | ✅        | ✅              | ✅          |
| View assets in media collection     |               | ✅        | ✅              | ✅          |
| View file & file version details    |               | ✅        | ✅              | ✅          |
| Download media collections as zip   |               | ✅        | ✅              | ✅          |
| Add assets to media collection      |               |          | ✅              | ✅          |
| Rename media collection             |               |          |                | ✅          |
| Remove assets from media collection |               |          |                | ✅          |
| Delete media collection             |               |          |                | ✅          |
| Share media collection              |               |          |                | ✅          |
| View public links                   |               |          |                | ✅          |
| Create public links                 |               |          |                | ✅          |
| Edit public links                   |               |          |                | ✅          |
| Delete public links                 |               |          |                | ✅          |


---

# Source: /dam/public-links

---
title: Public links
description: Learn how to create time-bound, password-protected public links for assets and media collections in the ImageKit media library.
---

Using public links, you can share assets and media collections with users who are not part of your ImageKit account. Public links allow limited view-only access to your assets and media collections; users accessing them via public links cannot edit or delete them. Moreover, you can password-protect and set expiration dates on public links.

## Understanding access to assets and media collections via public links

When accessing an asset or media collection using a public link, a user can-
- View file metadata like dimensions, size, and embedded metadata. However, they won't be able to see details like tags, AI tags, custom coordinates, custom metadata, ownership details, or comments on that file.
- Download assets and media collections.
- View private files. However, whether a file is private or not is not visible in this view.
- View draft files inside shared folders and media collections, if exposed using the "Expose unpublished files" checkbox. However, whether a file is published or not is not visible in this view. This can only be done if you have the [Draft assets](/dam/drafts) feature enabled.
- View only the current version of the file. Any non-current file version will not be accessible via the public link.

Note that when an asset or media collection is deleted or moved, its public link is also deleted.

![Public links view](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/public-links-view.png?tr=w-1600>)

{% callout style="info" %}
**Limits**
- A maximum of 5 public links can be created for a single asset or media collection.
- Across all assets and media collections in an account, a maximum of 100 public links can be created. This limit is configurable.
{% /callout %}

## Creating and managing public links for assets and media collections

Select the asset or media collection you want to share and right-click on it. From the menu, select the "Public links" option. Here you can create or manage any existing public link configurations.

![Right-click menu location for public links](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/right-click-menu-public-links.png?tr=w-1600>)

![Form for creating a new public link](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/new-public-link-form.png?tr=w-1600>)

You can configure the following options for a public link:
- Validity timeframe: You can set the "Validity start" and/or "Validity end" dates for any public link. At any time that is either earlier than the "Validity start" time or later than the "Validity end" time, the link will not work. After a link has expired, it will be automatically deleted.
- Password protection: If a password is set for a public link, any user trying to access the link will be prompted to enter that password before access is granted. This password can be changed at any time without affecting the URL of the public link.
- Expose unpublished assets: When creating a public link for a folder or media collection, this setting defines whether any unpublished assets that fall under that folder or media collection can be accessed via the link or not. If a public link is created for a single file, it will be accessible via the link, regardless of its publication status. Note that this option is only available if you have this feature enabled.

### Managing all public links from media library settings

You can view, edit, and delete public links for all assets and media collections in the Media Library [settings page](https://imagekit.io/dashboard/settings/media-library). Media library restricted users do not have access to this page.

![Table displaying all public links in an account](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/all-public-links-table-settings-page.png?tr=w-1600>)

## Download as a zip in public links

For a logged-in ImageKit user, downloads triggered via a public link will appear on the downloads page with the "Via public link" field set to "Yes".

For users accessing a public link, the downloads page will only display downloads triggered by that public link for their currently active session.

![Downloads page public links indicator](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/downloads-page-public-links.png?tr=w-1600>)

## Central audit logs

If [DAM audit log](/dam/history-and-audit-logs) feature is included in your pricing plan, you can view logs of all create, update, and delete operations on public links.

## Access control and permissions

A Media Library Restricted Access user needs at least "Manage" permission on an asset or media collection to view, create, edit, or delete its public links. Learn about actions that can be performed on media collections and assets by restricted access users [here](/dam/sharing-and-collaboration#understanding-access-to-assets-and-media-collections).


---

# Source: /dam/asset-versioning

---
title: Asset versioning
description: Learn how to manage and restore different versions of assets in the ImageKit Media Library.
---

Versioning in ImageKit keeps multiple variants of an asset. It allows you to preserve, retrieve, and restore every version of any asset stored in your DAM. As a result, you can recover more quickly from unintended user actions with versioning.

If ImageKit receives multiple upload requests for the same asset with the same name and location, it creates a new version.

{% callout style="info" %}
Versioning is enabled on all accounts on any pricing plan. All current plus previous versions of an asset count towards your total storage usage.
{% /callout %}

The following actions can be performed from the dashboard and programmatically via the APIs:

1. Create a new file version by uploading a file with the same name and location as an existing file. This can be done by upload API or [AI-powered background removal operation](/dam/edit-images#ai-powered-background-removal), which uploads a new file with the background removed.
2. Restore the file to a previous version.
3. Delete any non-current file version.
4. Get any file version's details.
5. Get details of all versions of a file.
6. Search for file versions.

{% callout style="warning" %}
**Cache clearing on new version creation**\
When you create a new version by uploading a file from the dashboard, all cached transformations for that asset are automatically cleared. This means new requests will re-process the file, consuming VPUs for video transformations and Extension Units for AI transformations.
{% /callout %}

{% youtube src="https://www.youtube.com/embed/WyOWZ50p-Vc?si=6vnrj-thT5jPRT6Q" /%}   

{% callout style="info" %}
**Version limits**\
An asset can have a maximum of 100 versions.
{% /callout %}

## Searching for file versions in the Media Library

Go to your [Media Library](https://imagekit.io/dashboard/media-library) in ImageKit's dashboard and click the search bar. To get the desired outcome, check the option to include file versions in search results. You can identify if an asset is a file version by looking at a badge marking it.

{% callout style="info" %}
**Viewing versions** \
Non-current file versions do not appear in the Media Library by default. You have to search for file versions or navigate to the details page of an asset to view its different versions.
{% /callout %}

## Media Library operations

When a file version is selected, the "Restore version" and "Delete version" options are available in the context menu. Using these options, you can restore the selected file version to the current version of the file or delete the file version respectively. These actions are also available in the menu of the asset details page of file versions. Note that these operations are only available for the non-current version of a file.

![File version context menu options](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/version-context-menu.png?tr=w-1600>)

### Copy/move file

When a file is copied/moved to a destination with an existing file of the same name, the source file versions are appended to the destination file version's history.

In a copy operation, an option to copy all file versions in the folder selection drawer is available. If this is not checked, which is the default behavior, only the current file version is copied. In contrast, all source file versions are moved to the destination in the move operation.

![Include file versions in copy operation](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/copy-include-versions.png?tr=w-1600>)

{% callout style="info" %}
**File and file version operations** \
Media Library operations available for files (current version) and file versions (non-current versions) are different. For example, you cannot update tags, copy, move, rename, edit, download/download (as zip), use extensions, etc., on non-current versions of a file.
{% /callout %}

## Details page

You can choose the version you want to view on the asset details page by clicking the dropdown at the top and selecting the desired version.

![Non-current file version details page](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/non-current-version-details.png?tr=w-1600>)

![Current/latest file version details page](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/current-version-details.png?tr=w-1600>)

## URLs and transformations

You can access and transform any version using its unique URL and ImageKit transformation parameters.


---

# Source: /dam/comments-on-assets

---
title: Comments on assets
description: Learn how to add comments, provide feedback, and collaborate on assets within the ImageKit Digital Asset Management (DAM).
---

In ImageKit DAM, users can seamlessly provide feedback, share ideas, and discuss various aspects of assets directly within the platform. Whether it's images, videos, or other files, commenting becomes a streamlined process, fostering efficient teamwork and facilitating clearer communication.

## Contextual comment on images

Users can add comments anywhere on an image by clicking on the desired point. This allows for precise feedback and discussion tailored to specific areas of interest within the image. Users can also add comments without specific contextual points by clicking the "Add comment" button.

![Add contextual comment on image](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/contextual-comment-on-image.png?tr=w-1600>)

## Contextual comment on videos

Comments on videos are timestamped, ensuring that discussions are linked to specific moments in the video. Users can easily reference these timestamps for clarity and context during discussions.

![Contextual comment on video with timestamp and marker](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/contextual-comment-on-video.png?tr=w-1600>)

## Commenting on non-media files

Users can still add comments using the "Add Comment" button for non-image and video files, such as PDF or TXT. While these comments may not be tied to specific elements within the file, they still serve as valuable feedback and discussion points.

## Limitations on comments

- A file can have at most 50 threads.
- A thread can have at most 50 comments.
- A comment can have at most 500 characters.

## Resolving comments

Users can resolve comments once they have been addressed or no longer require further action. This helps maintain clarity and organization within comment threads.

## Sorting and filtering

Users can sort comments by recently created or recent activity, enabling them to prioritize discussions based on their relevance and urgency. Additionally, comments can be filtered by resolved and unresolved threads for easier navigation and management.

![Sort and filter comments as per your need](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/all-threads-filter.png?tr=w-1600>)

## Comments and versions
Comments are associated with specific versions of files, ensuring that discussions remain linked to the appropriate iteration. This allows for continuity and context preservation, even as files are updated or revised.

![Comments associated with versions](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/comment-associated-with-versions.png?tr=w-1600>)

## Edit and delete
Users can edit their comments for clarity or correctness and delete them if necessary, ensuring that discussions remain accurate and relevant.

## Copy and Share Link
Users can copy and share links to specific threads. This allows them to reference discussions or share them with relevant stakeholders easily.

## Emoji reactions and rich text editor
Users can express their reactions to comments using emojis, adding a layer of nuance and engagement to discussions. The rich text editor also allows users to format their comments for better readability and emphasis.

## Mention other users
Users can mention other users in their comments, drawing their attention to specific discussions or seeking their input. This fosters collaboration and ensures that relevant stakeholders are engaged in the conversation.

## Watchers and Notifications

Watchers of a thread include:
- The file owner
- Anyone commenting on the thread
- Users mentioned within the thread discussion

This ensures that relevant stakeholders are kept informed of ongoing discussions and developments.

Watchers receive email notifications for the following types of new activity on a thread:

- Creation of a new thread with comments.
- Replies on a thread, facilitating ongoing conversation.
- Deletion of a thread.
- Changes in status of resolution.

Users will also receive notifications for new comments and mentions on threads they are watching, directly on their dashboard in the [Notification center](/dam/notification-center). 

Notifications are only sent to users with at least "Can view" permission on the file. A user won't receive notifications for their actions.

## Access control and permissions

Read about the permission levels required for [Media Library Restricted Access users](/user-management#user-roles) for different comment operations [here](/dam/sharing-and-collaboration#file-and-folder-permission-levels).


---

# Source: /dam/embed-video

---
title: Embed video
description: Learn how to embed videos stored in the ImageKit DAM on your website or application.
---

Embedding a video from ImageKit DAM allows you to add the video directly to a web page or a blog without integrating your own video player. 

Embedded videos are ready for playback without any other effort, show a preview thumbnail before playing, and provide a great streaming experience, quick start, and consistent playback. 

You can also configure [Adaptive Bitrate Streaming ABS](/adaptive-bitrate-streaming) for embedded videos supporting HLS and MPEG-DASH, and use video transformations compatible with ABS. This will create an experience similar to YouTube, where the video stream adjusts according to the user's network speed and other factors. 

ImageKit automatically generates the necessary encoded streaming representations and the required files.

Typically, the code to embed a video appears as follows:

```html
<iframe width="560" height="315" 
    src="https://imagekit.io/player/embed/demo/sample-video.mp4?thumbnail=https%3A%2F%2Fik.imagekit.io%2Fdemo%2Fsample-video.mp4%2Fik-thumbnail.jpg" 
    title="ImageKit video player" 
    frameBorder="0" 
    allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share; fullscreen">
</iframe>
```

## Get embed code

You can only embed [published] video files. To get the embed code, right-click on the video file and select "Embed" from the dropdown menu. You can access the same option from the file detail page by clicking on the "Embed" button at the top.

![Embed option](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/Screenshot-2023-10-09-at-3.16.21-PM.png?tr=w-1600>)

Upon selecting "Embed", a modal will appear with various configuration options and the embed iframe code.

![Embed video modal](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/Screenshot-2023-10-09-at-3.16.41-PM.png?tr=w-1600>)

The following embed options are available:

* [Expiration time](#expiration-time)
* [Adaptive Bitrate Streaming (ABS)](#adaptive-bitrate-streaming-abs)

## Expiration time

{% callout style="info" %}
The expiration time option is only available for private video files.
{% /callout %}

By default, embedded video does not expire. To specify an expiration date and time, deselect the "Never expire" checkbox.

![Expiration time](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/Screenshot-2023-10-09-at-3.17.07-PM.png?tr=w-1600>)

## Adaptive Bitrate Streaming (ABS)

You can enable Adaptive Bitrate Streaming(ABS) and embed the videos using either HTTP Live Streaming (HLS) or Dynamic Adaptive Streaming over HTTP (MPEG-DASH) protocols. To do so, select the "Enable ABS" option and choose your preferred protocol and resolution options from the dropdown menu.

![ABS embed options](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/Screenshot-2023-10-11-at-1.19.11-PM.png?tr=w-1600>)

An option to enter custom ABS transformation strings is also available. This can be used to add other [supported video transformation parameters](/video-transformation) compatible with [Adaptive Bitrate Streaming-enabled](/adaptive-bitrate-streaming) video.

{% callout style="info" %}
The transformation string must contain `sr-<representations>` transformation for ABS.
{% /callout %}

Additionally, [named transformation](/transformations#named-transformations) can be incorporated as part of a custom transformation string by specifying `tr:n-<named_transform>`.


---

# Source: /dam/notification-center

---
title: Notification center
description: Get updates on activities in the ImageKit DAM.
---

In the ImageKit DAM, you receive notifications for new comments and mentions in threads you are watching and when files, folders, or media collections are shared with you.

{% callout style="info" %}
Notifications are automatically removed from the list after 30 days. Older notifications can still be found in your email.
{% /callout %}

## View notifications

To view your notifications, click on the notification icon in the DAM, as shown below. The number of new notifications is displayed at the top of the icon.

![Notification icon in ImageKit DAM](<https://ik.imagekit.io/ikmedia/docs_images/notification/bell-icon-notification.png?tr=w-1600>)

There are two tabs in the notification center.
- "All" shows all the notifications received.
- "Only Mentions" shows the notifications directly mentioning you.

![Notification view](<https://ik.imagekit.io/ikmedia/docs_images/notification/notification-view.png?tr=w-1600>)


## Manage and filter notifications

You can mark notifications as "read" or "unread". To do so, hover over the avatar located on the left-hand side of the notification. A selectable will appear; click it to change the notification status.

{% video src="https://ik.imagekit.io/ikmedia/docs_images/notification/notification-set-read-unread-status.mov?tr=w-1600" alt="Set read status of notification" /%}

Additionally, you can mark all notifications as read using the "Mark all as read" button provided.

You can use the "Only show unread" filter to view only unread notifications.

![Only show unread notifications](<https://ik.imagekit.io/ikmedia/docs_images/notification/only-show-unread-notification.png?tr=w-1600>)

## Which notifications are included?

Notifications are added to the notifications center when another user with [access](/dam/sharing-and-collaboration#understanding-permissions-on-assets-and-media-collections) does one of the following:
- Shares any file, folder or media collection with you. Learn more about access control and sharing [here](/dam/sharing-and-collaboration#how-to-share-assets-and-media-collections).
- Adds a new comment on threads you are watching or mentions you on threads of files you have access to. Learn more about it [here](/dam/comments-on-assets#watchers-and-notifications).

In addition to being displayed in the Notification Center, you will also receive an email notification.


---

# Source: /dam/embeddable-media-library-widget

---
title: Embeddable Media Library widget
description: Embed ImageKit's Digital Asset Management platform directly into your existing web application or CMS with a ready-to-use widget.
---

The [Media Library widget](https://github.com/imagekit-developer/embeddable-media-library) provides an easy way to integrate ImageKit DAM into your CMS or any web application. Access all assets stored in your Media Library and Collections directly from your existing CMS or application.

Integration is straightforward, as you'll discover in this guide.

## Live demo

You can also see the live hosted demo on [codesandbox.io](https://codesandbox.io/p/sandbox/media-library-widget-mp484k). Tweak the parameters to understand the different options.

{%iframe src="https://codesandbox.io/embed/mp484k?view=editor+%2B+preview&module=%2Findex.html" %}
{% /iframe %}

## Media Library widget features

This JavaScript-based plugin enables seamless access to your ImageKit Media Library and Collections within your CMS or web application. Search and manage assets stored in the Media Library directly from your application.

Key features include:

* Access ImageKit Media Library within your CMS using ImageKit credentials
* Search and insert images directly from your Media Library into your CMS
* Configure UI view options: inline or modal-based Media Library panel
* Apply custom container classes to match your application's theme
* Open the Media Library in specific states (folders, assets, collections)
* Control asset selection: single/multiple assets with configurable limits

![](https://ik.imagekit.io/ikmedia/docs_images/media-library/mlw/15-mlw-home.png?tr=w-1600)

## Integration Overview

{% callout style="info" %}
For quick and easy access to the DAM, use the [ImageKit desktop app](/dam/app) on Windows and macOS instead of building custom integrations. This app handles simple tasks such as uploading, browsing, searching files, and drag-and-drop into your application, streamlining your workflow efficiently.
{% /callout %}

Integrating the ImageKit Media Library plugin into your web application or CMS is straightforward. Follow these steps:

1. [Include the plugin script and create a container element](#include-the-plugin-script-and-create-a-container-element) - Add the plugin script to your web page and create a container element for the widget
2. [Initialize the Media Library widget](#initialize-the-media-library-widget) - Configure the widget with options including the mandatory container and optional settings
3. [Instantiate the Media Library widget and open it](#run-the-application) - Create the widget instance using the `IKMediaLibraryWidget` constructor
4. [Insert assets from the Media Library](#insert-assets-from-the-media-library) - Select and insert images and other files into your CMS or application

### Include the plugin script and create a container element

You can include the ImageKit Media Library Widget in your project using either the CDN or NPM installation method.

#### CDN Installation

Insert the following script on the web page where you want to embed the Media Library:

```html
<script src="https://unpkg.com/imagekit-media-library-widget/dist/imagekit-media-library-widget.min.js"></script>
```

#### NPM Installation

Install the `imagekit-media-library-widget` package:

```bash
# Using npm
npm install --save imagekit-media-library-widget

# Using yarn
yarn add imagekit-media-library-widget
```

Then include it in your JavaScript code:

```javascript
// ES6 module
import IKMediaLibraryWidget from 'imagekit-media-library-widget';

// CommonJS syntax
const IKMediaLibraryWidget = require("imagekit-media-library-widget");
```

{% callout style="info" %}
Internet Explorer does not natively support all Media Library Widget features. We recommend using a modern browser like Google Chrome, Mozilla Firefox, or Safari.
{% /callout %}

#### Create a container element

Create an HTML container element where the widget will be rendered:

```html
<div id="container"></div>
```

### Initialize the Media Library widget

Using the configuration options and callback function, let’s instantiate the plugin:

```javascript
const mediaLibraryWidget = new IKMediaLibraryWidget(config, callback);
```

#### Constructor parameters

The `IKMediaLibraryWidget` constructor accepts two parameters:

{% table %}
- **Parameter** {% width="20%" %}
- **Type** {% width="15%" %}
- **Description** {% width="65%" %}
---
- **config**
- `object`
- Configuration options for the Media Library widget instance. See [plugin options](#plugin-options) for detailed configuration.
---
- **callback**
- `function`
- Function called when users click "Insert" in the Media Library. Receives a JSON payload containing the selected assets.
{% /table %}

#### Callback function signature

```javascript
function callback(payload) {
  // Handle the selected assets
  console.log('Selected assets:', payload.data);
}
```

#### Callback payload schema

The callback receives a JSON object with the following structure:

```javascript
{
  eventType: 'INSERT',
  data: [
    // Array of selected file/folder objects
    // Each object matches the schema from the 
    // List and Search Assets API response
  ]
}
```

{% table %}
- **Property** {% width="20%" %}
- **Type** {% width="15%" %}
- **Description** {% width="65%" %}
---
- **eventType**
- `'INSERT'`
- Always set to `'INSERT'` when assets are selected and inserted.
---
- **data**
- `object[]`
- Array of selected file objects. Each object follows the same schema as items returned by the [List and Search Assets API](/api-reference/digital-asset-management-dam/list-and-search-assets#responses). Contains properties like `fileId`, `name`, `filePath`, `url`, `fileType`, `tags`, etc.
{% /table %}

{% callout style="info" %}
**Note:** The default "Open Media Library" button is only displayed when `renderOpenButton` is set to `true` (default behavior).
{% /callout %}

#### Plugin options

The plugin accepts the following configuration options, including the mandatory `container`. It also accepts some optional settings that control the plugin's behavior and styling.

{% table %}
- **Option** {% width="25%" %}
- **Type** {% width="15%" %}
- **Description** {% width="60%" %}
---
- **container** **(required)**
- `string` \| [`HTMLElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement)
- The container element where the Media Library will be rendered. Accepts CSS selectors (e.g., `#container`) or DOM element references.
---
- **className**
- `string`
- Optional CSS class to apply to the container element for custom styling.
---
- **dimensions**
- `object`
- Dimensions of the Media Library container element.

  ```javascript
  {
    height: '100%',
    width: '100%'
  }
  ```
---
- **view**
- `'modal'` \| `'inline'`
- Display mode for the Media Library interface. Use `modal` for overlay display or `inline` for embedded display. Default: `'modal'`
---
- **renderOpenButton**
- `boolean`
- Whether to display the default "Open Media Library" button. Set to `false` when using custom triggers or editor plugins. Default: `true`
---
- **mlSettings**
- `object`
- Advanced configuration options for Media Library behavior. See [mlSettings options](#mlsettings-options) below.
{% /table %}

#### mlSettings options

The `mlSettings` object provides fine-grained control over Media Library behavior:

{% table %}
- **Option** {% width="25%" %}
- **Type** {% width="15%" %}
- **Description** {% width="60%" %}
---
- **initialView**
- `object`
- Configures the initial state when the Media Library opens. See [initialView options](#initialview-options) below.
---
- **multiple**
- `boolean`
- Whether users can select multiple assets during insertion. When `false`, only single asset selection is allowed. Default: `true`
---
- **maxFiles**
- `number`
- Maximum number of assets that can be selected in a single operation. Only applies when `multiple: true`.
---
- **toolbar**
- `object`
- Controls the visibility of toolbar buttons in the Media Library interface.

  ```javascript
  toolbar: {
    showCloseButton: false,   // Default: true
    showInsertButton: false   // Default: true
  }
  ```
---
- **queryParams**
- `object`
- Custom query parameters to append to the Media Library widget URL. Useful for passing additional context or tracking parameters.

  ```javascript
  queryParams: {
    customParam1: "value1",
    customParam2: 123,
    customParam3: true
  }
  ```
---
- **widgetImagekitId**
- `string`
- Specifies the ImageKit ID used to authenticate and open the Media Library.
---
- **loginViaSSO**
- `boolean` 
- Determines whether to automatically initiate Single Sign-On (SSO) login by default.	
{% /table %}

#### initialView options

The `initialView` object determines the initial state when the Media Library opens. You can specify **only one** of the following options:

{% callout style="info" %}
**Important:** You cannot pass more than one property in `initialView`. For complex filtering, use the `searchQuery` option.
{% /callout %}

{% table %}
- **Option** {% width="25%" %}
- **Type** {% width="15%" %}
- **Description** {% width="60%" %}
---
- **searchQuery**
- `string`
- Lucene-like query string to filter assets, same as the `searchQuery` parameter in the [list and search assets API](/api-reference/digital-asset-management-dam/list-and-search-assets). Opens the widget in search view with filtered results.

  ```javascript
  searchQuery: 'name: "pexel"'
  ```
---
- **folderPath**
- `string`
- Path to the folder that should be opened initially. Must start with `/`.

  ```javascript
  folderPath: '/marketing/banners'
  ```
---
- **fileId**
- `string`
- File ID to open in detail view initially. Opens the file detail page for the specified asset.

  ```javascript
  fileId: '5fd874c040308546019f0500'
  ```
---
- **collection**
- `object`
- Collection configuration. Pass an empty object `{}` to show all collections, or specify an ID to open a specific collection.  

  Example:

  ```javascript
  // All collections
  collection: {}
  
  // Specific collection
  collection: { 
    id: '5fd874c040308546019f0500' 
  }
  ```
---
- **fileType**
- `'images'` \| `'videos'` \| `'cssJs'` \| `'others'`
- Filter assets by type. Opens search view with results filtered to the specified asset type:
  - `'images'`: only image files
  - `'videos'`: only video files  
  - `'cssJs'`: only CSS, JS, or TS files
  - `'others'`: files other than images or videos

  ```javascript
  fileType: 'videos'
  ```
{% /table %}


Refer to the configuration examples below to learn how to use these options:

* [Open Media Library home](#open-media-library-home)
* [Open at a specific folder path](#open-at-a-specific-folder-path)
* [Open specific file detail view](#open-specific-file-detail-view)
* [Filter by file type](#filter-by-file-type)
* [Search with custom query](#search-with-custom-query)
* [View all collections](#view-all-collections)
* [Open specific collection](#open-specific-collection)
* [Single file selection](#single-file-selection)
* [Limit maximum file selection](#limit-maximum-file-selection)


#### Callback function and payload

This callback function is called after the user clicks the "Insert" button in the Media Library. The callback receives a JSON payload of the selected images. You can consume this data in your application in any way you choose.

```javascript
function callback(payload) {
  // Handle the selected assets
  console.log('Selected assets:', payload.data);
  
  // Example: Insert image URLs into a form
  payload.data.forEach(asset => {
    console.log(`Asset URL: ${asset.url}`);
    console.log(`Asset name: ${asset.name}`);
  });
}
```

#### Sample payload

The following shows an example of the JSON payload returned after selecting and inserting an image from the Media Library Widget UI:

```javascript
{
  eventType: 'INSERT',
  data: [{
    createdAt: "2020-12-15T08:33:04.570Z",
    customCoordinates: null,
    fileId: "5fd874c040308546019f0500",
    filePath: "/rally_s_tK613HYyf.jpg",
    fileType: "image",
    isPrivateFile: false,
    name: "rally_s_tK613HYyf.jpg",
    tags: null,
    thumbnail: "https://ik.imagekit.io/o00s3beva/rally_s_tK613HYyf.jpg?updatedAt=1608029584570&tr=n-media_library_thumbnail",
    type: "file",
    url: "https://ik.imagekit.io/o00s3beva/rally_s_tK613HYyf.jpg?updatedAt=1608029584570"
  }]
}
```

#### Open method

The `open()` method opens the widget programmatically, allowing you to override `mlSettings` and the callback function.

**Method signature:**
```javascript
mediaLibraryWidget.open(settings?, callback?)
```

**Parameters:**

{% table %}
- **Parameter** {% width="20%" %}
- **Type** {% width="15%" %}
- **Description** {% width="65%" %}
---
- **settings** (optional)
- `object`
- Object containing only `mlSettings` property. See [mlSettings options](#mlsettings-options) for available configuration. The `mlSettings` object completely replaces the existing `mlSettings` from the constructor (does not merge).
---
- **callback** (optional)
- `function`
- Callback function that overrides the constructor callback. Receives the same payload structure as the constructor callback.
{% /table %}

**Example usage:**

```javascript
// Open widget
mediaLibraryWidget.open();

// Open with updated configuration and custom callback
mediaLibraryWidget.open({
  mlSettings: {
    initialView: {
      fileType: 'images'
    },
    multiple: false
  }
}, (payload) => {
  console.log('Custom callback:', payload.data);
});

// Open with default settings
mediaLibraryWidget.open({});
```
{% callout style="info" %}
**Note:** When you provide `mlSettings` to the `open()` method, it completely replaces the existing `mlSettings` from the constructor. It does not merge with existing settings. If you want to preserve some settings while updating others, you must include all desired settings in the `mlSettings` object will calling `open()`.
{% /callout %}

### Run the application

Navigate to your application webpage in the browser. You should see the "Open Media Library" button:

![Open Media Library button](https://ik.imagekit.io/ikmedia/docs_images/media-library/mlw/02-mlw-button.png?tr=w-1600)

Click the button to open the Media Library. If you're already logged in to ImageKit in this browser, the Media Library will open directly. Otherwise, you'll see the login screen.

![ImageKit login screen in modal popup](https://ik.imagekit.io/ikmedia/docs_images/media-library/mlw/03-mlw-login.png?tr=w-1600)

Enter your ImageKit email and password to log in.

After successful login, you'll be automatically directed to the Media Library view.

![Media Library Widget panel in modal popup](https://ik.imagekit.io/ikmedia/docs_images/media-library/mlw/15-mlw-home.png?tr=w-1600)

### Opening programmatically

When `renderOpenButton` is set to `false`, you can control the widget programmatically using the `open()` method. This is useful when you want to:

- Use custom buttons or triggers in your application
- Open the widget with different configurations based on context
- Integrate with editor plugins or CMS interfaces

**Example:**

```javascript
// Initialize widget without default button
const mediaLibraryWidget = new IKMediaLibraryWidget({
  container: '#container',
  view: 'modal',
  renderOpenButton: false  // Hide default button
}, (payload) => {
  console.log('Selected assets:', payload.data);
});

// Open with custom button
document.getElementById('myCustomButton').addEventListener('click', () => {
  mediaLibraryWidget.open({
    mlSettings: {
      initialView: {
        fileType: 'images'
      }
    }
  });
});
```

### Insert assets from the Media Library

The Media Library Widget interface is similar to the ImageKit dashboard, providing a familiar experience.

Look for the "Insert" button in the upper right area of the screen. Click this button to trigger your callback function with the selected assets.

![Insert images](https://ik.imagekit.io/ikmedia/docs_images/media-library/mlw/05-mlw-insert-image.png?tr=w-1600)

The modal view should close automatically. Open the browser console and verify that the image payload data has been logged successfully:

![Data payload received successfully](https://ik.imagekit.io/ikmedia/docs_images/media-library/mlw/06-mlw-response.png?tr=w-1600)

## Sample application

{% linetabs %}
{% linetab title="HTML" %}
```html
<!DOCTYPE html>
<html>

<head>
  <title>ImageKit Media Library Widget</title>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="stylesheet" href="styles.css">
</head>

<body>
  <!-- Media Library -->
  <div class="wrapper">
    <div id="container"></div>
  </div>
</body>

<script src="https://unpkg.com/imagekit-media-library-widget/dist/imagekit-media-library-widget.min.js"></script>

<script>
// configuration options
const config = {
  container: '#container',   // the element in which the widget will be rendered
  className: 'media-library-widget',
  dimensions: {
    height: '100%',
    width: '100%',
 },
  view: 'modal',  // modal | inline
  renderOpenButton: true  // false | true (default)
};

// define callback handler  
function callback (payload) {
  // this is the callback handler
  // … consume json payload …
  console.log('Image data:', payload.data);
}

// instantiate the plugin
const mediaLibraryWidget = new IKMediaLibraryWidget(config, callback);
</script>

</html>
```
{% /linetab %}

{% linetab title="Styles" %}
```css
html {
  width: 100%;
  height: 100%;
  margin: 0;
  padding: 0;
}

body {
  margin: 0;
  font-family: Arial, Helvetica, sans-serif;
}

#container {
  position: relative;
  height: 100%;
  width: 100%;
}

.wrapper {
  width: 100%;
  height: 100%;
}
```
{% /linetab %}
{% /linetabs %}

## SSO Login
If your CMS or web application users already authenticate via Single Sign-On (SSO), you can [configure](/docs/single-sign-on/overview#how-to-set-up-sso) SSO login for ImageKit to create a seamless experience.

{% callout style="info" %}
Without SSO configured, your users will need to log in to ImageKit separately when the widget opens.
{% /callout %}

To enable automatic login using an existing SSO session, configure `mlSettings` as follows:
- `widgetImagekitId`: ID of the ImageKit account to open.
- `loginViaSSO`: true

With this setup, the Media Library widget will open without prompting for separate ImageKit credentials.

## Signature-based Login
For enterprise users, there is an option to log in users using their email addresses, without them having to enter their email addresses or passwords each time. This method instead relies on creating a valid signature using your account’s private key and the user’s email to initiate the login attempt. If the signature is valid, the user is logged in. 

This results in a more seamless experience when accessing the ImageKit Media Library, without each user having to log in. For more details on this login method, please contact your ImageKit Customer Success Manager.

## Configuration examples

## Open Media Library home

Basic configuration that opens the Media Library in the default home view:

```javascript
const config = {
  container: '#container',   // the element in which the widget will be rendered
  className: 'media-library-widget',
  dimensions: {
    height: '100%',
    width: '100%',
  },
  view: 'modal',  // modal (default) | inline
  renderOpenButton: true  // false | true (default)
};
```

![](https://ik.imagekit.io/ikmedia/docs_images/media-library/mlw/15-mlw-home.png?tr=w-1600)

## Open at a specific folder path

Opens the Media Library widget directly in the specified folder:

```javascript
const config = {
  container: '#container',   // the element in which the widget will be rendered
  className: 'media-library-widget',
  dimensions: {
    height: '100%',
    width: '100%',
  },
  view: 'modal',  // modal (default) | inline
  renderOpenButton: true,  // false | true (default)
  mlSettings: {
    initialView: {
      folderPath: '/marketing/banner'
    },
  }
};
```

![](https://ik.imagekit.io/ikmedia/docs_images/media-library/mlw/16-mlw-specific-folder.png?tr=w-1600)

## Open specific file detail view

Opens the Media Library widget directly in the file detail view for a specific asset:

```javascript
const config = {
  container: '#container',   // the element in which the widget will be rendered
  className: 'media-library-widget',
  dimensions: {
    height: '100%',
    width: '100%',
  },
  view: 'modal',  // modal (default) | inline
  renderOpenButton: true,  // false | true (default)
  mlSettings: {
    initialView: {
      fileId: "5fd874c040308546019f0500"
    },
  }
};
```

![](https://ik.imagekit.io/ikmedia/docs_images/media-library/mlw/14-mlw-file-detail.png?tr=w-1600)

## Filter by file type

Opens the Media Library widget with results filtered to show only specific file types:

```javascript
const config = {
  container: '#container',   // the element in which the widget will be rendered
  className: 'media-library-widget',
  dimensions: {
    height: '100%',
    width: '100%',
  },
  view: 'modal',  // modal (default) | inline
  renderOpenButton: true,  // false | true (default)
  mlSettings: {
    initialView: {
      fileType: 'videos'
    },
  }
};
```

![](https://ik.imagekit.io/ikmedia/docs_images/media-library/mlw/09-mlw-file-type.png?tr=w-1600)

## Search with custom query

Opens the Media Library widget in search view with a predefined query filter:

```javascript
const config = {
  container: '#container',   // the element in which the widget will be rendered
  className: 'media-library-widget',
  dimensions: {
    height: '100%',
    width: '100%',
  },
  view: 'modal',  // modal (default) | inline
  renderOpenButton: true,  // false | true (default)
  mlSettings: {
    initialView: {
      searchQuery: 'name: "pexel"'
    },
  }
};
```

![](https://ik.imagekit.io/ikmedia/docs_images/media-library/mlw/10-mlw-custom-search.png?tr=w-1600)

## View all collections

Opens the Media Library widget showing all available collections:

```javascript
const config = {
  container: '#container',   // the element in which the widget will be rendered
  className: 'media-library-widget',
  dimensions: {
    height: '100%',
    width: '100%',
  },
  view: 'modal',  // modal (default) | inline
  renderOpenButton: true,  // false | true (default)
  mlSettings: {
    initialView: {
      collection: {}
    }
  }
};
```

![](https://ik.imagekit.io/ikmedia/docs_images/media-library/mlw/13-mlw-all-collections.png?tr=w-1600)

## Open specific collection

Opens the Media Library widget directly in a specific collection:

```javascript
const config = {
  container: '#container',   // the element in which the widget will be rendered
  className: 'media-library-widget',
  dimensions: {
    height: '100%',
    width: '100%',
  },
  view: 'modal',  // modal (default) | inline
  renderOpenButton: true,  // false | true (default)
  mlSettings: {
    initialView: {
      collection: {
        id: "5fd874c040308546019f0500"
      }
    }
  }
};
```

![](https://ik.imagekit.io/ikmedia/docs_images/media-library/mlw/12-mlw-collection.png?tr=w-1600)

## Single file selection

Configures the Media Library widget to allow selection of only one asset at a time:

```javascript
const config = {
  container: '#container',   // the element in which the widget will be rendered
  className: 'media-library-widget',
  dimensions: {
    height: '100%',
    width: '100%',
  },
  view: 'modal',  // modal (default) | inline
  renderOpenButton: true,  // false | true (default)
  mlSettings: {
    multiple: false
  }
};
```

![](https://ik.imagekit.io/ikmedia/docs_images/media-library/mlw/11-mlw-single-selection.png?tr=w-1600)

## Limit maximum file selection

Sets a maximum limit on the number of assets that can be selected:

```javascript
const config = {
  container: '#container',   // the element in which the widget will be rendered
  className: 'media-library-widget',
  dimensions: {
    height: '100%',
    width: '100%',
  },
  view: 'modal',  // modal (default) | inline
  renderOpenButton: true,  // false | true (default)
  mlSettings: {
    multiple: true,
    maxFiles: 3
  }
};
```

![](https://ik.imagekit.io/ikmedia/docs_images/media-library/mlw/08-mlw-max-selection.png?tr=w-1600)

## Google Chrome Incognito mode

When using this plugin in Google Chrome's Incognito mode, you need to enable third-party cookies:

![](https://ik.imagekit.io/ikmedia/docs_images/media-library/mlw/07-mlw-incognito-sm.png?tr=w-1600)


---

# Source: /dam/app

---
title: Desktop app for DAM
description: ImageKit's desktop application for quick access to Digital Asset Management on Windows and macOS.
---

ImageKit offers a native app that allows users to quickly access its Digital Asset Management (DAM) platform on Windows and MacOS. With this app, you can browse and search your assets, create new folders, upload files and folders, and perform operations such as copying file URLs and downloading files.

Additionally, you can click to open assets directly on the web platform to utilize all available features. The app also supports drag-and-drop functionality, making it easy to move files between it and other applications.

{% video loop=true controls=false autoplay=true playsinline=true muted=true src="https://ik.imagekit.io/ikmedia/docs_images/media-library/dam-app-preview.mp4?tr=ac-none,so-2" alt="Desktop DAM app for Mac and Windows" /%}

## Installation

To start using the ImageKit DAM App, download it from the ImageKit website. After installation, open the app and log in with your ImageKit account credentials.

### Platform availability

The ImageKit DAM App is available for Windows and macOS. Download the appropriate version for your operating system from the ImageKit website.

{% quickstartLinksGrid %}

{% griditem %}
{% linkButton href="https://github.com/imagekit-developer/imagekit-desktop/releases/latest/download/ImageKit-DAM-1.1.2-arm64.dmg"  text="Download for Mac (Apple Silicon)" /%}
{% /griditem %}

{% griditem %}
{% linkButton href="https://github.com/imagekit-developer/imagekit-desktop/releases/latest/download/ImageKit-DAM-1.1.2.dmg"  text="Download for Mac (Intel Chip)" /%}
{% /griditem %}

{% griditem %}
{% linkButton href="https://github.com/imagekit-developer/imagekit-desktop/releases/latest/download/ImageKit-DAM-Setup-1.1.2.exe"  text="Download for Windows" /%}
{% /griditem %}

{% /quickstartLinksGrid %}

### How to update the app?

The app ensures you always have the latest features and improvements with automatic updates. When a new version is available, it is downloaded in the background, and the update is applied automatically the next time you open the app. 

If you prefer to apply the latest update immediately, you can select the "Relaunch to update app" option in the profile dropdown menu whenever an update is available.

## Browse assets

The app offers an intuitive interface similar to the web platform, allowing you to navigate your assets easily. You can view your files, folders, and media collections with sorting options. Additionally, you can switch between grid and list views for convenient browsing.

## Search assets

The search bar at the top of the app allows you to search for files, folders, tags, and media collections. The autocomplete search feature suggests possible matches as you type, helping you quickly locate the assets you need.

This feature is the same as the search functionality available on the ImageKit web platform. Read more about it [here](/dam/search#search-autocomplete).

## Create folder

To create a new folder at the current path, click the "New" button in the app and select "Create folder" from the menu.

## Upload files and folders

Click on the "New" button in the app and select "Upload files" or "Upload folder" to upload files or folders to your ImageKit account at the correct path.

You can also drag and drop files directly into the app to initiate upload.

## Open assets in the browser

The app allows you to open files, folders, and media collections in your browser. Hover over an asset and click the "Open in browser" icon to access it on the ImageKit web platform. This feature is useful when you need to perform advanced operations on assets that are not available in the app.

## Copy file URLs

To copy a file's URL, hover over it and click on the "Copy URL" icon. This feature is helpful for quickly sharing links to specific files.

## Download files

To download a file, hover over it and click on the "Download" icon. The file will be downloaded to your system.

## Drag and drop functionality

One useful feature of the ImageKit DAM App is its drag-and-drop functionality. You can click and hold on a file within the app and drag it to your desired location in your operating system or into another running application, such as Photoshop. This seamless operation allows you to work efficiently without switching between applications.

## Permissions

The DAM app natively supports capturing images or videos from your system's camera and microphone and uploading them to your ImageKit media library. To enable this feature, you need to grant necessary permissions to the app.

- [Permissions in MacOS](#permissions-in-macos)
- [Permissions in Windows](#permissions-in-windows)

#### Permissions in MacOS

The app requests for camera and microphone permissions to capture images or videos from your system's camera and microphone. When you open the app for the first time and click on the _"New"_ button > _"File Upload"_ section, you will see a notification asking for camera permission like the one shown below.

![](https://ik.imagekit.io/ikmedia/docs_images/media-library/permissions-docs-assets/permission-callout.png?tr=q-100,w-400)

On clicking the _"Grant"_ button, the app will request for camera and microphone permissions. They should look like the ones shown below.

![Microphone permission in MacOS](https://ik.imagekit.io/ikmedia/docs_images/media-library/permissions-docs-assets/dam-app-permission-microphone-macos.png?tr=q-100,w-400)

![Camera permission in MacOS](https://ik.imagekit.io/ikmedia/docs_images/media-library/permissions-docs-assets/dam-app-permission-camera-macos.png?tr=q-100,w-400)

Once you grant the permissions, you should be able to see the camera and microphone options in the _"New"_ button > _"File Upload"_ section like shown below.

![](https://ik.imagekit.io/ikmedia/docs_images/media-library/permissions-docs-assets/updated-upload-screen.png?tr=q-100,w-400)

**Note**: In certain cases, you might not see the "Grant" button. This is because the app has been denied these permissions by the system. You can grant these permissions manually by going to the _"System Preferences"_ > _"Security & Privacy"_ > _"Camera"_ and _"Microphone"_ and grant the permissions from there.

![](https://ik.imagekit.io/ikmedia/docs_images/media-library/permissions-docs-assets/permission-callout-open-settings.png?tr=q-100,w-400)

![](https://ik.imagekit.io/ikmedia/docs_images/media-library/permissions-docs-assets/mac-privacy-security.png?tr=q-100,w-400)

{% callout style="warning" %}
Once you grant the permissions, do not forget to quit and reopen the app to apply the changes. Unless you do this, the app will not recognize the new permissions.
{% /callout %}

#### Permissions in Windows

For Windows, the app should automatically have permissions to access the camera and microphone and you should be able to see the options in the _"New"_ button > _"File Upload"_ section like shown below.

![](https://ik.imagekit.io/ikmedia/docs_images/media-library/permissions-docs-assets/updated-upload-screen.png?tr=q-100,w-400)

**Note**: If you don't see the camera and microphone options, it is probably because you have overridden the default camera and microphone permission settings in Windows. You can grant these permissions manually by going to the _"Camera"_ and _"Microphone"_ options in Windows Settings. The below image shows how you can grant permissions for microphone.

![Granting microphone permissions in Windows](https://ik.imagekit.io/ikmedia/docs_images/media-library/permissions-docs-assets/windows-microphone-permissions.png?tr=q-100,w-1400&v=1)

Similarly, to grant permissions for camera, select the "Camera" option from the sidebar.

{% callout style="warning" %}
Once you grant the permissions, do not forget to quit and reopen the app to apply the changes. Unless you do this, the app will not recognize the new permissions.
{% /callout %}


---

# Source: /api-overview

---
title: ImageKit API Overview
description: Learn about ImageKit's APIs, authentication, rate limits, error codes, and more.
---

ImageKit.io offers REST APIs to programmatically integrate ImageKit.io into your application, especially the integrated Digital Asset Management or the media storage called the Media Library. Currently, APIs are available for the following operations.

* [File Upload APIs](/api-reference/upload-file/upload-file) - Upload files to the ImageKit Media Library from the server or client side.
* [Digital Asset Management APIs](/api-reference/digital-asset-management-dam/managing-assets/get-file-details) - Build a Headless DAM solution by natively integrating the ImageKit Media Library with search, list, copy, move, and other operations exposed via APIs.
* [File Metadata APIs](/api-reference/file-metadata/get-uploaded-file-metadata) - Get a file's metadata by its file ID or URL.
* [Custom Metadata Fields APIs](/api-reference/digital-asset-management-dam/custom-metadata-fields/create-new-field) - Create, read, and update custom metadata fields in your ImageKit Media Library via APIs. These fields can then be updated for your files via the [Update File](/api-reference/digital-asset-management-dam/managing-assets/update-file-details) or [Upload File API](/api-reference/upload-file/upload-file).
* [Cache Management APIs](/api-reference/caching/purge-cache) - Initiate cache purge requests and check their status via APIs.
* [Account Management APIs](/api-reference/account-management-api/get-usage) - Get the usage for your account between two dates.

All these methods are available in our [backend SDKs](/quick-start-guides#back-end). We recommend using the SDKs for a more straightforward integration with your code. Upload APIs can also be used from the [client side](/quick-start-guides#front-end).

For AI-powered workflows, see [Build with AI](/build-with-ai) to connect ImageKit's MCP servers and agent skills so assistants like Claude, Cursor, and VS Code Copilot can interact with ImageKit APIs using natural language. 

## Request and response structure

Except for [upload API](/api-reference/upload-file/upload-file), all our APIs accept JSON-encoded request bodies and return JSON-encoded responses.

## Run in Postman

We’ve created a Postman collection to simplify testing and working with our API.

[![;nozoom;noborder](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/38885799-5dfabefd-8c5f-4353-9df8-28fee835b3a9?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D38885799-5dfabefd-8c5f-4353-9df8-28fee835b3a9%26entityType%3Dcollection%26workspaceId%3D19950c59-789a-4b3d-a059-a2dc0596ec7c)

## OpenAPI specification
Here is the OpenAPI specification for [v1 version](https://raw.githubusercontent.com/imagekit-developer/sdk-generation/refs/heads/main/openapi/v1.0.0.yaml) of ImageKit's API.

## Error codes
    
ImageKit.io API uses standard HTTP error codes.

{% table %}
* **Error code** {% width="50%" %}
* **Description** {% width="50%" %}
---
* **2xx** \
 OK
* Everything worked as expected.
---
* **400** \
 Bad request
* The request was unacceptable, often due to missing or invalid parameter(s). In this case, a JSON-encoded error response is returned with the `message` property. `message` contains the details about the error and possible solution.
---
* **401** \
 Unauthorized
* No valid API key was provided.
---
* **403** \
 Forbidden
* Can be for the following reasons, which will be indicated in the `message` field in the response:
  - ImageKit could not authenticate your account with the keys provided.
  - An expired key (public or private) was used with the request.
  - The account is disabled.
  - If you are using the upload API, the total storage limit (or upload limit) is exceeded.
---
* **429** \
 Too Many Requests
* Too many requests hit the API too quickly. We recommend you throttle the request rate as per the value of `X-RateLimit-Limit` and `X-RateLimit-Reset` response headers and stay within [rate limits](#rate-limits).
---
* **500, 502, 503, 504** \
 Server error
* Something went wrong with ImageKit.io API. Please create a support ticket by emailing us at [support@imagekit.io](mailto:support@imagekit.io).
{% /table %}

## Request ID (x-ik-requestId)

All API responses contain a `x-ik-requestId` header. This header's value is a unique identifier associated with the API request. If you encounter any issues with any API, provide this header value in your support ticket to help us troubleshoot the issue quickly. This is also exposed in all SDKs as part of the response object. Please refer to the respective SDK documentation for more details.

## Authentication

Your API requests are authenticated using the account's [private API key](./api-keys). If you do not include your key when making an API request or use an incorrect one, we return an error. You can view your API keys in the ImageKit.io dashboard under the [developer's tab](https://imagekit.io/dashboard/developer/api-keys).

Authentication to the API is performed via [HTTP Basic Auth](http://en.wikipedia.org/wiki/Basic_access_authentication). Provide your [private API key](./api-keys) as the basic auth username value. You do not need to provide a password.

{% callout style="warning" %}
**Only HTTPS supported** \
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
{% /callout %}

### Example

You can provide the private API key in a curl request as:

```bash
curl https://api.imagekit.io/v1/files \ 
-u your_private_api_key:
# The colon prevents curl from asking for a password.
```

You can also use the "Authorization" header and provide base64 encoded value of the string \
`your_private_api_key:`

{% callout style="info" %}
Notice the colon (:) after the private key. It is required. Otherwise, authentication will fail. The format is `username:password`. `username` is your private key and `password` is an empty string.
{% /callout %}

If you encode `your_private_api_key:` using base64, you will get `eW91cl9wcml2YXRlX2FwaV9rZXk6`

```bash
curl https://api.imagekit.io/v1/files \
 -H 'Authorization: Basic eW91cl9wcml2YXRlX2FwaV9rZXk6'
```

## Rate limits

Except for the upload API, all our APIs are rate-limited to protect our infrastructure from excessive request rates and to keep ImageKit.io fast and stable for everyone.
    
Rate limiting is done across the account. When you exceed the rate limits for an endpoint, you will receive a `429` (Too many requests) response code.

Rate limiting is based on two primary thresholds:

1. **Burst (short-term)**: A limit on how many requests can be sent in a very short window (for example, per second).
2. **Sustained (long-term)**: A limit on how many requests can be sent over a longer window (for example, per minute).

When your requests exceed either the burst or the sustained threshold for a given endpoint, you’ll receive an HTTP **429 Too Many Requests** response. In that case, please sleep/pause for the number of milliseconds specified by the value of `X-RateLimit-Reset` response header before making additional requests to that endpoint.

### Recommended Safe Usage

Based on the majority of standard file and folder endpoints:

- **Reads**: Stay near or below **40 requests/second** on average. This remains comfortably under our common per-minute limit and leaves headroom for short bursts. Most read operations allow bursts of up to 100 requests/second.
- **Writes**: Aim for **5-20 requests/second** on average. Many write operations allow bursts of up to 100 requests/second, but some endpoints have tighter caps e.g. add bulk tags, remove bulk tags, custom metadata fields CRUD operations, etc, which are limited to 5 requests/second.

### Response headers to understand rate limits

You will also receive the following response headers in response to every API request that hits the rate limit. Use these headers to stay within rate limits or pause/sleep your workflow in case you exceed them.

{% table %}
- **Response header** {% width="30%" %}
- **Description** {% width="70%" %}
---
- **X-RateLimit-Limit**
- The maximum number of requests that can be made to this endpoint in the interval specified by `X-RateLimit-Interval` response header.
---
- **X-RateLimit-Reset**
- The amount of time in milliseconds before you can make another request to this endpoint. Pause/sleep your workflow for this duration.
---
- **X-RateLimit-Interval**
- The duration of the interval in milliseconds for which this rate limit was exceeded.
{% /table %}

### Request higher rate limits

If your workflow demands a higher rate limit, please contact us at [support@imagekit.io](mailto:support@imagekit.io).


---

# Source: /api-keys

---
title: API keys
description: Learn about ImageKit's API keys, standard and restricted keys, and how to keep your keys safe.
---

ImageKit [authenticates](/api-overview#authentication) API requests using API keys. We return an error if you don't include your key when making an API request or use an incorrect or outdated one.

Authentication to the API is performed via [HTTP Basic Auth](http://en.wikipedia.org/wiki/Basic_access_authentication). Provide your [private API key](#private-key) as the basic auth username value. You do not need to provide a password.

For example, you can provide the private API key in a curl request as:

```bash
curl https://api.imagekit.io/v1/files \ 
-u your_private_api_key:
# The colon prevents the curl from asking for a password.
```

You can view your API keys in the ImageKit.io dashboard under the [developer options](https://imagekit.io/dashboard/developer/api-keys).

![The API keys section in Developer options](https://ik.imagekit.io/ikmedia/docs_images/api-reference/api-introduction/webhooks/obtain-api-key_AzXoqM0WE.webp?tr=w-1600)
    
There are two types of API keys:

- **Standard keys**: A standard API key has read and write access to all the APIs. At any time, you can have a maximum of 5 standard keys.
- **Restricted key**: A restricted API key allows only the minimum [level of access](#resource-list) that you specify across all the APIs listed above. The three access levels are: `None`, `Read only`, and `Read and write`. For example, if you set `Read-only` permission for media access for your restricted key, you cannot use it to perform any upload, update, or delete operation. You can only perform operations like list and search files, get file details, get file metadata, etc. At any time, you can have a maximum of 5 restricted keys.

## Public key

This is used to identify your account in certain client-side file upload implementations. It is not meant to be a secret; you can publish this in client-side Javascript code or an Android or iPhone app. It is only used in upload API integration on client-side applications.

It always starts with the `public_` prefix to make it easy to identify.

## Private key

This should be kept confidential and only stored on your servers. When you make an API request, a private key is used to authenticate your account.

It always starts with `private_` prefix to make it easy to identify.

## Keeping your keys safe

It is strongly recommended that your private key be kept safe and confidential. To help keep your API keys secure, follow these best practices:

1. Do not embed API keys directly in your code. API keys that are embedded in code can be accidentally exposed to the public. For example, you may forget to remove the keys from the code that you share. Instead of embedding your API keys in your applications, store them in environment variables or in files outside of your application's source tree.
2. Do not store API keys in files inside your application's source tree. If you do, keep the files outside your application's source tree to help ensure your keys do not end up in your source code control system. This is particularly important if you use a public source code management system like GitHub.
3. Regularly [rotate your API keys](#rolling-keys). If you suspect your API keys have been compromised, rotate them immediately. You can also rotate your keys periodically as a security best practice.
4. Prefer using [restricted keys](#restricted-api-keys) over standard keys. Restricted keys limit the scope of access to your account, reducing the risk of unauthorized access.

## Rolling keys

If an API key is compromised, you should roll that pair immediately and start using the newly generated keys. The newly generated pair has the same resource access permissions as the old one.

You can choose when to expire the existing key:

- Immediately
- In 1 hour
- In 24 hours
- In 3 days
- In 7 days

The expiry period you choose, blocks and expires the existing key after the specified time period. Regardless of the expiry period, you can use the new key immediately.

![Roll API keys](https://ik.imagekit.io/ikmedia/docs_images/api-reference/api-introduction/webhooks/roll-api-key_uO_qlGz6W.webp?tr=w-1600)

## Deleting keys

You can delete any existing API key in your account. However, your account will always have at least one pair of active standard keys.

## Revealing keys

By default, the private key is masked for security reasons. You can click on the reveal icon next to the private key and enter your password to authorize and reveal the private keys. 

If you have logged in using SSO, you will first need to set the password for your account under the [profile section](https://imagekit.io/dashboard/profile).

If you have logged in using a one-time link sent to your email, you must set the password for your account under the [profile section](https://imagekit.io/dashboard/profile) and then reveal the private key.

## Restricted API keys

You can:

- Create a new restricted API key and specify its resource access permissions.
- Update resource access permissions on any existing restricted API keys.

![Create restricted API keys](https://ik.imagekit.io/ikmedia/docs_images/api-reference/api-introduction/webhooks/create-restricted-api-key_MOyq1TUOLz.webp?tr=w-1600)

The three access levels across any resource are: `None`, `Read only`, and `Read and write`.

## Resource list

{% linetabs %}

{% linetab title="Media managment" %}

{% table %}

- **Permission level** {% width="50%" %}
- **APIs** {% width="50%" %}
---
- **None**
- No APIs
---
- **Read**
- [List and search files](/api-reference/digital-asset-management-dam/list-and-search-assets)  
 [Get file details](/api-reference/digital-asset-management-dam/managing-assets/get-file-details)  
 [Get file version details](/api-reference/digital-asset-management-dam/managing-assets/get-file-version-details)  
 [Get file versions](/api-reference/digital-asset-management-dam/managing-assets/list-file-versions)  
 [Bulk job status](/api-reference/digital-asset-management-dam/managing-folders/bulk-job-status)  
 [Purge cache status](/api-reference/caching/purge-status)  
 [Get image metadata for uploaded media files](/api-reference/file-metadata/get-uploaded-file-metadata)  
 [Get image metadata from remote URL](/api-reference/file-metadata/get-metadata-from-url)  
 [Get custom metadata field](/api-reference/digital-asset-management-dam/custom-metadata-fields/list-all-fields)  
 [Get account usage information](/api-reference/account-management-api/get-usage)
---
- **Read and write**
- All APIs under read permission  
 [File upload](/api-reference/upload-file/upload-file)  
 [Secure file upload](/api-reference/upload-file/upload-file-v2)  
 [Update file details](/api-reference/digital-asset-management-dam/managing-assets/update-file-details)  
 [Add tags (bulk)](/api-reference/digital-asset-management-dam/managing-assets/add-tags-bulk)  
 [Remove tags (bulk)](/api-reference/digital-asset-management-dam/managing-assets/remove-tags-bulk)  
 [Remove AITags (bulk)](/api-reference/digital-asset-management-dam/managing-assets/remove-ai-tags-bulk)  
 [Delete file](/api-reference/digital-asset-management-dam/managing-assets/delete-file)  
 [Delete file version](/api-reference/digital-asset-management-dam/managing-assets/delete-file-version)  
 [Delete files (bulk)](/api-reference/digital-asset-management-dam/managing-assets/delete-multiple-files)  
 [Copy file](/api-reference/digital-asset-management-dam/managing-assets/copy-file)  
 [Move file](/api-reference/digital-asset-management-dam/managing-assets/move-file)  
 [Rename file](/api-reference/digital-asset-management-dam/managing-assets/rename-file)  
 [Restore file version](/api-reference/digital-asset-management-dam/managing-assets/restore-file-version)  
 [Create folder](/api-reference/digital-asset-management-dam/managing-folders/create-folder)  
 [Delete folder](/api-reference/digital-asset-management-dam/managing-folders/delete-folder)  
 [Copy folder](/api-reference/digital-asset-management-dam/managing-folders/copy-folder)  
 [Move folder](/api-reference/digital-asset-management-dam/managing-folders/move-folder)
 [Rename folder](/api-reference/digital-asset-management-dam/managing-folders/rename-folder)    
 [Purge cache](/api-reference/caching/purge-cache)  
 [Create custom metadata field](/api-reference/digital-asset-management-dam/custom-metadata-fields/create-new-field)  
 [Update custom metadata field](/api-reference/digital-asset-management-dam/custom-metadata-fields/update-existing-field)  
 [Delete custom metadata field](/api-reference/digital-asset-management-dam/custom-metadata-fields/delete-a-field)  
{% /table %}

{% /linetab %}

{% linetab title="Account managment" %}

{% table %}

- **Permission level** {% width="50%" %}
- **APIs** {% width="50%" %}
---
- **None**
- No APIs
---
- **Read**
- [List origins](/api-reference/account-management-api/origins/list-origins)  
 [Get origin](/api-reference/account-management-api/origins/get-origin)  
 [List URL endpoints](/api-reference/account-management-api/url-endpoints/list-url-endpoints)  
 [Get URL endpoint](/api-reference/account-management-api/url-endpoints/get-url-endpoint)

---
- **Read and write**
- All APIs under read permission  
 [Create origin](/api-reference/account-management-api/origins/create-origin)  
 [Update origin](/api-reference/account-management-api/origins/update-origin)  
 [Delete origin](/api-reference/account-management-api/origins/delete-origin)  
 [Create URL endpoint](/api-reference/account-management-api/url-endpoints/create-url-endpoint)  
 [Update URL endpoint](/api-reference/account-management-api/url-endpoints/update-url-endpoint)  
 [Delete URL endpoint](/api-reference/account-management-api/url-endpoints/delete-url-endpoint)
 
{% /table %}

{% /linetab %}


---

# Source: /webhooks

---
title: Webhooks
description: Learn how to configure and receive webhooks from ImageKit securely.
---

ImageKit uses webhooks to notify your application when an event occurs in your account. Webhooks are particularly useful for asynchronous events such as video encoding and extension processing during uploads.

## Steps to receive webhooks

1. [Configure the webhook](#configure-a-webhook) in your ImageKit dashboard.
2. Create a webhook endpoint as an HTTP endpoint (URL) on your server and [listen](#listen-to-webhook) for incoming webhook requests.
3. Handle requests from ImageKit by parsing each event object and returning `2xx` response status codes. You can also [verify the webhook signature](#verify-webhook-signature) to ensure the authenticity of the request. We recommend using the ImageKit SDK to handle webhook [signature verification](#verify-webhook-signature) and [prevent replay attacks](#preventing-replay-attacks).

## Configure a Webhook

Go to the [Developer options](https://imagekit.io/dashboard/developer) in the ImageKit dashboard. Under Webhooks, you will see the list of configured webhook endpoints.

Click the "Add new" button to create a new webhook endpoint.

![Create new webhook endpoint](https://ik.imagekit.io/ikmedia/docs_images/api-reference/api-introduction/webhooks/create-new-webhook-endpoint_yWUV8YlGH.png?tr=w-1600)

Enter a valid HTTP(S) endpoint, select the events you want to receive, and click "Create."

![Create webhook form;width=400](https://ik.imagekit.io/ikmedia/docs_images/api-reference/api-introduction/webhooks/create-webhook-form.png?v=1&tr=w-1600)

You should now see the webhook endpoint in the list.

![Webhook endpoint lists](https://ik.imagekit.io/ikmedia/docs_images/api-reference/api-introduction/webhooks/webhook-endpoint-lists_vH5I4Faas.png?tr=w-1600)

To update an existing endpoint, click `...`. You can change its current status (enabled or disabled) and update the list of active events.

![Update webhook endpoint;width=400](https://ik.imagekit.io/ikmedia/docs_images/api-reference/api-introduction/webhooks/update-webhook-endpoint.png?tr=w-1600)

## Listen to Webhook

Use a tool like [Ngrok](https://ngrok.com/) to make your webhook endpoint publicly accessible for testing webhook implementation.

All webhook bodies are JSON-encoded. The body schema may differ based on the event type, but the following fields are standard:

| Field      | DataType | Description                               |
| ---------- | -------- | ----------------------------------------- |
| type       | `string` | Type of event.                            |
| id         | `string` | Unique identifier of the event.           |
| created_at | `string` | Timestamp of the event in ISO8601 format. |
| data       | `JSON`   | Actual event payload in JSON format.      |

## Verify webhook signature

Webhook endpoints are publicly accessible, so filtering out malicious requests is essential. We recommend using the webhook signature to verify the authenticity of the webhook request and payload.

ImageKit follows the [Standard Webhooks](https://standardwebhooks.com) specification for secure webhook verification and sends `webhook-id`, `webhook-timestamp`, and `webhook-signature` HMAC-SHA256 signature headers.

You can use the [webhook secret](https://imagekit.io/dashboard/developer/webhooks), which starts with the `whsec_` prefix, to verify the webhook payload as explained below.

> We will continue to send the legacy `x-ik-signature` header as well if you are using an old SDK or old verification method.

### Verify signature with ImageKit SDK

We recommend using our official libraries to verify signatures. You can perform the verification by providing the raw event payload, request headers, and the webhook secret. If verification fails, you will get an error.

For development and testing purposes, SDKs also provide methods that skip signature verification entirely - however, these should never be used in production environments as they bypass critical security measures. 

We are updating our SDKs, so if you don't see a snippet for your language, refer to the [manual verification](#verify-signature-manually) process.

{% tabs %}
{% tab title="Node.js" %}

```javascript
import ImageKit from '@imagekit/nodejs';
import express from 'express';

const client = new ImageKit({
  privateKey: "your_private_key",
  webhookSecret: "whsec_..." // Copy from ImageKit dashboard
});

const app = express();

// For mixed APIs: Use JSON parser for all non-webhook routes
app.use((req, res, next) => {
  if (req.originalUrl === '/webhook') {
    next(); // Skip JSON parsing for webhook
  } else {
    express.json()(req, res, next);
  }
});

app.post(
  '/webhook',
  // ImageKit requires the raw body to construct the event
  express.raw({ type: 'application/json' }),
  (req, res) => {
    try {
      // Verify signature and parse webhook payload securely
      const event = client.webhooks.unwrap(req.body, {
        headers: req.headers
        // Optional: Use a different webhook secret for this request
        // key: 'whsec_different_secret'
      });
      
      // Alternative: For development/testing only (NEVER use in production)
      // const event = client.webhooks.unsafeUnwrap(req.body);

      console.log('Verified webhook event:', event.type);

      // Handle different event types with full type safety
      switch (event.type) {
        case 'video.transformation.accepted':
          console.log('Video transformation accepted:', event.data.asset.url);
          // Debugging: Track transformation requests
          break;
          
        case 'video.transformation.ready':
          console.log('Video transformation ready:', event.data.transformation.output?.url);
          // Update your database/CMS to show the transformed video
          // Example: updateVideoStatus(event.data.transformation.output.url, 'ready')
          break;
          
        case 'video.transformation.error':
          console.error('Video transformation error:', event.data.transformation.error?.reason);
          // Log error and check your origin/URL endpoint settings
          break;
          
        case 'upload.pre-transform.success':
          console.log('Pre-transform success:', event.data.fileId);
          // File uploaded and pre-transformation completed
          break;
          
        case 'upload.pre-transform.error':
          console.error('Pre-transform error:', event.data.transformation.error?.reason);
          break;
          
        case 'upload.post-transform.success':
          console.log('Post-transform success:', event.data.url);
          // Additional transformation completed
          break;
          
        case 'upload.post-transform.error':
          console.error('Post-transform error:', event.data.transformation.error?.reason);
          break;

        case 'file.created':
          console.log('DAM file created:', event.data.fileId);
          break;

        case 'file.updated':
          console.log('DAM file updated:', event.data.fileId);
          break;

        case 'file.deleted':
          console.log('DAM file deleted:', event.data.fileId);
          break;

        case 'file-version.created':
          console.log('DAM file version created:', event.data.fileId);
          break;

        case 'file-version.deleted':
          console.log('DAM file version deleted:', event.data.fileId);
          break;

        default:
          console.log(`Unhandled event type: ${event.type}`);
      }

      // Return a response to acknowledge receipt of the event
      res.json({ received: true });
      
    } catch (error) {
      // On error, log and return the error message
      console.log(`Error message: ${error.message}`);
      res.status(400).send(`Webhook Error: ${error.message}`);
    }
  }
);

const server = app.listen(3000);
console.log(
  `🚀 Webhook endpoint available at http://localhost:3000/webhook`
);
```
{% /tab %}

{% tab title="Python" %}

```python
import os
from flask import Flask, request, jsonify
from imagekitio import ImageKit

app = Flask(__name__)

imagekit = ImageKit(
    private_key=os.environ.get("IMAGEKIT_PRIVATE_KEY"),
    webhook_secret="whsec_..."  # Copy from ImageKit dashboard
)

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    payload = request.get_data(as_text=True)
    headers = dict(request.headers)
    
    try:
        # Verify signature and parse webhook payload securely
        event = imagekit.webhooks.unwrap(
            payload=payload,
            headers=headers
            # Optional: Use a different webhook secret for this request
            # key="whsec_different_secret"
        )
        
        # Alternative: For development/testing only (NEVER use in production)
        # event = imagekit.webhooks.unsafe_unwrap(payload)
        
        print(f"Verified webhook event: {event.type}")
        
        # Handle different event types with full type safety
        if event.type == 'video.transformation.accepted':
            print(f"Video transformation accepted: {event.data.asset.url}")
            # Debugging: Track transformation requests
            
        elif event.type == 'video.transformation.ready':
            print(f"Video transformation ready: {event.data.transformation.output.url}")
            # Update your database/CMS to show the transformed video
            # Example: update_video_status(event.data.transformation.output.url, 'ready')
            
        elif event.type == 'video.transformation.error':
            print(f"Video transformation error: {event.data.transformation.error.reason}")
            # Log error and check your origin/URL endpoint settings
            
        elif event.type == 'upload.pre-transform.success':
            print(f"Pre-transform success: {event.data.file_id}")
            # File uploaded and pre-transformation completed
            
        elif event.type == 'upload.pre-transform.error':
            print(f"Pre-transform error: {event.data.transformation.error.reason}")
            
        elif event.type == 'upload.post-transform.success':
            print(f"Post-transform success: {event.data.url}")
            # Additional transformation completed
            
        elif event.type == 'upload.post-transform.error':
            print(f"Post-transform error: {event.data.transformation.error.reason}")

        elif event.type == 'file.created':
            print(f"DAM file created: {event.data.file_id}")

        elif event.type == 'file.updated':
            print(f"DAM file updated: {event.data.file_id}")

        elif event.type == 'file.deleted':
            print(f"DAM file deleted: {event.data.file_id}")

        elif event.type == 'file-version.created':
            print(f"DAM file version created: {event.data.file_id}")
        
        elif event.type == 'file-version.deleted':
            print(f"DAM file version deleted: {event.data.file_id}")
            
        else:
            print(f"Unhandled event type: {event.type}")
        
        # Return a response to acknowledge receipt of the event
        return jsonify({"received": True})
        
    except Exception as error:
        # On error, log and return the error message
        print(f"Error message: {error}")
        return jsonify({"error": f"Webhook Error: {error}"}), 400

if __name__ == '__main__':
    app.run(port=3000)
    print("🚀 Webhook endpoint available at http://localhost:3000/webhook")
```
{% /tab %}

{% tab title="Go" %}

```go
package main

import (
	"fmt"
	"io"
	"log"
	"net/http"
	"os"

	"github.com/imagekit-developer/imagekit-go/v2"
	"github.com/imagekit-developer/imagekit-go/v2/option"
)

func main() {
	client := imagekit.NewClient(
		option.WithPrivateKey("your_private_key"),
		option.WithWebhookSecret("whsec_..."), // Copy from ImageKit dashboard
	)

	// Webhook handler with proper request body handling
	http.HandleFunc("/webhook", func(w http.ResponseWriter, req *http.Request) {
		// Limit request body size to prevent abuse (64KB should be sufficient for most webhooks)
		const MaxBodyBytes = int64(65536)
		req.Body = http.MaxBytesReader(w, req.Body, MaxBodyBytes)
		
		// Read the raw webhook payload
		payload, err := io.ReadAll(req.Body)
		if err != nil {
			fmt.Fprintf(os.Stderr, "Error reading request body: %v\n", err)
			w.WriteHeader(http.StatusServiceUnavailable)
			return
		}

		// Verify and unwrap webhook payload
		event, err := client.Webhooks.Unwrap(payload, req.Header)
		if err != nil {
			fmt.Fprintf(os.Stderr, "Invalid webhook signature or malformed payload: %v\n", err)
			w.WriteHeader(http.StatusUnauthorized)
			return
		}

		fmt.Printf("Verified webhook event: %s\n", event.Type)
		
		// Handle different event types with full type safety
		switch event.Type {
		case "video.transformation.accepted":
			videoEvent := event.AsVideoTransformationAcceptedEvent()
			fmt.Printf("Video transformation accepted: %s\n", videoEvent.Data.Asset.URL)
			// Debugging: Track transformation requests
			// handleVideoTransformationAccepted(videoEvent)
			
		case "video.transformation.ready":
			videoEvent := event.AsVideoTransformationReadyEvent()
			fmt.Printf("Video transformation ready: %s\n", videoEvent.Data.Transformation.Output.URL)
			// Update your database/CMS to show the transformed video
			// handleVideoTransformationReady(videoEvent)
			
		case "video.transformation.error":
			videoEvent := event.AsVideoTransformationErrorEvent()
			fmt.Printf("Video transformation error: %s\n", videoEvent.Data.Transformation.Error.Reason)
			// Log error and check your origin/URL endpoint settings
			// handleVideoTransformationError(videoEvent)
			
		case "upload.pre-transform.success":
			uploadEvent := event.AsUploadPreTransformSuccessEvent()
			fmt.Printf("Pre-transform success: %s\n", uploadEvent.Data.FileID)
			// File uploaded and pre-transformation completed
			// handleUploadPreTransformSuccess(uploadEvent)
			
		case "upload.post-transform.success":
			postEvent := event.AsUploadPostTransformSuccessEvent()
			fmt.Printf("Post-transform success: %s\n", postEvent.Data.Name)
			// Additional transformation completed
			// handleUploadPostTransformSuccess(postEvent)

		case "upload.pre-transform.error":
			uploadEvent := event.AsUploadPreTransformErrorEvent()
			fmt.Printf("Pre-transform error: %s\n", uploadEvent.Data.Transformation.Error.Reason)
			// Log error and investigate the transformation request

		case "upload.post-transform.error":
			postEvent := event.AsUploadPostTransformErrorEvent()
			fmt.Printf("Post-transform error: %s\n", postEvent.Data.Transformation.Error.Reason)

		case "file.created":
			fileEvent := event.AsFileCreateEvent()
			fmt.Printf("DAM file created: %s\n", fileEvent.Data.FileID)

		case "file.updated":
			fileEvent := event.AsFileUpdateEvent()
			fmt.Printf("DAM file updated: %s\n", fileEvent.Data.FileID)

		case "file.deleted":
			fileEvent := event.AsFileDeleteEvent()
			fmt.Printf("DAM file deleted: %s\n", fileEvent.Data.FileID)

		case "file-version.created":
			versionEvent := event.AsFileVersionCreateEvent()
			fmt.Printf("DAM file version created: %s\n", versionEvent.Data.FileID)

		case "file-version.deleted":
			versionEvent := event.AsFileVersionDeleteEvent()
			fmt.Printf("DAM file version deleted: %s\n", versionEvent.Data.FileID)
		// Handle other event types as needed
		default:
			fmt.Printf("Unhandled event type: %s\n", event.Type)
		}

		w.WriteHeader(http.StatusOK)
	})

	// Start the server
	fmt.Println("Webhook server listening on :8080")
	log.Fatal(http.ListenAndServe(":8080", nil))
}
```
{% /tab %}

{% tab title="Ruby" %}

```ruby
require 'json'
require 'sinatra'
require 'imagekitio'

client = Imagekitio::Client.new(
  private_key: "your_private_key",
  webhook_secret: "whsec_..." # Copy from ImageKit dashboard
)

# Using Sinatra
post '/webhook' do
  payload = request.body.read
  event = nil

  begin
    # Verify signature and parse webhook payload securely
    event = client.webhooks.unwrap(payload, headers: {
      "webhook-id" => request.env["HTTP_WEBHOOK_ID"],
      "webhook-timestamp" => request.env["HTTP_WEBHOOK_TIMESTAMP"],
      "webhook-signature" => request.env["HTTP_WEBHOOK_SIGNATURE"]
    })
  rescue => e
    puts "⚠️  Webhook signature verification failed. #{e.message}"
    status 400
    return
  end

  # Alternative: For development/testing only (NEVER use in production)
  # event = client.webhooks.unsafe_unwrap(payload)

  # Handle the event
  case event.type
  when 'video.transformation.accepted'
    puts "Video transformation accepted: #{event.data.asset.url}"
    # Debugging: Track transformation requests

  when 'video.transformation.ready'
    puts "Video transformation ready: #{event.data.transformation.output.url}"
    # Update your database/CMS to show the transformed video

  when 'video.transformation.error'
    puts "Video transformation error: #{event.data.transformation.error.reason}"
    # Log error and check your origin/URL endpoint settings

  when 'upload.pre-transform.success'
    puts "Pre-transform success: #{event.data.file_id}"
    # File uploaded and pre-transformation completed

  when 'upload.pre-transform.error'
    puts "Pre-transform error: #{event.data.transformation.error.reason}"

  when 'upload.post-transform.success'
    puts "Post-transform success: #{event.data.url}"
    # Additional transformation completed

  when 'upload.post-transform.error'
    puts "Post-transform error: #{event.data.transformation.error.reason}"

  when 'file.created'
    puts "DAM file created: #{event.data.file_id}"

  when 'file.updated'
    puts "DAM file updated: #{event.data.file_id}"

  when 'file.deleted'
    puts "DAM file deleted: #{event.data.file_id}"

  when 'file-version.created'
    puts "DAM file version created: #{event.data.file_id}"

  when 'file-version.deleted'
    puts "DAM file version deleted: #{event.data.file_id}"

  else
    puts "Unhandled event type: #{event.type}"
  end

  status 200
end
```
{% /tab %}

{% tab title="Java" %}

```java
import io.imagekit.client.ImageKitClient;
import io.imagekit.client.okhttp.ImageKitOkHttpClient;
import io.imagekit.models.webhooks.UnwrapWebhookEvent;
import io.imagekit.models.webhooks.UnwrapWebhookParams;
import io.imagekit.models.webhooks.VideoTransformationAcceptedEvent;
import io.imagekit.models.webhooks.VideoTransformationReadyEvent;
import io.imagekit.models.webhooks.VideoTransformationErrorEvent;
import io.imagekit.models.webhooks.UploadPreTransformSuccessEvent;
import io.imagekit.models.webhooks.UploadPreTransformErrorEvent;
import io.imagekit.models.webhooks.UploadPostTransformSuccessEvent;
import io.imagekit.models.webhooks.UploadPostTransformErrorEvent;
import io.imagekit.models.webhooks.FileCreateEvent;
import io.imagekit.models.webhooks.FileUpdateEvent;
import io.imagekit.models.webhooks.FileDeleteEvent;
import io.imagekit.models.webhooks.FileVersionCreateEvent;
import io.imagekit.models.webhooks.FileVersionDeleteEvent;
import io.imagekit.core.http.Headers;
import spark.Request;
import spark.Response;
import java.util.Map;
import static spark.Spark.*;

public class WebhookHandler {
    public static void main(String[] args) {
        ImageKitClient client = ImageKitOkHttpClient.builder()
            .privateKey("your_private_key")
            .webhookSecret("whsec_...") // Copy from ImageKit dashboard
            .build();

        // Using Spark framework (http://sparkjava.com)
        post("/webhook", (request, response) -> handleWebhook(client, request, response));
        
        System.out.println("🚀 Webhook endpoint available at http://localhost:4567/webhook");
    }

    public static Object handleWebhook(ImageKitClient client, Request request, Response response) {
        String payload = request.body();
        UnwrapWebhookEvent event = null;

        try {
            // Build headers map for webhook verification
            Headers headers = Headers.builder()
                .putAll(Map.of(
                    "webhook-id", request.headers("webhook-id"),
                    "webhook-timestamp", request.headers("webhook-timestamp"),
                    "webhook-signature", request.headers("webhook-signature")
                ))
                .build();

            // Verify signature and parse webhook payload securely
            event = client.webhooks().unwrap(
                UnwrapWebhookParams.builder()
                    .payload(payload)
                    .headers(headers)
                    .build()
            );

            // Alternative: For development/testing only (NEVER use in production)
            // event = client.webhooks().unsafeUnwrap(payload);

            // Handle different event types
            if (event.isVideoTransformationAccepted()) {
                VideoTransformationAcceptedEvent videoEvent = event.asVideoTransformationAccepted();
                System.out.println("Video transformation accepted: " + videoEvent.data().asset().url());
                // Debugging: Track transformation requests
                
            } else if (event.isVideoTransformationReady()) {
                VideoTransformationReadyEvent videoEvent = event.asVideoTransformationReady();
                System.out.println("Video transformation ready: " + 
                    videoEvent.data().transformation().output().url());
                // Update your database/CMS to show the transformed video
                
            } else if (event.isVideoTransformationError()) {
                VideoTransformationErrorEvent videoEvent = event.asVideoTransformationError();
                System.out.println("Video transformation error: " + 
                    videoEvent.data().transformation().error().reason());
                // Log error and check your origin/URL endpoint settings
                
            } else if (event.isUploadPreTransformSuccess()) {
                UploadPreTransformSuccessEvent uploadEvent = event.asUploadPreTransformSuccess();
                System.out.println("Pre-transform success: " + uploadEvent.data().fileId());
                // File uploaded and pre-transformation completed
                
            } else if (event.isUploadPreTransformError()) {
                UploadPreTransformErrorEvent uploadEvent = event.asUploadPreTransformError();
                System.out.println("Pre-transform error: " + 
                    uploadEvent.data().transformation().error().reason());
                
            } else if (event.isUploadPostTransformSuccess()) {
                UploadPostTransformSuccessEvent postEvent = event.asUploadPostTransformSuccess();
                System.out.println("Post-transform success: " + postEvent.data().url());
                // Additional transformation completed
                
            } else if (event.isUploadPostTransformError()) {
                UploadPostTransformErrorEvent postEvent = event.asUploadPostTransformError();
                System.out.println("Post-transform error: " + 
                    postEvent.data().transformation().error().reason());

            } else if (event.isFileCreate()) {
                FileCreateEvent fileEvent = event.asFileCreate();
                System.out.println("DAM file created: " + fileEvent.data().fileId());

            } else if (event.isFileUpdate()) {
                FileUpdateEvent fileEvent = event.asFileUpdate();
                System.out.println("DAM file updated: " + fileEvent.data().fileId());

            } else if (event.isFileDelete()) {
                FileDeleteEvent fileEvent = event.asFileDelete();
                System.out.println("DAM file deleted: " + fileEvent.data().fileId());

            } else if (event.isFileVersionCreate()) {
                FileVersionCreateEvent versionEvent = event.asFileVersionCreate();
                System.out.println("DAM file version created: " + versionEvent.data().fileId());

            } else if (event.isFileVersionDelete()) {
                FileVersionDeleteEvent versionEvent = event.asFileVersionDelete();
                System.out.println("DAM file version deleted: " + versionEvent.data().fileId());
                
            } else {
                System.out.println("Unhandled event type");
            }

            // Return a response to acknowledge receipt of the event
            response.status(200);
            return "";

        } catch (Exception e) {
            // On error, log and return the error message
            System.out.println("⚠️  Webhook error while validating signature: " + e.getMessage());
            response.status(400);
            return "";
        }
    }
}
```
{% /tab %}
{% /tabs %}

### Verify signature manually

{% linetabs %}
{% linetab title="Standard Webhooks (Recommended)" %}

ImageKit follows the [Standard Webhooks](https://standardwebhooks.com) specification for secure webhook verification. This approach provides better security and standardized implementation.

For implementation examples in Python, Node.js (use our SDK), PHP, Go, and other languages, refer to the [Standard Webhooks GitHub repository](https://github.com/standard-webhooks/standard-webhooks). The repository contains complete examples and libraries for all supported languages.

**Important:** When using Standard Webhooks libraries directly, make sure to base64 encode your webhook secret before passing it to the library.

{% /linetab %}

{% linetab title="Legacy Method" %}

ImageKit webhook requests contain an `x-ik-signature` header like this:

```txt
x-ik-signature: t=1655795539264,v1=b6bc2aa82491c32f1cbef0eb52b7ffaa51467ea65a03b5d4ccdcfb9e0941c946
```

The timestamp of the signature is a Unix timestamp in milliseconds, prefixed with `t=`. The HMAC signature is prefixed with `v1=`.

Once you have retrieved the webhook signature from the request header and raw request body, you can verify the authenticity of the webhook request in the following steps:

**Step 1:** Extract each item from the `x-ik-signature` by splitting on the `,` separator.

```javascript
items = 't=1655795539264,v1=b6bc2aa82491c32f1cbef0eb52b7ffaa51467ea65a03b5d4ccdcfb9e0941c946'.split(',')
// [ 't=1655795539264', 'v1=b6bc2aa82491c32f1cbef0eb52b7ffaa51467ea65a03b5d4ccdcfb9e0941c946' ]
```

**Step 2:** Extract the timestamp.

```javascript
timestamp = 't=1655795539264'.split('=')[1]
// '1655795539264'
```

**Step 3:** Extract the signature encoded as a hex string.

```javascript
signature = 'v1=b6bc2aa82491c32f1cbef0eb52b7ffaa51467ea65a03b5d4ccdcfb9e0941c946'.split('=')[1]
// 'b6bc2aa82491c32f1cbef0eb52b7ffaa51467ea65a03b5d4ccdcfb9e0941c946'
```

**Step 4:** Compute the HMAC hash using the webhook secret, signature timestamp, and raw request body.

- The HMAC key is the webhook secret.
- The HMAC payload is formed by concatenating the timestamp (as a numeric string), the character `.`, and the raw request body (encoded as a UTF8 string).
- Use the SHA256 algorithm to compute the HMAC hash.
- The HMAC hash is encoded as a hex string.

Here is an example in Node.js:

```javascript
const createHmac = require("crypto").createHmac;
var signature = createHmac('sha256', webhookSecret)
    .update(timestamp + '.' + rawRequestBody)
    .digest('hex');
```

**Step 5:** Compare the signature with the signature received in the `x-ik-signature` header. The webhook request is valid if they are the same.

{% /linetab %}
{% /linetabs %}

## Preventing replay attacks

When an attacker intercepts a webhook request, they can replay it multiple times with a valid signature.

To mitigate this, the ImageKit webhook signature contains a timestamp. The timestamp is generated before the webhook request is sent to your server.

The verification method in the ImageKit SDK returns the timestamp and parsed event object.

If the timestamp is within the tolerance limit, the request can be considered valid, or you can reject it.

Optionally, a stronger approach is to use a nonce to prevent replay attacks. You can use the Event ID as a nonce, which is guaranteed to be unique across all events. You can find the event ID in the `id` field of the event object.

## List of events

Below is the list of events for which ImageKit calls your configured webhook:

- [video.transformation.accepted](/video-webhook-events#video.transformation.accepted)
- [video.transformation.ready](/video-webhook-events#video.transformation.ready)
- [video.transformation.error](/video-webhook-events#video.transformation.error)
- [upload.pre-transform.success](/dam/pre-and-post-transformation-on-upload#pre-transformation-events)
- [upload.pre-transform.error](/dam/pre-and-post-transformation-on-upload#pre-transformation-events)
- [upload.post-transform.success](/dam/pre-and-post-transformation-on-upload#post-transformation-events)
- [upload.post-transform.error](/dam/pre-and-post-transformation-on-upload#post-transformation-events)
- [file.created](/dam/overview#file.created)
- [file.updated](/dam/overview#file.updated)
- [file.deleted](/dam/overview#file.deleted)
- [file-version.created](/dam/overview#file-version.created)
- [file-version.deleted](/dam/overview#file-version.deleted)


---

# Source: /account-management

---
title: Account Management
description: Manage your account, billing, and active sessions, and track changes with audit logs.
---

In this section, we will cover the following:

- Where to find the [ImageKit ID and Processing Region](#imagekit-id-and-processing-region) for your account?
- How to [delete your account](#delete-account)?
- How to [manage users and permissions](/user-management)?
- How to [manage currently active sessions](/session-management)
- How to [setup SSO](/single-sign-on/overview) for your account?
- [General audit logs](/central-audit-logs) for your account to monitor changes to account configuration, settings, and more. [DAM audit logs](./dam/history-and-audit-logs) to monitor changes in the DAM are covered in a separate guide.
- [Billing, subscription management, and invoices](/billing-and-subscription).

## ImageKit ID and Processing Region

Go to the [profile section](https://imagekit.io/dashboard/profile) to see your ImageKit ID and the processing region. If you want to change either of them, please contact us at [support@imagekit.io](mailto:support@imagekit.io).

![Profile section](https://ik.imagekit.io/ikmedia/docs_images/features/user-management/profile-section.png?tr=w-1600)

## Delete Account

To delete your account, go to the profile section and click on the delete account button. It's important to note that after you confirm the deletion, this action is irreversible, and all your data will be permanently erased from the systems.


---

# Source: /user-management

---
title: User management
description: Manage users, user groups, roles, and permissions in your ImageKit account.
---

Under the [User Management](https://imagekit.io/dashboard/user-management/users) section in the dashboard, you can add, edit, and delete users and assign them specific roles. When you add a new user, they receive an email to set their account password. Alternatively, they can log in with Google using the same email to access the account.

You can also create user groups like `Marketing Team`, `Sales Team`, etc., and add users to these groups. The user groups can be used to share and collaborate in the DAM.

Only a user with an **Account Administrator** role can manage users and groups.

![User and user groups](<https://ik.imagekit.io/ikmedia/docs_images/features/user-management/user-management-screen_7uJqtuFVD.png?tr=w-1600>)

{% callout style="info" %}
Depending on your plan, the number of users you can create might be capped, and you may receive an error when trying to add more users. Please contact the [support team](mailto:support@imagekit.io) to raise this cap.
{% /callout %}

## User Roles
ImageKit has predefined roles you can assign to users. These roles align with the most common access requirements in teams.

You can select a user's role when adding or editing them. 

![;width=400](https://ik.imagekit.io/ikmedia/docs_images/features/user-management/add-user-form_6dtQOem-U.png?tr=w-1600)

- **Account Administrator**: Account administrators have access to everything.
- **Developer**: Developers have access to all account features and settings except user management, billing, and subscription.
- **Media Library Full Access**: Users with this role have full access to the Media Library. They can upload, delete, and manage assets. They can also view and manage audit logs for the Media Library. However, they cannot access account settings, user management, billing, or subscriptions.
- **Media Library View-only Access**: Users with this role can only view assets in the Media Library. They cannot upload, delete, or manage assets. They can also view audit logs for the Media Library.
- **Media Library Restricted Access**: A user with this role has restricted access to the Media Library. This user can only access and work on the files, folders, and media collections shared with them based on their permission level.
- **Finance**: Users with this role can view billing, subscription, usage analytics, and invoices. They can also cancel the subscription and update the payment method.

## User groups

User groups combine different users under a logical group, mimicking how we function as teams at work. Adding users to groups makes it easier to share assets in the DAM with the entire group or team in one go. 

For example, all Marketing team members would need access to upload to the "Social Media Ads" folder. You can add all team members to a "Marketing team" group and share the relevant folder with them, providing each individual with the necessary access in one go.

To create, edit, or delete user groups, go to the [user groups](https://imagekit.io/dashboard/user-management/user-groups) section in the dashboard.

![User groups](https://ik.imagekit.io/ikmedia/docs_images/features/user-management/user-groups.png?tr=w-1600)

{% callout style="info" %}
**User group limits**
- There are no limits to the number of users that can be added to a user group.
- You can create at most five user groups. Please contact the [support team](mailto:support@imagekit.io) if you want to create more user groups.
- A user group's name is case insensitive and has to be unique. The name can only contain alphabets, numbers, and spaces.
{% /callout %}

## Multi-factor authentication

Your ImageKit dashboard is the central location for all your media assets and delivery configurations. You should secure access to it using a strong password. But, to ensure even better security, we recommend using Multi-Factor Authentication (MFA) to log in to your account.

MFA adds a layer of protection to the login process. A one-time password is generated and sent to the user's registered email address, which is required for additional identity verification.

At the moment, ImageKit supports MFA only by email.

You can either enforce MFA for all users in your account or enable it for your account individually.

### Enforce MFA for all users

If you have administrator privileges on your ImageKit account, you can enforce MFA for all the users in your account from the [User Management page](https://imagekit.io/dashboard/user-management). 

A user cannot override this setting on their profile.

![Enforce MFA for all users](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/mfa-enforce-user-management.png?tr=w-1600>)

### Enable MFA on your profile

Every user can enable MFA for their account from their [User Profile page](https://imagekit.io/dashboard/profile). 

This option is unavailable if an account administrator has enforced MFA for all users belonging to that account.

![MFA for your account](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/mfa-user-profile.png?tr=w-1600>)

## Single sign-on

Learn how to set up Single Sign-On (SSO) for your ImageKit account [here](/single-sign-on/overview).


---

# Source: /session-management

---
title: Session Management
description: Manage your active sessions and terminate them remotely.
---

You may access the ImageKit dashboard on multiple devices simultaneously, such as your computer, tablet, and phone. The dashboard is the central location for all your media assets, so keeping track of which devices you are logged in from is vital.

## View active sessions

The [User Profile section](https://imagekit.io/dashboard/profile) provides a simple, easy-to-use interface for this. To view it, go to your user profile page and scroll down to the "Active sessions" table.

The session table displays information about your active sessions, like the IP address, the device and browser used, and the last active time.

You can only view and terminate your active sessions, not those of other users in your ImageKit account.

![Session management screen](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/session-management-1.png?tr=w-1600>)

## Terminate an active session

Sometimes, you may want to terminate an active session. You can do this by clicking the terminate icon corresponding to that session.

![Terminate a session](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/session-management-2.png?tr=w-1600>)

If you encounter any issues using this feature or have questions or suggestions, please email us at [support@imagekit.io](mailto:support@imagekit.io).


---

# Source: /central-audit-logs

---
title: Central Audit Logs
description: Audit logs provide detailed insights into critical operations performed by all the users in your account.
---

{% callout style="info" %}
**Enterprise Plans only**\
This feature is available only on custom enterprise pricing plans.
{% /callout %}

With multiple users possibly having access to your ImageKit dashboard, organization administrators and auditors need to have information about the activities of various users inside the dashboard to diagnose and troubleshoot various issues, like configuration changes, suspicious activities, etc.

This is where audit logs come into play, providing detailed insights into operations performed by all the users in your account.

### Available audit logs

Audit logs are provided for all write activities, i.e., create, update, and delete -

- External storage
- URL endpoints
- Performance center
- Developer options
- User management
- Billing details
- Settings
- Purge cache

This covers all the access and configuration-related changes inside your dashboard. 

{% callout style="info" %}
DAM audit logs are separate from Central audit logs. They help monitor uploads, deletions, access control changes, etc., happening in the Media Library. You can read more about them [here](/dam/history-and-audit-logs).
{% /callout %}

We store audit logs for 12 months.

Once the feature is enabled for your account, you can [access audit logs inside your dashboard here](https://imagekit.io/dashboard/audit-logs).

![Accessing Audit Logs](<https://ik.imagekit.io/ikmedia/docs/account-management/audit-logs-menu-imagekit_wiFmddgUvQ.jpg?tr=w-1600>)

On the Audit Logs page, you can filter audit logs by users, types of operations, and the start and end dates of the operations. After setting your criteria, click on "Submit".

If there are any logged events, information such as user, time, type of operation, and status will be displayed in a tabular format. Clicking on an event's row will load additional details about the event, including the API used, the request payload for that API, the response data received (if any), the time of operation, and the IP address that initiated this operation. The API and the associated request and response data will help you determine the exact change made during the operation.

![Audit Logs in ImageKit](<https://ik.imagekit.io/ikmedia/docs/account-management/audit-logs-imagekit_nr5FYSMWTo.png?tr=w-1600>)


---

# Source: /single-sign-on/overview

---
title: Single Sign-On (SSO) Overview
description: Single sign-on (SSO) is an authentication method that allows users to log in to ImageKit with a single unique ID provided through a trusted Identity Provider (IdP).
---

{% callout style="info" %}
**Important info**

1. This feature is available only on custom enterprise pricing plans.
2. [Multi-factor authentication (MFA)](/user-management#multi-factor-authentication) setting is not applicable for users logging in via single sign-on (SSO) authentication and enabling/disabling it will have no effect on the authentication flow of the user to ImageKit's dashboard. If you wish to enable MFA, you may do so in your Identity Provider (IdP) platform.
{% /callout %}

Single sign-on (SSO) is an authentication method that allows users to log in to ImageKit with a single unique ID provided through a trusted Identity Provider (IdP).

SSO adds a layer of centralized control to user management. You can manage all the users in your organization and assign their ImageKit role from a central Identity Provider (IdP) platform. ImageKit will use that IdP to register, authenticate and authorize your users.

![ImageKit SSO login screen](<https://ik.imagekit.io/ikmedia/docs_images/old-docs-images/sso-login-screen.png?tr=w-1600>)

## How to set up SSO?

If you have administrator privileges on your ImageKit account, you can set up SSO for all the users in your account by following these guides for supported Identity Providers:

- [Set up SSO for ImageKit on Azure](/single-sign-on/azure)
- [Set up SSO for ImageKit on Okta](/single-sign-on/okta)
- [Set up SSO for ImageKit on OneLogin](/single-sign-on/onelogin)
- [Set up SSO for ImageKit on AD FS](/single-sign-on/active-directory-federation-services-ad-fs)


## How does ImageKit use SSO?

ImageKit uses SAML-based authentication for "Just In Time" (JIT) provisioning for your users. JIT provisioning means that you do not need to create or update users on the ImageKit [User management](/user-management) page manually. This will be done automatically whenever a user that exists on your IdP logs into ImageKit using SSO.

For this, you need to configure SAML provisions on your Identity Provider platform.

## Register a new user on ImageKit using SSO

Users on your IdP that do not yet have an account on ImageKit must initiate authentication through the SSO application on your IdP portal for the first time. 

This process will provide ImageKit with the information needed to register that user on ImageKit and associate them with your organization account.

Upon successful authentication from the IdP, ImageKit will parse the SAML response. If a user with the unique email ID provided in the response does not already exist on ImageKit, a new user having the specified email ID, full name and ImageKit role will be registered under your organization account.

## Log in and update an existing user on ImageKit using SSO

Registered users can log in to ImageKit using SSO on [this page](https://imagekit.io/single-sign-on). Once they enter their registered email ID and submit the form, they will be redirected to the associated IdP for authentication. 

Alternatively, they may use the SSO application on your IdP portal to initiate authentication directly.

Upon successful authentication response from the IdP, ImageKit will check if there have been any changes to the user's information (such as full name and ImageKit role) since their last login on ImageKit. If so, the information will be updated on ImageKit automatically. 

## SSO and Multi-factor authentication (MFA)

Since the primary authentication of SSO users is provided by the Identity Provider (IdP), multi-factor authentication for these users is also best configured through the IdP. You can follow the documentation of your configured IdP to set it up on its platform. 

Even if an SSO user enables MFA on their own profile through the User profile page or an administrator enforces MFA for all users through the User Management Page, no unique code will be sent to the email associated with the SSO user's account and the user will be redirected to ImageKit dashboard following successful authentication by IdP.

## Delete an existing user

When a user is deleted from your IdP, they would be unable to log in to ImageKit using SSO. However, their account would still exist on ImageKit and count towards your subscription plan. To avoid this, you should delete them immediately from the User Management page on ImageKit as well.


---

# Source: /billing-and-subscription

---
title: Billing and subscription
description: Learn how to manage your billing, subscription, and invoices with ImageKit.io.
---

## Billing details

Update your billing information in the dashboard from the [billing center](https://imagekit.io/dashboard/billing/details). You can modify your company name, billing email, company address, and tax ID to ensure accurate invoices.

## Manage subscriptions

View your current subscription's pricing plan and inclusions [here](https://imagekit.io/dashboard/billing/subscriptions). You can also update your payment method or cancel your subscription. For details on pricing parameters and inclusions, refer to this [document](/how-pricing-works#pricing-parameters).

### How to cancel your subscription

Cancel your subscription through the [billing center](https://imagekit.io/dashboard/billing/subscriptions). Before proceeding, ensure the following conditions are met:

1. **No unpaid invoices**  
 Verify all invoices are paid. Check your invoices [here](https://imagekit.io/dashboard/invoices).
2. **Usage within free plan limits**  
 Ensure your usage is within the limits of the Forever Free plan. View limits [here](https://imagekit.io/plans). If your media library exceeds 50,000 files or folders, the "empty media library" will not work. You can use the [bulk file delete API](https://imagekit.io/docs/api-reference/digital-asset-management-dam/managing-assets/delete-multiple-files) to delete files in smaller batches. Alternatively, we will do it for you. Contact support for assistance.
3. **No URLs tracked in the performance center**  
 Ensure no URLs are currently tracked in your dashboard [here](https://imagekit.io/dashboard/performance-alerts).
4. **No custom domain names configured**  
 If custom domain names are configured, our support team will assist in removing these settings.

If you meet these conditions and encounter issues, please share screenshots of the error message with support for assistance.

### Update credit card details

You can update your credit card details [here](https://imagekit.io/dashboard/billing/subscriptions). Once updated, our payment processor, Stripe, will automatically charge the card for any outstanding invoices. This process may take some time to complete. If you wish to clear outstanding invoices immediately, navigate to the [invoice section](https://imagekit.io/dashboard/invoices) and click the "Pay now" button for each invoice.

## Credit balance

With the credit balance, you can prepay for future usage and receive a **15% discount** on the amount you add. For example, adding $1000 to your credit balance will cost you $850. Your credit balance is automatically applied to reduce the amount on your future invoices, ensuring uninterrupted service.

Adding credit is available for accounts with an active subscription and without a custom pricing plan. This is especially helpful if you face issues with monthly auto-debit due to RBI regulations or similar restrictions.

To add credit, visit the [credit balance page](https://imagekit.io/dashboard/billing/credit-balance), enter the desired amount, and proceed with the payment. If authentication (e.g., 3D Secure) is required, you will be redirected to your bank's authentication page. Once the payment is processed, the credit will automatically be applied to future invoices.

![Add credit balance](<https://ik.imagekit.io/ikmedia/docs_images/features/credit-balance/add-credit-balance.png?tr=w-1600>)

### Few things about credit balance

- You will receive a confirmation email and a receipt after payment. If authentication was required, check your email for any pending actions.
- The credit balance typically updates immediately after payment. In rare cases, it may take up to an hour to reflect. Contact support if it does not update within this time.
- Adding credit upfront helps avoid service interruptions caused by payment issues, such as those related to RBI regulations for Indian-issued cards.


## Invoices

Visit the [invoice section](https://imagekit.io/dashboard/invoices) to:

- View and download your invoices.
- Check your upcoming bill.

ImageKit generates invoices at the beginning of each month for usage during the previous month.

## Payment troubleshooting

### Card not working

Ensure your card details are accurate and that the card has sufficient funds. For Indian-issued cards, payment issues may occur due to RBI regulations. To avoid interruptions, consider paying upfront with a **15% discount** by [adding credit balance](#credit-balance).

### Moving to manual invoicing

Manual billing is available exclusively for enterprise accounts on a case-by-case basis. Reach out to support for more information.

### My account is disabled due to non-payment

If your account is disabled due to non-payment, ensure all outstanding invoices are paid. Once payment is made, your account will be reactivated automatically.

### Payment made, but invoice not marked as paid

If you paid using the "Pay now" button, the invoice is marked as paid immediately. For bank transfer/manual invoicing, share these details with support to verify your payment:

1. **Payment advice or transaction details**  
 This helps us locate and confirm your payment.
2. **Invoice details**  
 Include the invoice number and payment date to expedite resolution.

Verification may take 24–48 hours. Once completed, we’ll update our records and notify you.

## Billing alerts

Managing your ImageKit.io billing is crucial to staying within budget and optimizing usage. Setting up billing alerts ensures timely notifications about your account's billing status. Use the [analytics API](/api-reference/account-management-api/get-usage) to build custom usage-based alerts.

### Creating a billing alert

1. Navigate to your billing alerts page [here](https://imagekit.io/dashboard/billing/subscriptions).
2. Enter the "Threshold amount" in the form.
3. Press "Enter" or click the "Save" button.

Review your recent invoices to determine a suitable threshold.

![Billing alerts](<https://ik.imagekit.io/ikmedia/docs_images/features/billing-alerts/set-billing-alert-screenshot_qDVn-hUTP.png?tr=w-1600>)

### Deleting a billing alert

1. Navigate to your billing alerts page [here](https://imagekit.io/dashboard/billing/subscriptions).
2. Click the "Remove alert" button.

![Deleting billing alerts](<https://ik.imagekit.io/ikmedia/docs_images/features/billing-alerts/remove-billing-alert-screenshot_-sgrb10dQ5.png?tr=w-1600>)

### Notifications for billing alerts

Users with account administrator and finance roles will receive billing alerts. Learn more about user roles [here](/user-management#user-roles). Alerts are sent once a month when the upcoming invoice exceeds the defined threshold.


---

# Source: /how-pricing-works

---
title: Pricing Plan Parameters
description: Learn how different plans and pricing parameters work in ImageKit
---

ImageKit offers various plans to meet your requirements. In this document, we will examine different plan types and pricing parameters to help you understand which plan suits your requirements and how your billing will change with usage.

## Plan Types
ImageKit offers two plan types, as shown on the [pricing page](https://imagekit.io/plans/). 
Complete Media Processing + DAM plans - These plans are suitable if
You want to optimize, transform, and deliver images, videos, and other assets on your website or app.
Your entire team wants a central place to store, manage, collaborate on, and share digital assets in a DAM, along with the ability to deliver optimized content from that DAM on your website and app.
DAM-only plan - These plans are suitable if your team wants to use ImageKit only to store, manage, collaborate on, and share digital assets. While assets stored in the DAM do get built-in media optimizations and transformations, the primary use of this plan is only for digital asset management and not for media delivery on websites and apps.

## Pricing Parameters
ImageKit has several different pricing parameters. First, we will understand each parameter and then see how it impacts usage and billing on different plans.

1. **Bandwidth**: This is the total optimized data transfer from your account. For example, if you have a 500KB original image and can optimize it to 30KB with ImageKit, then the bandwidth used for billing is 30KB. If there are 2 million requests for this image on your website, the total bandwidth consumed is 30KB x 2 million = 60GB. 

    {% callout style="info" %}
    If the image is cached on the user's device, and the request never comes to ImageKit, it is not counted towards bandwidth consumption. If the image is already processed and cached on ImageKit, it is still counted towards bandwidth consumption.
    {% /callout %}

2. **Storage**: This is the total size of files you upload to ImageKit's Media Library. If you upload 100 files of 2MB each, your total storage usage is 2 x 100MB = 200MB. Connecting your external storage or server with ImageKit does not count toward storage usage in ImageKit. ImageKit does not charge for internal storage generated by caching image or video transformations. You are only billed for what you upload to the Media Library.

3. **Video Processing Units**: When you process any video for the first time with ImageKit, then it consumes Video Processing Units. These units are proportional to the output resolution and duration. Repeat delivery of videos does not consume video processing units; it counts only towards bandwidth.

    Read more about [how video processing units are consumed](#video-processing-units-pricing).

4. **Extension Units**: These units are consumed when you use third-party services integrated within ImageKit. Services such as AI tagging using Google and AWS integrations, AI-powered background removal, and more, consume extension units only when you explicitly call these operations via the API or the Media Library.

Read more about how extension units are consumed in [here](#extension-units-pricing).

5. **Users**: Any user, including the primary account administrator, with login access to the ImageKit account is considered towards this parameter. You can find the users added to your account [here](https://imagekit.io/dashboard/user-management/users). 

    If you use [sub-accounts](/sub-accounts), and the sub-account is set to "Bill to Parent", then the users in that account also count towards the billing against this parameter on the Parent account. 

    Users viewing content via [Public Links](/dam/public-links) or accessing the content via the CDN-powered media URLs on a website or app do not count towards this parameter.

6. **Custom Domain Names**: If you use a [custom domain name for media delivery](/core-delivery-features#using-custom-domain-name) with ImageKit, then the number of unique domain names you have count towards this parameter.

7. **Purge Cache Requests**: This parameter counts the number of [cache purge requests](/cdn-caching-and-purging#purging-the-cache) you issue for content cached during media delivery.

8. **Original Cache Storage**: If you utilize the feature to [save a copy of the original assets](/integration/connect-external-storage#save-a-copy-of-original-assets-on-demand) when using ImageKit for media delivery with your external storage, then the storage generated as a result of storing the original assets is billed against this parameter.

## Video Processing Units Pricing
Video processing units used depend on the output video codec, duration, and resolution. Every new video transformation or an optimized variant that has never been done before will contribute to video processing units using the below definition. Subsequent views of the same video transformation only count towards bandwidth. 

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`](/audio-transformations#extracting-audio) 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.
* **Video smart crop** - 1 additional VPU per second of output for each smart crop operation requested in the transformation, along with the standard VPU consumption. Refer to the examples given below to learn more.

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

| Resolution | Description                                                      |
| ---------- | ---------------------------------------------------------------- |
| SD         | Less than 921,600 total pixels, i.e., less than 1280 × 720.      |
| HD         | Greater than or equal to 1280 × 720 but less than 3840 × 2160.   |
| 4K         | Greater than or equal to 3840 × 2160 but less than 7680 × 4320.  |
| 8K         | Greater than or equal to 7680 × 4320 but less than 15360 × 8640. |
| 16K        | Greater than or equal to 15360 × 8640. |

### Examples of VPU consumption
- Automatic format optimization to WebM, VP9 codec and compression on a 30s Full HD video = 2 units x 30s = 60 units
- Using transformation `tr=w-300,h-300,f-webm` on a 15s full HD video = 1 unit x 15s = 15 units (1 unit is used per second as the output resolution is SD at 300 x 300 pixels)
- Using AV1 codec with WebM format using `tr=w-300,h-300,f-webm,vc-av1` on a 15s full HD video = 1 unit for SD x 10 units for AV1 x 15s = 150 units
- Using transformation `tr=w-1400,h-700` on a 20s SD video = 2 unit x 20s = 30 units (2 units are used per second as the output resolution is HD at 1400 x 700 pixels)
- If you use smart crop on the base video and on two video layers in the same transformation (`base.mp4?tr=fo-auto:l-video,i-overlay1.mp4,fo-auto,w-480,h-360,cm-extract,l-end:l-video,i-overlay2.mp4,fo-face,l-end`), and the output is 15s long, then the total VPU consumption will be 75 units. This includes 
    - Standard VPU consumption towards HD Encoding = 2 units x 15s = 30 units
    - Additional VPUs towards the smart crop operation = 3 smart crop parameters x 15s = 45 units.
- If you use ABS on a 60s, 16:9 HD video and create 4 representations using the transformation `tr=sr-360_480_720_1080`, then total video processing unit consumption is 390. This includes
    - Fixed 30 VPUs for Adaptive Bitrate Streaming transformation
    - 1 unit x 60s for 360p = 60 units
    - 1 unit x 60s for 480p = 60 units
    - 2 unit x 60s for 720p = 120 units
    - 2 unit x 60s for 1080p = 120 units

## Extension Units Pricing

The standard extension units consumption for AI-powered image generation, transformations, and auto description is as follows. We are constantly working to improve AI models and reduce the cost of these transformations. The units consumed may change over time.

Enterprise users may have a custom extension unit matrix available. This can be checked from the [subscriptions section](https://imagekit.io/dashboard/billing/subscriptions) of the ImageKit dashboard.

| AI Transformation                                      | Unit consumed |
| ------------------------------------------------------ | ------------- |
| Background removal (e-removedotbg)                     | 130           |
| ImageKit background removal (e-bgremove)               | 10            |
| Change background (e-changebg)                         | 60            |
| Edit Image (e-edit)                                    | 50            |
| Drop shadow (e-dropshadow)                             | 1             |
| Retouch (e-retouch)                                    | 5             |
| Upscale (e-upscale)                                    | 5             |
| Generative fill (bg-genfill)                           | 90            |
| Generate image via text prompt                         | 65            |
| Generate variation of an image (e-genvar)              | 25            |
| AWS auto-tagging (aws-auto-tagging extension)          | 1             |
| Google auto-tagging (google-auto-tagging extension)    | 2             |
| AI Auto Description (only for Media Library Assets)              | 1            |
| AI tasks (only for Media library assets)               | 4*            |
| AI transcription for Video Player (auto-generated subtitles and chapters) | 2 units/minute of video |
| Face crop (fo-face)                                    | Free          |
| Object aware cropping (fo-{object})                    | Free          |
| Smart crop (fo-auto)                                   | Free          |

{% callout style="info" %}
**AI Tasks Extension Units**: The consumption of 4 extension units applies per 5,000 LLM tokens used. The majority of AI tasks consume less than 5,000 tokens and therefore use just 4 extension units. For tasks that consume more tokens, the units scale proportionally—for example, if an AI task consumes 10,000 tokens, it uses 8 extension units, and so on.

**AI Transcription for Video Player**: AI transcription costs **2 extension units per minute** of source video duration. When you enable auto-generated subtitles or chapters for a video, both features are generated together automatically—you're billed once, not separately. Each language translation costs an additional **2 units per minute** for that language's subtitles and chapters.
{% /callout %}

## Free Plans and Limits
The free plans include some inclusions, as mentioned on the [Plans page](https://imagekit.io/plans), sufficient for small teams or low-traffic websites and apps. The plan offers these inclusions every month and is free forever.

On the first day of every calendar month, the usage of Bandwidth, Video Processing Units (VPUs), and Extension Units reset to 0. 

If you exceed the free plan inclusions in the middle of a month, the corresponding functionality will stop. You must upgrade to a paid plan to resume using the feature. 

## Paid Plans

The paid plans offer some inclusions for the above pricing parameters, as mentioned on the [Plans page](https://imagekit.io/plans) in the base pricing. Once you exceed those inclusions, pay-per-use pricing is defined for every component. 

If you are on a paid plan, you will be billed the minimum monthly fixed cost, irrespective of your monthly consumption. If the usage of some components exceeds the inclusions, you pay for the additional units you consume in that monthly billing cycle.

If your consumption falls within the free plan inclusions but you are on a paid plan, you must cancel your subscription to switch to the free plan to avoid getting billed.
 

## Common Billing examples
Please refer to the billing examples on our [pricing page](https://imagekit.io/plans) under the Frequently Asked Questions (FAQs) section.
 

## Custom Pricing Plans
If your requirement does not fit one of the paid plans we offer, or if your billing is significantly higher than the base pricing of the paid plan, or if you want to access any of the enterprise plan features, contact our [support team](mailto:support@imagekit.io) to discuss any custom pricing plans. 
 
Enterprise pricing plans can also include access to a dedicated customer success manager and integration support.


---

# Source: /usage-analytics

---
title: Usage Analytics
description: Learn how to access and understand usage analytics in ImageKit.io
---

ImageKit provides detailed usage analytics to help you understand how your account is being used. To access usage analytics, log in to your ImageKit dashboard and navigate to the [Usage Analytics](https://imagekit.io/dashboard/analytics/overall-usage) section.

{% callout style="info" %}
**Note** \
If you use [sub-accounts](/sub-accounts), the parent account can only show an overview of analytics, while detailed analytics are available in the sub-accounts.
{% /callout %}

The overall usage summary looks like this.

![Overall usage summary](https://ik.imagekit.io/ikmedia/docs_images/Usage%20Analytics/Overview_K5e9RUwvh8.png?tr=w-1600)

Let's explore different sections of usage analytics.

## Daily usage graphs for bandwidth, requests, VPUs, and extensions

Monitor bandwidth, requests, VPUs, and extensions with daily usage graphs. These are usually updated within a few hours of actual consumption.

![Daily usage trends](https://ik.imagekit.io/ikmedia/docs_images/Usage%20Analytics/Usage%20Trend_DuRyhIRAiF.png?tr=w-1600)

Within VPU, you can also see the split for different resolutions, such as `SD`, `HD`, `4K`, etc.

![VPU usage split](https://ik.imagekit.io/ikmedia/docs_images/Usage%20Analytics/vpu-split.png?tr=w-1600)

## Top assets by bandwidth and requests

Under [Media use analysis](https://imagekit.io/dashboard/analytics/media-usage), you can see the top assets by bandwidth and requests. We provide split for `images`, `videos`, and `other` assets based on the `Content-Type` response header.

This lets you determine which assets consume the most bandwidth and are requested frequently. For example, if you find a few large-sized GIFs consuming a lot of bandwidth, consider [converting them to videos](/vector-and-animated-images#gif-to-video) to save bandwidth. Or, for example, if you find a lot of high-resolution images, consider [resizing them correctly](/image-transformation).

![Media use analysis](https://ik.imagekit.io/ikmedia/docs_images/Usage%20Analytics/Media%20Use%20analysis_iTp2K0f7O.png?tr=w-1600)


## Error reports

Go to the [error reports](https://imagekit.io/dashboard/analytics/error-reports) section to see the errors received on your ImageKit URLs in the selected duration.

If you see a lot of 404 errors, look at the top URLs and the reasons to fix them in your application. Learn more about [troubleshooting 404 errors](/integration/connect-external-storage#troublshooting-404-errors).

{% linetabs %}

{% linetab title="Response status code distribution" %}

![Response status code distribution](<https://ik.imagekit.io/ikmedia/docs_images/Usage%20Analytics/Response%20status%20code%20distribution_yC6w6C8mo.png?tr=w-1600>)

{% /linetab %}

{% linetab title="404 error reasons" %}

![404 Errors](<https://ik.imagekit.io/ikmedia/docs_images/Usage%20Analytics/404%20ERROR%20REASONS_TAl-jInM8.png?tr=w-1600>)

{% /linetab %}

{% linetab title="Top URLs with 404 errors" %}

![Top 404 URls](<https://ik.imagekit.io/ikmedia/docs_images/Usage%20Analytics/Top%20404%20errors_mngdYBLob.png?tr=w-1600>)

{% /linetab %}

{% /linetabs %}


## Top image and video transformations

This section summarizes the top transformations applied to images and videos. Ideally, for high performance, a few transformations should account for most of the request volume. 

If you see too many transformations here, each with a very low percentage usage and a [low cache hit ratio](#cache-hit-statistics) on the CDN, consider consolidating your transformations to a smaller number. 

If you suspect a transformation is incorrect or should not have been used, first check your code for it. If still an issue, consider using [named transformation](/transformations#named-transformations) and [restricting un-named transformations](/media-delivery-basic-security#restrict-unnamed-transformations) for more control on the transformations that can be applied to your media assets.

{% linetabs %}

{% linetab title="Top image transformations" %}

![Top image transformations](https://ik.imagekit.io/ikmedia/docs_images/Usage%20Analytics/Top%20Image%20Transformations_nSKNjs_BP.png?tr=w-1600)

{% /linetab %}

{% linetab title="Top video transformations" %}
![Top video transformations](https://ik.imagekit.io/ikmedia/docs_images/Usage%20Analytics/Top%20Video%20Transformations_kQKvno0Obu.png?tr=w-1600)

{% /linetab %}

{% /linetabs %}

## Cache hit statistics

This section provides information about cache hit statistics. It shows the number of cache hits, misses, and error requests on the CDN integrated in ImageKit.

A cache hit percentage above 90% is considered excellent, while above 80% is good. A lower cache hit ratio means the cache is not utilized effectively. This is usually the case if you are using a lot of unique URL transformations, signed URLs with expiry, or the cache is being bypassed due to random query parameters containing a timestamp or a unique identifier.

![Cache hit statistics](https://ik.imagekit.io/ikmedia/docs_images/Usage%20Analytics/Cache%20hit__jRdfG8O3.png?tr=w-1600)

## Top usage by countries, devices, browsers, and referrers

This section helps you identify the top usage by countries, browsers, output formats, devices, user agents, referrers, and IP addresses. Looking at anomalies here can help identify, optimize, and fix high usage on ImageKit.

![](https://ik.imagekit.io/ikmedia/docs_images/Usage%20Analytics/Top%20Usage_WKcgg0fU5.png?tr=w-1600)

* **By countries**: determined from the country of CDN edge used to serve content and may not match the  country of your user  
* **By browsers**: Determined from the User-Agent string value in the request header.
* **By formats**: Determined from the value of the HTTP Content-Type header of the response.
* **By devices**: Determined from the value of the User-Agent string in the request header
* **By user agents**: Determined from the value of the User-Agent header in the request header.
* **By referer**: Determined from the Referer header in the request headers.
* **By IP addresses**: Determined by the IP address of the incoming request.

If you observe hotlinking or unauthorized usage, you can use the [advanced security](/media-delivery-advanced-waf) features to block specific IPs, referrers, or user agents.

Suppose you observe significantly high usage for a single format like JPEG or PNG. In that case, the images are not optimized to a modern format, like WebP or AVIF. Consider checking the [image](/image-optimization) and [video optimizations](./video-optimization) and ensuring they work across all websites and apps.


---

# Source: /sub-accounts

---
title: Sub-accounts
description: Learn how to use a parent account to create and manage multiple sub-accounts in ImageKit.io
---

{% callout style="info" %}
**Enterprise Plans only**\
This feature is available only on custom enterprise pricing plans or to ImageKit partners.
{% /callout %}

ImageKit allows the creation of multiple child sub-accounts, enabling you to manage multiple websites, brands, or environments under one parent account. 

A parent account is a special kind of ImageKit account that can only be used for creating and managing sub-accounts and handling their billing, not for media delivery or management. You cannot directly sign up for a parent account, and only ImageKit's team can convert an existing account into one.

Under a parent account, each sub-account is like a new, regular ImageKit account operating independently with its own configuration, settings, API keys, etc. As covered here, billing for sub-accounts can be handled in two ways.

## Benefits of using sub-accounts

* **Segregating media delivery and management across multiple clients**: If you are an agency or an ImageKit partner, organize and secure each client's assets and configuration in separate sub-accounts. This ensures data privacy and enables tailored analytics, optimization strategies, billing, and access control.

* **Brand and Product Line Isolation**: Use dedicated sub-accounts to isolate assets for different brands or product lines, facilitating brand-level analytics, billing, access control, and media processing strategies.

* **Environment Segregation and testing**: Create sub-accounts for different development, staging, and production environments to simplify development and new feature adoption in lower environments before rolling out changes in production.

* **Segregate Billing and Analytics**: Independently access usage and billing for each sub-account to optimize costs and resource utilization.

## Billing Models

ImageKit offers two billing models for sub-accounts. Both the models can be used in parallel.

1. **Bill to Parent**: The parent account is responsible for all charges incurred by the sub-accounts. This model suits organizations that want to manage billing centrally and have a single payment method for all sub-accounts. In this mode, one invoice is generated against the parent account, combining usage from all sub-accounts set to Bill to Parent. The sub-accounts don't see the pricing plan or billing details in their dashboard.

2. **Bill to Sub-account**: In this model, the sub-account is billed independently, and the parent account is not responsible for the charges incurred. This model is suitable for cases where the customer using the sub-account wants to manage their own billing and negotiate their own pricing directly with ImageKit. In this mode, the child accounts are billed separately, and each has its own invoice.

## Create a child sub-account

To create a child sub-account, go to the [Manage Account](https://imagekit.io/dashboard/manage-accounts) section and click on the "Add Account" button.

During account creation, you can choose [ImageKit ID and Processing Region](/account-management#imagekit-id-and-processing-region) and the [billing model](#billing-models) for the sub-account.

![Add new child sub-account](https://ik.imagekit.io/ikmedia/docs_images/Usage%20Analytics/add-sub-account.png?tr=w-1600)

## Overall Usage Analytics

You can also see the high-level usage by each sub-account in the parent account. For detailed [usage analytics](/usage-analytics), you must have access to the sub-account with a suitable role and log in to the sub-account.

![Usage analytics](https://ik.imagekit.io/ikmedia/docs_images/Usage%20Analytics/overall-analytics.png?tr=w-1600)