Client side file upload

You can upload files to the media library directly from the client-side in Javascript, or Android or iPhone app using signature-based authentication. You will need to implement authenticationEndpoint endpoint on your backend server as shown here.

You can use ImageKit client-side SDKs to get started quickly. See example usage.

File size limit The maximum upload file size is limited to 25MB.


Request structure (multipart/form-data)



file required

This field accepts three kinds of values:

  • binary - You can send the content of the file as binary. This is used when a file is being uploaded from the browser.

  • base64 - Base64 encoded string of file content.

  • url - URL of the file from where to download the content before uploading. For example -

Note: When passing a URL in the file parameter, please ensure that our servers can access the URL. In case ImageKit is unable to download the file from the specified URL, a 400 error response is returned. In addition to this, the file download request is aborted if response headers are not received in 8 seconds. This will also result in a 400 error.

publicKey required

Your public API key.  Note: This field is only required when uploading the file from the client-side. The only purpose of this is to identify your account.

signature required

HMAC-SHA1 digest of the token+expire using your private API key as a key. Learn how to create a signature below on the page. This should be in lowercase.

Warning: Signature must be calculated on the server-side. This field is required for authentication when uploading a file from the client-side.

expire required

The time until your signature is valid. It must be a Unix time in less than 1 hour into the future. It should be in seconds.

token required

A unique value generated by the client, which will be used by the server to recognize and prevent subsequent retries for the same request. We suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions. Note: Sending a value that has been used in the past will result in a validation error. Even if your previous request resulted in an error, you should always send a new value for this field.

fileName required

The name with which the file has to be uploaded.

The file name can contain: - Alphanumeric Characters: a-z , A-Z , 0-9 (including unicode letters, marks, and numerals in other languages) - Special Characters: . _ and -

Any other character including space will be replaced by _

useUniqueFileName optional

Whether to use a unique filename for this file or not.

  • Accepts true or false.

  • If set true, will add a unique suffix to the filename parameter to get a unique filename.

  • If set false, then the image is uploaded with the provided filename parameter, and any existing file with the same name is replaced.

Default value - true

tags optional

Set the tags while uploading the file.

  • A comma-separated value of tags in the format tag1,tag2,tag3. For example - t-shirt,round-neck,men

  • The maximum length of all characters should not exceed 500.

  • % is not allowed.

  • If this field is not specified and the file is overwritten, then the tags will be removed.

folder optional

The folder path (e.g. /images/folder/) in which the image has to be uploaded. If the folder(s) didn't exist before, a new folder(s) is created.

The folder name can contain: - Alphanumeric Characters: a-z , A-Z , 0-9 (including unicode letters, marks, and numerals in other languages) - Special Characters: / _ and - - Using multiple / creates a nested folder.

Default value - /

isPrivateFile optional

Whether to mark the file as private or not. This is only relevant for image type files

  • Accepts true or false.

  • If set true, the file is marked as private which restricts access to the original image URL and unnamed image transformations without signed URLs. Without the signed URL, only named transformations work on private images

Default value - false

customCoordinates optional

Define an important area in the image. This is only relevant for image type files.

  • To be passed as a string with the x and y coordinates of the top-left corner, and width and height of the area of interest in the format x,y,width,height. For example - 10,10,100,100

  • Can be used with fo-customtransformation.

  • If this field is not specified and the file is overwritten, then customCoordinates will be removed.

responseFields optional

Comma-separated values of the fields that you want to return in the response. For example, set the value of this field to tags,customCoordinates,isPrivateFile,metadata to get the value of tags, customCoordinates, isPrivateFile , and metadata in the response.

Response code and structure (JSON)

In case of an error, you will get an error code along with the error message. On successful upload, you will receive a 200 status code with uploaded file details in a JSON-encoded response body.

"fileId" : "598821f949c0a938d57563bd",
"name": "file1.jpg",
"url": "",
"thumbnailUrl": "",
"height" : 300,
"width" : 200,
"size" : 83622,
"filePath": "/images/products/file1.jpg",
"tags": ["t-shirt","round-neck","sale2019"],
"isPrivateFile" : false,
"customCoordinates" : null,
"fileType": "image"

Understanding response

The JSON-encoded response contains details of the file which can have the following properties:




Unique fileId. Store this fileld in your database, as this will be used to perform update action on this file.


The name of the uploaded file.


The URL of the file.


In the case of an image, a small thumbnail URL.


Height of the uploaded image file. Only applicable when the file type is an image.


Width of the uploaded image file. Only applicable when the file type is an image.


Size of the uploaded file in bytes.


Type of file. It can either be image or non-image.


The path of the file uploaded. It includes any folder that you specified while uploading.


Anarray of tags associated with the file.


Is the file marked as private. It can be either true or false.


Value of custom coordinates associated with the image in the format x,y,width,height.


The metadata of the upload file. Use fields property in request to get the metadata returned in the response of upload API.

Signature generation for client-side file upload

signature is a string sent along with your upload request for authentication when using upload API from the client-side. Generating it requires your private API key, and hence this should be generated on your backend. Your backend should ideally implement an API that should provide signature.

The signature is HMAC-SHA1 digest of the string token+expire using your private API key as a key. The signature should be in lowercase.

Never publish your private key on client-side The Private API key should be kept confidential and only stored on your own servers.

If you are using client-end SDK for file upload, it requires an authenticationEndpoint endpoint for getting authentication parameters required in the upload API.

How to implement authenticationEndpoint endpoint?

This endpoint is specified by authenticationEndpoint parameter during initialization. The SDK makes an HTTP GET request to this endpoint and expects a JSON response with three fields i.e. signature, token and expire.

Example response:

token: "1bab386f-45ea-49e1-9f0d-6afe49a5b250",
expire: 1580372696,
signature: "0f9d5a45e97c24fa9200a9d5543c9af1e2c45a54"

Since calculating these parameters requires your private API key, hence this endpoint has to be implemented on your server-side. You can use utility functions provided in all server-side SDKs to implement this endpoint as shown below.

Pseudo code
Pseudo code
var token = req.query.token || uuid.v4();
var expire = req.query.expire || parseInt(;
var privateAPIKey = "your_private_key";
var signature = crypto.createHmac('sha1', privateAPIKey).update(token+expire).digest('hex');
"Access-Control-Allow-Origin" : "*"
token : token,
expire : expire,
signature : signature
var ImageKit = require("imagekit");
var fs = require('fs');
var imagekit = new ImageKit({
publicKey : "your_public_api_key",
privateKey : "your_private_api_key",
urlEndpoint : ""
var authenticationParameters = imagekit.getAuthenticationParameters();
import base64
import os
import sys
from imagekitio import ImageKit
imagekit = ImageKit(
private_key='your private_key',
public_key='your public_key',
url_endpoint = 'your url_endpoint'
auth_params = imagekit.get_authentication_parameters()
print("Auth params-", auth_params)
use ImageKit\ImageKit;
$public_key = "your_public_key";
$your_private_key = "your_private_key";
$url_end_point = "";
$sample_file_path = "/sample.jpg";
$imageKit = new ImageKit(
$authenticationParameters = $imageKit->getAuthenticationParameters();
echo("Auth params : " . json_encode($authenticationParameters));

Never publish your private key on client-side The Private API key should be kept confidential and only stored on your own servers.


Make sure you have implemented authenticationEndpoint endpoint on your server as shown here before using the below examples.

JavaScipt SDK
jQuery (without SDK)
React SDK
Vue.js SDK
JavaScipt SDK
<form action="#" onsubmit="upload()">
<input type="file" id="file1" />
<input type="submit" />
<script type="text/javascript" src="../dist/imagekit.js"></script>
SDK initilization
authenticationEndpoint should be implemented on your server
as shown above
var imagekit = new ImageKit({
publicKey : "your_public_api_key",
urlEndpoint : "",
authenticationEndpoint : ""
// Upload function internally uses the javascript SDK
function upload(data) {
var file = document.getElementById("file1");
file : file.files[0],
fileName : "abc.jpg",
tags : ["tag1"]
}, function(err, result) {
src: result.url,
transformation : [{ height: 300, width: 400}]
jQuery (without SDK)
<form action="#" onsubmit="upload()">
<input type="file" id="file1" />
<input type="submit" />
<script src="" integrity="sha256-CSXorXvZcTkaix6Yvo6HppcZGetbYMGWSFlBw8HfCJo=" crossorigin="anonymous"></script>
// This endpoint should be implemented on your server as shown above
var authenticationEndpoint = "";
function upload() {
var file = document.getElementById("file1");
var formData = new FormData();
formData.append("file", file.files[0]);
formData.append("fileName", "abc.jpg");
formData.append("publicKey", "your_public_api_key");
// Let's get the signature, token and expire from server side
url : authenticationEndpoint,
method : "GET",
dataType : "json",
success : function(body) {
if(typeof callback != "function") return;
formData.append("signature", body.signature || "");
formData.append("expire", body.expire || 0);
formData.append("token", body.token);
// Now call upload API
url : "",
method : "POST",
mimeType : "multipart/form-data",
dataType : "json",
data : formData,
processData : false,
contentType : false,
error : function(jqxhr, text, error) {
success : function(body) {
error : function(jqxhr, text, error) {
React SDK
import React from 'react';
import { IKImage, IKContext, IKUpload } from 'imagekitio-react'
function App() {
const publicKey = "your_public_api_key";
let urlEndpoint = "";
const authenticationEndpoint = "";
return (
<div className="App">
<p>To use this funtionality please remember to setup the server</p>
<IKContext publicKey={publicKey} urlEndpoint={urlEndpoint} authenticationEndpoint={authenticationEndpoint} >
<IKUpload fileName="abc.jpg" tags={["tag1"]} useUniqueFileName={true} isPrivateFile= {false} />
export default App;
Vue.js SDK
<div class="sample-app">
<IKUpload fileName="abc.jpg" v-bind:tags="['tag1']" v-bind:responseFields="['tags']"/>
<p>To use this funtionality please remember to setup the server</p>
import { IKImage, IKContext, IKUpload } from "imagekitio-vue";
let urlEndpoint= "";
export default {
name: "app",
components: {
data() {
return {
urlEndpoint: "",
publicKey: "your_public_api_key",
authenticationEndpoint: ""