NAV
ImageKit.io logo
cURL NodeJS Python Java PHP

Getting Started

As soon as you sign up with ImageKit, a default image, named default-image.jpg, is added to your ImageKit Media Library which can be accessed using the URL given in the code sample. 

  https://ik.imagekit.io/your_imagekitId/default-image.jpg

Welcome to ImageKit! Get familiar with the available image transformations, upload, and admin APIs. Use SDKs and plugins for easier integration.

After creating an account, integrating ImageKit into your app or website requires only three steps:

  1. Configure the origin in ImageKit dashboad. You can follow a quick step by step integration guide based on your platform. If you want to use ImageKit Media library for storing images, upload images directly using upload API or from the dashboard.
  2. Try out resizing and cropping on existing or newly uploaded images. Your images will be accessible on https://ik.imagekit.io/your_imagekitId/rest-of-the-path.jpg
  3. After testing is complete, start using ImageKit URL endpoints in production to accelerate image loading. You can also use custom domain (CNAME) instead of https://ik.imagekit.io/your_imagekitId.

ImageKit URL structure

Here is how a typical ImageKit URL will look like:

{URL_endpoint}/{transformation_string}/{rest_of_the_image_path_including_extension}

For example https://ik.imagekit.io/demo/tr:w-100/default-image.jpg

When using custom domain (CNAME), replace URL endpoint with the configured CNAME.
For example replace https://ik.imagekit.io/{your_imagekitId}/{url_pattern} with images.yourdomain.com. Learn more

Image Transformations

There are several image transformations available in ImageKit, and new ones are being added regularly. Here is the list of all image transformations:

Commonly used

Parameter
w
width
 Used to specify the width of the output image. Accepts integer value greater than 1 and if a value between 0 and 1 is specified, then it acts as a percentage width. For eg, 0.1 means 10% of the original width, 0.2 means 20% of the original width.
h
height
 Used to specify the height of the output image. Accepts integer value greater than 1 and if a value between 0 and 1 is specified, then it acts as a percentage height. For eg, 0.1 means 10% of the original height, 0.2 means 20% of the original height.
ar
aspect ratio
 Used to specify the aspect ratio of the output image or the ratio of width to height of the output image. This transform must be used along with either the height or the width transform. The format of specifying this transformation is ar-<width>-<height>
c
crop
 This option decides the final value of height and width of the output image based on the aspect ratio of the input image and the requested transform. Possible values include maintain_ratio, force, at_least and at_max.
Default value - maintain_ratio
Learn about crop, crop modes and focus using examples
cm
crop mode
 The crop mode option is used to specify the strategy of how the input image is used for cropping to get the output image. Possible values include resize, extract, pad_extract and pad_resize.
Default value - resize
Learn about crop, crop modes and focus using examples
fo
focus
 This option is coupled with the extract type of crop mode (crop mode is not needed if you are using auto focus) to get the area of the input image that should be focussed on to get the output image. Possible values include center, top, left, bottom, right, top_left, top_right, bottom_left, bottom_right and auto.
Default value - center
Learn about crop, crop modes and focus using examples
q
quality
 This option specifies the output quality of the lossy formats like JPG and WebP. A higher quality number means a larger size of the output image with high quality. A smaller number means low quality image at a smaller size.
Default value is picked from the dashboard settings. It is set to 80
Learn about image quality optimization, subsampling and data-saver mode support
f
format
 This option specifies the format of the output image. If no output format is specified and the “Dynamic image format selection” option is selected in your dashboard settings, then the output format is decided on the basis of the user’s device capabilities and input image format. If dynamic image format selction is switched off, and no output format is specified then the format of the output image is same as that of the input image. Possible values include auto, webp, jpg, jpeg and pnt.
Default value - auto
Learn about automatic format optimization
bl
blur
 This option specifies the Gaussian blur that has to be applied to the image. The value of blur decides the radius of the Gaussian blur that is applied. Higher the value, higher is the radius of Gaussian blur. Possible values include integers from 1 to 100
Learn more from examples
e-grayscale
grayscale
 Turn an image into its grayscale version.
Learn more
dpr
dpr
 This option specifies the device pixel ratio to be used to calculate the dimension of the output image. It is useful when creating image transformations for devices with high density screens (DPR greater than 1) like the iPhone.
The DPR option works only when either the height or the width or both are specified for resizing the image
If the resulting height or width after considering the specified DPR value is less than 1px or more than 5000px then the value of DPR is not considered and the normal height or width specified in the transformation string is used.
Possible values: 0.1 to 5.0
n
named transformations
 Named transformations is an alias for the entire transformation string.
e.g we can create a named transform media_library_thumbnail for transformation string tr:w-150,h-150,f-center,c-at_max and use it like this https://ik.imagekit.io/demo/img/tr:n-media_library_thumbnail/default-image.jpg
Learn how to use named transformations
di
default image
 If the image that is requested using ImageKit does not exist, then a 404 error is shown. However, there might be a need where instead of giving a broken image to the user, you want a default image to be delivered. ImageKit provides a way to do this without having to handle this at application level.
Learn how to serve a default placeholder image in case original image is not found on origin.
pr
progressive JPEG
 This option specifies if the output JPEG image should be rendered progressively. In progressive rendering, the client instead of downloading the image row-wise (baseline loading), renders a low-quality pixelated full image and then gradually keeps on adding more pixels and information to the image. It gives faster-perceived load times. Possible values include true and false.
Default value - false
Learn more
lo
Lossless WebP and PNG
 This option specifies if the output image (if in PNG or WebP format) should be compressed losslessly. In lossless compression, the output file size would be larger than the regular lossy compression but at the same time, the perceived quality can be better in certain cases, especially for computer generated graphics. Using lossless compression is not recommended for photographs. Possible values include true and false.
Default value - false
Learn more
t
trim edges
 This transformation is useful for images that have a solid / nearly-solid background and the object in the center. This transformation will trim the background from the edges, leaving only the central object in the picture. Possible values include true or an integer from 1 to 99
Learn more from examples

Overlay

Parameter
oi
overlay image
 This is used to overlay one image over another image. This will help you generate watermarked images if needed.
Learn how to control the overlay position and size
ofo
overlay focus
 Specifies the positon of the overlaid image relative to the input image. Possible values include center, top, left, bottom, right, top_left, top_right, bottom_left and bottom_right.
Default value - center
Learn more from examples
ox
overlay X position
 This option provides more granular control over the positioning of the overlay image on the input image. The top left corner of the input image is considered as (0,0) and the bottom right corner is considered as (w, h) where w is the width and h is the height of the input image. If ox is 100 then the overlay image is placed 100px from the left edge of the input image. If ox value exceeds the width or height of the input image, then the values are adjusted and made equal to the corresponding dimension of the input image.
We also have support for negative values as well. Negative values are supported with a leading capital N in front of the value provided. The value provided is subtracted from the original dimension of the image & positioned accordingly.
Possible values include any integer.
Learn how to control the overlay position and size
oy
overlay Y position
 This option provides more granular control over the positioning of the overlay image on the input image. The top left corner of the input image is considered as (0,0) and the bottom right corner is considered as (w, h) where w is the width and h is the height of the input image. If oy is 150 then the overlay image is placed 150px from the top edge of the input image. If oy value exceeds the width or height of the input image, then the values are adjusted and made equal to the corresponding dimension of the input image.
We also have support for negative values as well. Negative values are supported with a leading capital N in front of the value provided. The value provided is subtracted from the original dimension of the image & positioned accordingly.
Possible values include any integer.
Learn how to control the overlay position and size
oh
overlay height
 Specifies the height of the overlaid image.
Learn how to control the overlay position and size
ow
overlay width
 Specifies the width of the overlaid image.
Learn how to control the overlay position and size
ot
overlay text
 This is used to overlay text over an image. Our current support is limited to alphanumberic & special characters _ & - only.
Learn how to control the font, font size, weight, color and position of text
Learn advanced concepts from examples
otc
overlay text color
 Species the color of the overlaid text on the image. Possible value is a valid valid RGB Hex Code
Learn more from examples
otf
overlay text font
 Specifies the font family for the overlaid text. Currently we only support these fonts.
Learn more from examples
ots
overlay text size
 Specifies the size of the overlaid text. Possible values include any integer.
Default value - 14px
Learn more from examples
ott
overlay text typography
 Specifies the typography of the font family used for the overlaid text. Possible values include bold b and italics i.
Note Bold & Italics are not supported for all provided fonts, kindly refer to font list
Learn more from examples
oa
overlay transparency
 Specifies the transperancy level for the overlaid image. Possible values include integer from 1 to 9.
Note Overlay transparency is currently supported for overlay texts & backgrounds only.
Learn more from examples
obg
overlay background
 Specifies the colour of background canvas to be overlaid. Possible values include a valid RGB Hex code.
NoteOverlay transparency is currently supported for overlay texts & backgrounds only.
Learn how to create marketing banners

Others

Parameter
cp
color profile
 This option specifies if the output image should contain the color profile that is initially available from the original image. It is recommended to remove the color profile before serving the image on web and apps. However, in cases where you feel that the image looks faded or washed-out after using ImageKit and want to preserve the colors in your image, then you should set this option to true. Possible values include true and false.
Default value - false
Learn about preserving color profile
md
image metadata
 This option specifies if the output image should contain all the metadata that is initially available from the original image. Enabling this is not recommended because this metadata is not relevant for rendering on the web and mobile apps. The only reason where you should enable the metadata option is when you have knowingly wanted the additional data like camera information, lens information and other image profiles attached to your image. Possible values include true and false.
Default value - false
Learn about metadata, color profile and auto-orientation optimizations
rt
rotate
 This option specifies the degrees by which the output image has to be rotated or specifies the use of EXIF Orientation tag for the rotation of the image using auto. Possible values include 0, 90, 180, 270, 360 and auto.
Learn about auto-orientation
r
radius
 This option specifies the radius to be used to get a rounded corner image. If you want a perfectly rounded image, set the value as max. This option is applied after resizing of the image, if any. Possible values include positive integer or max.
Learn how to create rounded profile thumbnails
bg
background color
 This option specifies the background color as RGB hex code (e.g. FF0000) or an RGBA code (e.g. FFAABB50) to be used for the image. If you specify an 8-character background, the last two characters should be numbers from 00 to 99 which indicate the opacity level of the background. 00 corresponds to an opacity of 0.00, 01 corresponds to an opacity of 0.01 and so on. Possible values include a valid RGB hex code
Default value - Black 000000
Learn various use-cases from example
b
border
 This option specifies the width and color of the border that is added around the image. The width is a positive integer that specifies the border width in pixels. The border color is specified as a standard RGB hex code e.g b-<width>_<color>
Learn more from examples

Image enhancement

Parameter
e-contrast
contrast stretch
 This option will automatically enhance the contrast of the image by using the full range of intensity values that a particular image format allows. This basically means that the lighter portions of the image would become even lighter and the darker portions of the image would become even brighter, thereby enhancing the contrast.
Learn more
e-sharpen
sharpen
 Sharpens the input image. It is useful to highlight the edges and finer details in the image. If just e-sharpen is used, then a default sharpening is performed on the image. This behavior can be controlled by specifying a number that controls the extent of sharpening performed - higher the number, more the sharpening like this e-sharpen-<number>
Learn more
e-usm
unsharp mask
 Unsharp masking (USM) is an image sharpening technique. This transform allows you to apply and control unsharp mask on your images. The amount of sharpening can be controlled by varying the 4 parameters - radius, sigma, amount and threshold. This results in perceptually better images compared to just e-sharpen. Only positive floating point values are allowed for these 4 parameters.
Learn more

Chained Transformations

Some transforms are dependent on the sequence in which they are carried out. For example, if we have a transformation that requires the input image to be resized from 800x600 to 400x300 and rotated by 90 degrees. The transformation string for this will be tr:w-400,h-300,rt-90

Here are two possible scenarios for this-

  1. Rotation takes place before resize - The 800x600 image is rotated by 90 degrees to get 600x800 image. Then a 400x300 image is obtained from it. The resulting image would be a 400x300 image with some portion of the original image missing (if the aspect ratio of the 600x800 image is to be maintained).

  2. Resize takes place before rotation - The 800x600 image is first resized to 400x300 (half it’s size) and then rotated by 90 degrees. The resulting image would be a 300x400 image with all the contents of the original image still present (though rotated by 90 degrees). This is also the default behavior of ImageKit.

Since it is easy to confuse the two cases while implementation and there can be more confusing cases when it comes to the sequence of application of transforms, ImageKit provides an easy way to get the exact image predictably with chained transformations. In chained transformations, you can specify the exact sequence in which the transformations are to be applied. Each step of the transformation chain is separated from the other by “:”.

In the above example, rotate and resize can be considered as two steps of the transformation chain.

Resize step: w-400,h-300
Rotate step: rt-90

These two can be combined in a transformation chain to get a predictable image as per the requirement.

Rotate before resize: tr:rt-90:w-400,h-300
Resize before rotate: tr:w-400,h-300:rt-90

As can be seen from the chained transformation strings above, the transformation steps are separated by a “:”. Also, the transformation string is now more expressive about the transformation that will be carried out. Like this, you can add other sequence dependent steps in a transform chain to obtain predictable results.

Supported text font list

We currently support a limited number of font families

Font Family Support for Bold Support for Italics
AbrilFatFace No No
Amarnath Yes Yes
Arvo Yes Yes
Audiowide No No
Chivo Yes Yes
CrimsonText Yes Yes
exo Yes Yes
FredokaOne No No
GravitasOne No No
Kanit Yes Yes
Lato Yes Yes
Lobster No No
Lora Yes Yes
Monoton No No
Montserrat Yes Yes
PT Mono No No
PT_Serif Yes Yes
OpenSans Yes Yes
Roboto Yes Yes
stagOldStandard Yes Yes
Ubuntu Yes Yes
Vollkorn Yes Yes

Optimisations

ImageKit offers below optimisations out of the box. The optimisations are done to reduce the size of the final output image. This greatly improves the loading performance of your images while preserving an acceptable image quality.

  1. Removing Metadata
  2. Quality Optimisation
  3. Format Optimisation
  4. PNG Image Optimisation

Learn more to understand and modify default optimization settings in ImageKit.

Chroma Subsampling

Chroma Subsampling is an optimisation technique that is used for encoding of JPEG images. This technique takes advantage of the lower sensitivity of the human visual system towards color (chroma) than towards brightness (luma). It is generally recommended to use 4:2:0 chroma subsampling on all images. But in certain cases, especially the ones with a very bright object in the foreground over a completely white background, it introduces unwanted image artifacts.

Because the quality of the image is our utmost priority, the setting “Use chroma subsampling 4:2:0” is kept “off” by default. This means that we do not use chroma subsampling on the image by default. However, if your images look fine with this setting turned “on”, then you can use it on all your images without worrying and enjoy even better compression ratios on your images.

Security and Restrictions

Certain options are provided in your ImageKit account to secure your images and restrict the transformations that can be done on them. Implementing these securities and restrictions would not only help prevent unauthorized use of your image URLs by random third-parties but would also make your code look cleaner.

Signed URLs

When generating image URLs from your server, you can use your Private Key (available in the Settings section of your dashboard) to sign the image URL. The signing adds additional query parameters to your image which ensure that the URL and the image transformation cannot be altered from the URL. The signature can even be used to set a predefined expiry time of the URL.

Since your private key is only known to you and image signatures are one-way hashes, it is not possible for a third-party to be able to generate the exact same signature for a request even if they get access to one of your URLs. If the third party tries to modify the image transformation or the image URL or use it beyond its intended expiry time, the request would return a 401 Unauthorised status code because of a signature mismatch.

By default, this setting, “Only allow signed URLs”, is kept turned off in the settings dashboard as this requires you to implement the signing logic on your servers. If this setting is enabled, then no image without a valid signature attached to it as a query parameter would be accessible. If this setting is kept off, then all image URLs would be accessible no matter when or how they were generated. If you are using unsigned images now, and want to move to a completely secure signed image request system, then you would need to migrate the existing image URLs as well to start using a signature.

Your private key is used for creating signatures. It is important that signature generation logic is kept on your servers and your private key is not disclosed to anyone.

Generating signed URLs

You can use one of our SDKs to generate a signed image URL. The process of generating a signed URL using the SDK is available in the respective SDK’s documentation.

If you want to implement the signature and URL generation logic on your own, then follow these steps:

  1. Append the following in a string
    a. ImageKit ID
    b. The complete transformation string without the tr: in the beginning.
    If you use tr:h-100,w-100:rt-90 in the URL, then to calculate the signature use h-100,w-100:rt-90.
    c. The UTC timestamp in seconds for the expiry time of the URL (if you do not want to expire the URL, set this to 9999999999)
    d. Image Key which is the image URL without the URL pattern and transformation string. It should include all query parameters as well except for the signature related query params i.e. ik-s and ik-t (covered in the next point)
    If your URL is https://ik.imagekit.io/demo/tr:h-100,w-100:rt-90/files/image.jpg?version=1 then the image key is files/image.jpg?version=1.

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

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

  4. If you used a timestamp (other than the default 9999999999) to set the expiry time while calculating the hash, attach it to the URL as a query parameter named ik-t.

If the signature is incorrect and the setting “Only allow signed URLs” is checked in your dashboard, then you will get 401 Unauthorised error in the response. Only when the signature is correct, and the URL has not expired (if you set an expiry time in the hash), will the image will be delivered.

If the setting “Only allow signed URLs” is unchecked in your dashboard, then it doesn’t matter whether the URL is signed or not. If the image exists, it will be delivered.

Restricting Unnamed Transformations

Named transformations and their utility has been explained in the Named Transformations section above.

There is a setting “Only allow named transformations” in the settings section of your dashboard. If this setting is enabled, then using unnamed transformations like height, width etc. won’t work in any combination. If the setting is enabled and any of the requested transformations is unnamed, then the URL would return 400 Bad Request response. All the transformations, even in chained transformations, must be named.

Restricting the use of transformations not only makes it easier for the developers to remember the transformations that can be used, it also prevents any unauthorized third-party from applying random transformations on your images.

Uploads

At this stage, only JPG, PNG, WebP and GIF images can be uploaded to ImageKit.

Uploading from dashboard

In the media library section of your dashboard, click on the Upload Images button. You can either choose files using the normal file select dialog box or drag and drop images anywhere on the dashboard to initiate an upload. Once the upload completes, you can copy the image URL to access the image.

Server-side image upload

ImageKit has developed several SDKs to ease the upload integrations. You can check the available SDKs here. If you do not want to use an SDK or could not find a relevant SDK, then you can integrate the upload API directly in your application.

Generating signature for the upload

Each upload request must be signed before uploading. The signature is a mandatory parameter in the upload request. To calculate the signature.

  1. The parameters filename, timestamp and apiKey (your public key) that have to be sent in the image upload request have to be included in the signature.

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

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

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

  5. Example - If the filename is my-image.jpg, timestamp is 123456789 and apiKey is myapikey, then the string to be used for signature will be apiKey=myapikey&filename=my-image.jpg&timestamp=123456789.

  6. Using your private key as the key, calculate a hexadecimal HMAC-SHA1 digest of this serialized string.

Never expose your private key on the client-side. All signature generation should take place on the server.

Server-side image upload, using public key:

curl -X POST
     -F "filename=my_image"
     -F "useUniqueFilename=true"
     -F "file=@/path/to/image.jpg"
     -F "folder=/files/"
     -F "signature=generatedsignaturefromyourcode"
     -F "apiKey=mypublickey"
     -F "timestamp=1475592319" 
     "https://upload.imagekit.io/rest/api/image/v2/myimagekitid"

Fill in with actual imagekitId, file and timestamp.

Output for successful upload:

{
  "imagePath": "images/my_image_BJyuWdf0.jpg",
  "size": 51198,
  "height": 300,
  "width": 444
}

HTTP Request

POST https://upload.imagekit.io/rest/api/image/v2/<imagekitId>
Content-Type : multipart/form-data

The API endpoint /rest/api/image/ used the parameter ‘image’ for the input file. Given the introduction of non-image file uploads, this old API endpoint will be deprecated in favor of the new /rest/api/image/v2/ endpoint that uses 'file’ parameter for the input file

Path Parameters

Parameter Required Description
imagekitId Yes The ImageKit Id associated with your account

Form Parameters

Parameter Required Description
file Yes The base64 encoded image that has to be uploaded
filename Yes The name with which the file has to be uploaded
apiKey Yes Your public API key
signature Yes HMAC-SHA1 signature generated for the file upload
timestamp Yes UTC timestamp in seconds. The request will be valid for 30 minutes from this timestamp.
useUniqueFilename No “true” or “false”. If set to true, ImageKit will add a unique code to the filename parameter to get a unique filename. If false, the image is uploaded with the filename parameter as name. If an image exists with the same name, this new image will override it. Default is “true”
folder No The folder path (eg- /images/folder/) in which the image has to be uploaded. Default is “/”

Response Codes

HTTP Status Status Number (Status Code) Description
400 1400 (BAD_REQUEST) Invalid or missing form parameters in the request or file too large
403 1403 (ACCESS_FORBIDDEN) Invalid signature or expired request
404 1404 (UNMAPPED_REQUEST) Invalid ImageKit Id
500 1500 (SERVER_ERROR) Internal server error while uploading the file

Server-side file upload

Since it is not an ideal scneario to manage multiple CDN partners for different set of resources on a single app, ImageKit now allows PDF, JS, CSS and TXT file upload to it’s media library.

Generating signature for the upload

The process of generating a signature for a file upload remains the same as that explained for image upload in the section above. Use the file’s name instead of the PDF name

Never expose your private key on the client-side. All signature generation should take place on the server.

Server-side file upload, using public key:

curl -X POST
     -F "filename=my_file"
     -F "useUniqueFilename=true"
     -F "file=@/path/to/file.pdf;type=application/pdf"
     -F "folder=/files/"
     -F "signature=generatedsignaturefromyourcode"
     -F "apiKey=mypublickey"
     -F "timestamp=1475592319" 
     "https://upload.imagekit.io/rest/api/static/v2/myimagekitid"

Fill in with actual imagekitId, file and timestamp.

Output for successful upload:

{
  "imagePath": "files/my_file_BJyuWdf0.jpg",
  "size": 51198
}

HTTP Request

POST https://upload.imagekit.io/rest/api/static/v2/<imagekitId>
Content-Type : multipart/form-data

Path Parameters

Parameter Required Description
imagekitId Yes The ImageKit Id associated with your account

Form Parameters

Parameter Required Description
file Yes The base64 encoded file that has to be uploaded
filename Yes The name with which the file has to be uploaded
apiKey Yes Your public API key
signature Yes HMAC-SHA1 signature generated for the file upload
timestamp Yes UTC timestamp in seconds. The request will be valid for 30 minutes from this timestamp.
useUniqueFilename No “true” or “false”. If set to true, ImageKit will add a unique code to the filename parameter to get a unique filename. If false, the file is uploaded with the filename parameter as name. If a file exists with the same name, this new file will override it. Default is “true”
folder No The folder path (eg- /files/folder/) in which the file has to be uploaded. Default is “/”

Response Codes

HTTP Status Status Number (Status Code) Description
400 1400 (BAD_REQUEST) Invalid or missing form parameters in the request or file too large
403 1403 (ACCESS_FORBIDDEN) Invalid signature or expired request
404 1404 (UNMAPPED_REQUEST) Invalid ImageKit Id
500 1500 (SERVER_ERROR) Internal server error while uploading the file

 

Server-side Upload via URL (Beta)

As a method of convenience, ImageKit allows you to upload images and PDF, JS, CSS and TXT files to the ImageKit Media Library from a remote HTTP(S) accessible URL. The image or the file is downloaded from the URL provided and uploaded to the Media Library.

Generating signature for the upload

The process of generating a signature for a file upload via URL remains the same as that explained for image upload in the section above. Use the API Key, Filename and Timestamp to generate the signature using your secret key.

Never expose your private key on the client-side. All signature generation should take place on the server.

Server-side upload via URL with public key

    curl -X POST 
         -H "Content-Type: application/x-www-form-urlencoded" 
         -d 'url=https://example.com/path/to/my/image.jpg&filename=abc.pdf&useUniqueFilename=true&folder=/images/&apiKey=myapikey&signature=mysignature&timestamp=1510829509'
    "https://upload.imagekit.io/rest/api/url/v2/myimagekitid"

Fill in with actual imagekitId, url, filename and timestamp.

Output for successful upload:

{
  "imagePath": "files/my_file_BJyuWdf0.jpg",
  "size": 51198
}

HTTP Request

POST https://upload.imagekit.io/rest/api/url/v2/<imagekitId>
Content-Type : application/x-www-form-urlencoded

Path Parameters

Parameter Required Description
imagekitId Yes The ImageKit Id associated with your account

Form Parameters

Parameter Required Description
url Yes The HTTP(S) accessible URL for the file that has to be uploaded. The protocol http:// or https:// also needs to be included.
filename Yes The name with which the file has to be uploaded
apiKey Yes Your public API key
signature Yes HMAC-SHA1 signature generated for the file upload
timestamp Yes UTC timestamp in seconds. The request will be valid for 30 minutes from this timestamp.
useUniqueFilename No “true” or “false”. If set to true, ImageKit will add a unique code to the filename parameter to get a unique filename. If false, the file is uploaded with the filename parameter as name. If a file exists with the same name, this new file will override it. Default is “true”
folder No The folder path (eg- /files/folder/) in which the file has to be uploaded. Default is “/”

Response Codes

HTTP Status Status Number (Status Code) Description
400 1400 (BAD_REQUEST) Invalid or missing form parameters in the request or file not downloadable
403 1403 (ACCESS_FORBIDDEN) Invalid signature or expired request
404 1404 (UNMAPPED_REQUEST) Invalid ImageKit Id
500 1500 (SERVER_ERROR) Internal server error while uploading the file

 

Admin API

Purging

You can purge single image URL using this API endpoint.

Generating signature for the purge request

Each purge request must be signed. The signature is a mandatory parameter in the request. To calculate the signature.

  1. The parameters url, imagekitId that have to be sent in the image purge request have to be included in the signature.

  2. Sort the parameters in the alphabetical order of the keys i.e. imagekitId comes before url.

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

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

  5. Example - If the url is https://ik.imagekit.io/yourimagekitID/example-image.jpeg, imagekitId is yourimagekitID, then the string to be used for signature will be imagekitId=yourimagekitID&url=https://ik.imagekit.io/yourimagekitID/example-image.jpeg.

  6. Using your private key as the key, calculate a hexadecimal HMAC-SHA1 digest of this serialized string.

Never expose your private key on the client-side. All signature generation should take place on the server.

Purge API usage:

curl -X POST \
  https://imagekit.io/api/admin/purge \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'signature=your_generated_signature&url=https://ik.imagekit.io/your_imagekitId/path-of-the-image-your-want-to-purge.jpg&imagekitId=your_imagekitId'

// Using ImageKit npm package
var ImageKit = require("imagekit");

var imagekit = new ImageKit({
   "imagekitId" : "your_imagekitId",       
   "apiKey" : "your_apiKey",
   "apiSecret" : "your_apiSecret", 
});
var purgePromise = imagekit.purgeFile("https://ik.imagekit.io/your_imagekitId/path-of-the-image-your-want-to-purge.jpg");  

purgePromise.then(function(resp) {
  //handle purge success here    
}, function(err) {
  //handle purge failure here
});

import requests

url = "https://imagekit.io/api/admin/purge"

payload = "signature=your_generated_signature&url=https://ik.imagekit.io/your_imagekitId/path-of-the-image-your-want-to-purge.jpg&imagekitId=your_imagekitId"
headers = {
    'Content-Type': "application/x-www-form-urlencoded"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

// Using Unirest
HttpResponse<String> response = Unirest.post("https://imagekit.io/api/admin/purge")
  .header("Content-Type", "application/x-www-form-urlencoded")
  .body("signature=your_generated_signature&url=https://ik.imagekit.io/your_imagekitId/path-of-the-image-your-want-to-purge.jpg&imagekitId=your_imagekitId")
  .asString();

<?php
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://imagekit.io/api/admin/purge",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "signature=your_generated_signature&url=https://ik.imagekit.io/your_imagekitId/path-of-the-image-your-want-to-purge.jpg&imagekitId=your_imagekitId",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/x-www-form-urlencoded"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
?>

Output for successful purge request:

{
  "requestId": "RequestID which you can use to get status of purge request"
}

HTTP Request

POST https://imagekit.io/api/admin/purge
Content-Type : application/x-www-form-urlencoded

Parameters

Parameter Required Description
url Yes The URL which needs to be purged from ImageKit and CDN
imagekitId Yes ImageKit ID associated with your account
signature Yes HMAC-SHA1 signature generated for the this request

Response Codes

HTTP Status Status Number (Status Code) Description
400 1400 (BAD_REQUEST) Invalid or missing form parameters in the request
403 1403 (ACCESS_FORBIDDEN) Invalid signature
404 1404 (UNMAPPED_REQUEST) Invalid ImageKit Id
500 1500 (SERVER_ERROR) Internal server error while purging the file

Purge status

To get the status of purge request, use the requestId returned in the response of purge API:

GET https://imagekit.io/api/admin/purge/status/<requestID>

Rate limits on purging API

You can clear 1000 URL caches in a month from a single account (from both dashboard and the Purge API combined). After you reach this limit, cache clear requests will start getting blocked in your account. If you need more cache clear requests per month, please get in touch with us by creating a support ticket from your dashboard.

Apart from above, we enforce the global rate limits on purge API.

Get media library file

You can get the list of files uploaded in media library using this admin API.

Generating signature for the list uploaded files request

Each request must be signed. The signature is a mandatory parameter in the request. To calculate the signature.

  1. The parameters skip, limit, imagekitId that have to be sent in the request have to be included in the signature. Maximum value of limit can be 1000.

  2. Sort the parameters in the alphabetical order of the keys i.e. imagekitId comes before limit.

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

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

  5. Example - If the skip is 0, limit is 1000, then the string to be used for signature will be imagekitId=yourimagekitID&limit=1000&skip=0.

  6. Using your private key as the key, calculate a hexadecimal HMAC-SHA1 digest of this serialized string.

Never expose your private key on the client-side. All signature generation should take place on the server.

List files API usage:

curl -X GET \
  'https://imagekit.io/api/admin/media/listFiles?skip=0&limit=1000&imagekitId=your_imagekitId&signature=your_generated_signature'

var ImageKit = require("imagekit");

var imagekit = new ImageKit({
   "imagekitId" : "your_imagekitId",       
   "apiKey" : "your_apiKey",
   "apiSecret" : "your_apiSecret", 
});

var listMediaFiles = imagekit.listUploadedMediaFiles(0,1000);

listMediaFiles.then(function(resp) {
    //handle array of results
}, function(err) {
    //handle failure here
});

import requests

url = "https://imagekit.io/api/admin/media/listFiles"

querystring = {"skip":"0","limit":"1000","imagekitId":"your_imagekitId","signature":"your_generated_signature"}

payload = ""
headers = {}

response = requests.request("GET", url, data=payload, headers=headers, params=querystring)

print(response.text)

HttpResponse<String> response = Unirest.get("https://imagekit.io/api/admin/media/listFiles?skip=0&limit=1000&imagekitId=your_imagekitId&signature=your_generated_signature")
  .asString();

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://imagekit.io/api/admin/media/listFiles?skip=0&limit=1000&imagekitId=your_imagekitId&signature=your_generated_signature",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => "",
  CURLOPT_HTTPHEADER => array(),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

?>

Output for successful list files request:

[  
   {  
      "name":"test.jpg",
      "url":"https://ik.imagekit.io/demo/test.jpg"
   },
   {  
      "name":"gate.jpg",
      "url":"https://ik.imagekit.io/demo/new-uploaded-files/gate.jpg"
   }
]

HTTP Request

GET https://imagekit.io/api/admin/media/listFiles

Query Parameters

Parameter Required Description
skip Yes The number of files you want to skip from the response
limit Yes The maximum number of URLs you want in response. The maximum allowed value is 1000.
imagekitId Yes ImageKit ID associated with your account
signature Yes HMAC-SHA1 signature generated for the this request

Response Codes

HTTP Status Status Number (Status Code) Description
400 1400 (BAD_REQUEST) Invalid or missing form parameters in the request
400 1401 (BAD_REQUEST) Limit parameter value is more than 1000
403 1403 (ACCESS_FORBIDDEN) Invalid signature
404 1404 (UNMAPPED_REQUEST) Invalid ImageKit Id
500 1500 (SERVER_ERROR) Internal server error while deleting the file

Delete media library file

You can delete the files uploaded in media library from the dashboard or using this admin API.

Generating signature for the delete request

Each delete request must be signed. The signature is a mandatory parameter in the request. To calculate the signature.

  1. The parameters path, imagekitId that have to be sent in the file delete request have to be included in the signature.

  2. Sort the parameters in the alphabetical order of the keys i.e. imagekitId comes before path.

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

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

  5. Example - If the path is example-image.jpeg, imagekitId is yourimagekitID, then the string to be used for signature will be imagekitId=yourimagekitID&path=example-image.jpeg.

  6. Using your private key as the key, calculate a hexadecimal HMAC-SHA1 digest of this serialized string.

Never expose your private key on the client-side. All signature generation should take place on the server.

Delete API usage:

curl -X POST \
  https://imagekit.io/api/admin/media/deleteFile \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'imagekitId=your_imagekitId&signature=your_generated_signature&path=path-of-the-image-returned-from-upload-api.jpg'

var ImageKit = require("imagekit");

var imagekit = new ImageKit({
   "imagekitId" : "your_imagekitId",       
   "apiKey" : "your_apiKey",
   "apiSecret" : "your_apiSecret", 
});

var deletePromise = imagekit.deleteFile("path-of-the-image-returned-from-upload-api.jpg");  

deletePromise.then(function(resp) {
    //handle delete success here    
}, function(err) {
    //handle delete failure here
});

import requests

url = "https://imagekit.io/api/admin/media/deleteFile"

payload = "imagekitId=your_imagekitId&signature=your_generated_signature&path=path-of-the-image-returned-from-upload-api.jpg"
headers = {
    'Content-Type': "application/x-www-form-urlencoded"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

HttpResponse<String> response = Unirest.post("https://imagekit.io/api/admin/media/deleteFile")
.header("Content-Type", "application/x-www-form-urlencoded")
.body("imagekitId=your_imagekitId&signature=your_generated_signature&path=path-of-the-image-returned-from-upload-api.jpg")
.asString();

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://imagekit.io/api/admin/media/deleteFile",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "imagekitId=your_imagekitId&signature=your_generated_signature&path=path-of-the-image-returned-from-upload-api.jpg",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/x-www-form-urlencoded"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

?>

Output for successful delete request:

{
  "success": true
}

HTTP Request

POST https://imagekit.io/api/admin/media/deleteFile
Content-Type : application/x-www-form-urlencoded

Parameters

Parameter Required Description
path Yes The imagePath that you get when uploading image. It excludes any URL-pattern and hostname.
imagekitId Yes ImageKit ID associated with your account
signature Yes HMAC-SHA1 signature generated for the this request

Response Codes

HTTP Status Status Number (Status Code) Description
400 1400 (BAD_REQUEST) Invalid or missing form parameters in the request
403 1403 (ACCESS_FORBIDDEN) Invalid signature
404 1404 (UNMAPPED_REQUEST) Invalid ImageKit Id
500 1500 (SERVER_ERROR) Internal server error while deleting the file

Rate Limits

ImageKit.io does not enforce any rate limits on image fetch requests or image transformations. However, we do impose rate limits on our admin APIs to protect our infrastructure from excessive request rates, to keep ImageKit.io fast and stable for everyone. These limits are high enough that typical API workflows aren’t affected. However, please do code your integration to follow the rule below:

If you receive a response status code of 429 (Too Many Requests), please sleep/pause for the number of milliseconds specified by the X-RateLimit-Reset value before making additional requests to that endpoint. If an action is blocked, it is still counted against the enforced rate limits. This means that if you are continually attempting actions more quickly than the allowed rate, all of your actions will be blocked until you pause or slow your requests

See below for the specific response format in case you receive a status code of 429.

Response structure

Parameter Description
X-RateLimit-Type It could be perSecondLimit or perMinuteLimit
X-RateLimit-Limit Request limit enforced for this endpoint
X-RateLimit-Reset Milliseconds remaining before this enforcement window ends

API requests are limited at a per account level across all users.

SDKs and Plugins

ImageKit provides SDKs and plugins that make it easy to integrate image uploads and image get requests in your application. The documentation of how to use a particular SDK or plugin in your application is provided below-

Developed by ImageKit

ImageKit developed these libraries. If you find a bug or have any suggestions, feel free to contact us.

NodeJS

NPM package

Python

Python package

Client-side jQuery plugin

ImageKit client-side jQuery plugin

Wordpress plugin

See on Wordpress

Shopify Integration

ImageKit.io integration on Shopify

Developed by the community

These libraries were contributed by ImageKit community. If you find a bug or have any suggestions, feel free to create an issue in respective repositories.

Ruby

Ruby Gem

.NET

.NET integration

If you have implemented your library or an example that you’d like to share, please send a link to your code. We’ll be happy to add it to the list!

cURL NodeJS Python Java PHP