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:
- 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.
- 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
- 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
https://ik.imagekit.io/demo
is default URL endpoint.tr:w-100
is transformation string.default-image.jpg
is the image path.
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 -
Learn about crop, crop modes and focus using examples
maintain_ratio |
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 -
Learn about crop, crop modes and focus using examples
resize |
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 -
Learn about crop, crop modes and focus using examples
center |
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
Learn about image quality optimization, subsampling and data-saver mode support
80 |
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 -
Learn about automatic format optimization
auto |
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
Learn how to use named transformations
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
|
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 -
Learn more
false |
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 -
Learn more from examples
center |
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 -
Learn more from examples
14px |
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 -
Learn about preserving color profile
false |
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 -
Learn about metadata, color profile and auto-orientation optimizations
false |
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
Learn various use-cases from example
000000 |
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>
e.g default sharpening https://ik.imagekit.io/demo/tr:e-sharpen,h-300/sample_image.jpg
e.g image with numeric sharpening https://ik.imagekit.io/demo/tr:e-sharpen-10,h-300/sample_image.jpg
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.
e.g image with unsharp masking https://ik.imagekit.io/demo/tr:h-300,e-usm-2-2-0.8-0.024/sample_image.jpg
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-
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).
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.
- Removing Metadata
- Quality Optimisation
- Format Optimisation
- 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:
Append the following in a string
a. ImageKit ID
b. The complete transformation string without thetr:
in the beginning.
If you usetr:h-100,w-100:rt-90
in the URL, then to calculate the signature useh-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
andik-t
(covered in the next point)
If your URL ishttps://ik.imagekit.io/demo/tr:h-100,w-100:rt-90/files/image.jpg?version=1
then the image key isfiles/image.jpg?version=1
.Create an HMAC-SHA1 signature of the above string using your private key as the key.
Get the hex digest of the above signature and attach it to the URL as a query parameter named
ik-s
.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.
The parameters
filename
,timestamp
andapiKey
(your public key) that have to be sent in the image upload request have to be included in the signature.Sort the parameters in the alphabetical order of the keys i.e.
apiKey
comes beforefilename
which comes beforetimestamp
.Append the value of each of these parameters with the key using an
=
sign to get a key-value pair.Append these key-value pairs to each other using
&
to get a serialized string of the parameters.Example - If the
filename
ismy-image.jpg
,timestamp
is123456789
andapiKey
ismyapikey
, then the string to be used for signature will beapiKey=myapikey&filename=my-image.jpg×tamp=123456789
.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
andtimestamp
.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/
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
andtimestamp
.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×tamp=1510829509'
"https://upload.imagekit.io/rest/api/url/v2/myimagekitid"
Fill in with actual
imagekitId
,url
,filename
andtimestamp
.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.
The parameters
url
,imagekitId
that have to be sent in the image purge request have to be included in the signature.Sort the parameters in the alphabetical order of the keys i.e.
imagekitId
comes beforeurl
.Append the value of each of these parameters with the key using an
=
sign to get a key-value pair.Append these key value pairs to each other using
&
to get a serialized string of the parameters.Example - If the
url
ishttps://ik.imagekit.io/yourimagekitID/example-image.jpeg
,imagekitId
isyourimagekitID
, then the string to be used for signature will beimagekitId=yourimagekitID&url=https://ik.imagekit.io/yourimagekitID/example-image.jpeg
.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.
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.Sort the parameters in the alphabetical order of the keys i.e.
imagekitId
comes beforelimit
.Append the value of each of these parameters with the key using an
=
sign to get a key-value pair.Append these key value pairs to each other using
&
to get a serialized string of the parameters.Example - If the
skip
is0
,limit
is1000
, then the string to be used for signature will beimagekitId=yourimagekitID&limit=1000&skip=0
.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.
The parameters
path
,imagekitId
that have to be sent in the file delete request have to be included in the signature.Sort the parameters in the alphabetical order of the keys i.e.
imagekitId
comes beforepath
.Append the value of each of these parameters with the key using an
=
sign to get a key-value pair.Append these key value pairs to each other using
&
to get a serialized string of the parameters.Example - If the
path
isexample-image.jpeg
,imagekitId
isyourimagekitID
, then the string to be used for signature will beimagekitId=yourimagekitID&path=example-image.jpeg
.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-
NodeJS
Python
Ruby
.NET
Client-side jQuery plugin
ImageKit client-side jQuery plugin