Getting started

Integration & migration

Image & video API

DAM user guide

API overview


Connect external storage 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 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 acts as a proxy between the CDN and your storage. This means that when a request is made to for any file, 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:

Your media files remain securely stored in your storage system. 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.

Supported external storage

ImageKit works with a variety of external storage types. You can connect any of the following types of external storage with

URL Endpoints

URL endpoints are unique access points that allow you to retrieve your media files through When you create an account, a default URL endpoint is automatically generated:

Default URL endpoint:

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 in your 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:

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.

Origin preference

When you attach multiple origins to a single URL endpoint, you can set the order in which will attempt to fetch the resource from these origins.

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 and optionally associate it with only a specific URL endpoint. Contact for domain and URL endpoint mapping.

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.

Error CodeDescription
ENOENTIt 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.
EACCESInvalid 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 has the necessary permission to access the file. In the case of web server origin, you should check firewall settings and whitelist our servers. In the case of object storage, you should ensure that the configured credential has read access.
ELIMITRefer to transformation limits to understand more about the reason for the error. The response status is 400 in this case.
ECONNREFUSEDThe 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.
UNIDENTIFIEDThe exact nature of the error could not be identified. This is rare, in this case, contact us at

Whitelist requests from

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.

Note that these IP addresses may change in the future. Any changes will be reflected and updated in this document.


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 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 to create a secure tunnel to your local machine. You can then use the ngrok URL as the origin URL in 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 as the origin URL in

Debugging slow origin response

ImageKit returns a standard 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.

  • 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 and the geographical location of your origin. The longer the physical distance between the two, the longer the download time. has six processing regions: North California (United States), North Virginia (United States), Frankfurt (Europe), Mumbai (India), Singapore (Singapore), and Sydney (Australia). To change your processing region, you can speak to our support team. 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 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, 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.