Client side file upload
You can upload files to the ImageKit.io 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.File size limit
The maximum upload file size is limited to 25MB on the free plan. On paid plan, this limit is 300MB for video files.
Version limit
A file can have a maximum of 100 versions.
Method | Endpoint |
---|---|
POST |
Parameter | Description |
---|---|
file
required
| This field accepts three kinds of values:
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 ImageKit.io private API key as a key. Learn how to create a signature below on the page. This should be in lowercase.
⚠ |
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 ImageKit.io 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.
Default value - true |
tags
optional
| Set the tags while uploading the file.
|
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 nesting of folders can be at most 50 levels deep.
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
Default value - false |
isPublished
optional
| Whether to upload file as published or not.
- Accepts true or false .
- If set false , the file is marked as unpublished, which restricts access to the file only via the media library. Files in draft or unpublished state can only be publicly accessed after being published.
- The option to upload in draft state is only available in custom enterprise pricing plans.
Default value - true |
customCoordinates
optional
| Define an important area in the image. This is only relevant for image type files.
|
responseFields
optional
| Comma-separated values of the fields that you want the API to return in the response. For example, set the value of this field to tags,customCoordinates,isPrivateFile to get the value of tags , customCoordinates , and isPrivateFile in the response. Accepts combination of tags , customCoordinates , isPrivateFile , embeddedMetadata , customMetadata and metadata . |
extensions optional | Stringified JSON object with array of extensions to be processed on the image. |
webhookUrl optional | Final status of pending extensions will be sent to this URL. To learn more about how ImageKit uses webhooks, refer here. |
overwriteFile optional | Default is true . If overwriteFile is set to false and useUniqueFileName is also false , and a file already exists at the exact location, upload API will return an error immediately. |
overwriteAITags optional | Default is true . If set to true and a file already exists at the exact location, its AITags will be removed. Set overwriteAITags to false to preserve AITags . |
overwriteTags optional | Default is true . If the request does not have tags , overwriteTags is set to true and a file already exists at the exact location, exiting tags will be removed. In case the request body has tags , setting overwriteTags to false has no effect and request's tags are set on the asset. |
overwriteCustomMetadata optional | Default is true . If the request does not have customMetadata , overwriteCustomMetadata is set to true and a file already exists at the exact location, exiting customMetadata will be removed. In case the request body has customMetadata , setting overwriteCustomMetadata to false has no effect and request's customMetadata is set on the asset. |
customMetadata optional | Stringified JSON key-value data to be associated with the asset. Checkout overwriteCustomMetadata parameter to understand default behaviour. Before setting any custom metadata on an asset you have to create the field using custom metadata fields API. |
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": "https://ik.imagekit.io/your_imagekit_id/images/products/file1.jpg",
"thumbnailUrl": "https://ik.imagekit.io/your_imagekit_id/tr:n-media_library_thumbnail/images/products/file1.jpg",
"height": 300,
"width": 200,
"size": 83622,
"filePath": "/images/products/file1.jpg",
"tags": ["t-shirt", "round-neck", "sale2019"],
"AITags": [
{
"name": "Shirt",
"confidence": 90.12,
"source": "google-auto-tagging"
},
/* ... more googleVision tags ... */
],
"versionInfo": {
"id": "598821f949c0a938d57563bd",
"name": "Version 1"
},
"isPrivateFile": false,
"customCoordinates": null,
"customMetadata": {
brand: "Nike",
color: "red"
},
"embeddedMetadata": {
Title: "The Title (ref2019.1)",
Description: "The description aka caption (ref2019.1)",
State: "Province/State(Core)(ref2019.1)",
Copyright: "Copyright (Notice) 2019.1 IPTC - www.iptc.org (ref2019.1)"
},
"extensionStatus": {
"google-auto-tagging": "success",
"aws-auto-tagging": "pending"
},
"fileType": "image"
}
The JSON-encoded response contains details of the file which can have the following properties:
Property name | Description |
---|---|
fileId | Unique fileId . Store this fileld in your database, as this will be used to perform update action on this file |
name | Name of the file. |
filePath | The relative path of the file. In the case of an image, you can use this path to construct different transformations. |
tags | The array of tags associated with the image. If no tags are set, it will be null . |
AITags | Array of AITags associated with the image. If no AITags are set, it will be null . These tags can be added using the google-auto-tagging or aws-auto-tagging extensions. |
versionInfo | An object containing the file or file version's id (versionId) and name . |
isPrivateFile | Is the file marked as private. It can be either true or false . |
customCoordinates | Value of custom coordinates associated with the image in the format x,y,width,height . If customCoordinates are not defined, then it is null .
|
url | A publicly accessible URL of the file. |
thumbnailUrl | In the case of an image, a small thumbnail URL. |
fileType | The type of file could be either image or non-image . |
height | Height of the media file in pixels (Only for images and videos) |
width | Width of the media file in pixels (Only for images and videos) |
size | Size of the file in Bytes |
bitRate | Bitrate of the media file (Only for videos) |
videoCodec | Video codec of the first stream for the media file (Only for videos) |
audioCodec | Audio codec of the first stream for the media file (Only for videos) |
duration | Duration of the media file content in seconds (Only for videos) |
customMetadata | A key-value data associated with the asset. Use responseField in API request to get customMetadata in the upload API response. Before setting any custom metadata on an asset, you have to create the field using custom metadata fields API. |
embeddedMetadata | Consolidated embedded metadata associated with the file. It includes exif , iptc , and xmp data. Use responseField in API request to get embeddedMetadata in the upload API response. |
metadata | Metadata associated with the file in legacy format. |
extensionStatus | Extension names with their processing status at the time of completion of the request. It could have one of the following status values:
If no extension was requested, then this parameter is not returned. |
signature
is a string sent along with your upload request for authentication when using upload API from the client-side. Generating it requires your ImageKit.io 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 ImageKit.io 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 ImageKit.io client-end SDK for file upload, it requires an
authenticationEndpoint
endpoint for getting authentication parameters required in the upload API.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 ImageKit.io 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
Node.js
Python
PHP
var token = req.query.token || uuid.v4();
var expire = req.query.expire || parseInt(Date.now()/1000)+2400;
var privateAPIKey = "your_private_key";
var signature = crypto.createHmac('sha1', privateAPIKey).update(token+expire).digest('hex');
res.set({
"Access-Control-Allow-Origin" : "*"
})
res.status(200);
res.send({
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 : "https://ik.imagekit.io/your_imagekit_id/"
});
var authenticationParameters = imagekit.getAuthenticationParameters();
console.log(authenticationParameters);
import base64
import os
import sys
from imagekitio import ImageKit
imagekit = ImageKit(
public_key='your public_key',
private_key='your private_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 = "https://ik.imagekit.io/your_imagekit_id";
$sample_file_path = "/sample.jpg";
$imageKit = new ImageKit(
$public_key,
$your_private_key,
$url_end_point
);
$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.
The example below demonstrates only basic usage. Refer to these examples in the server-side upload section to learn about different use-cases. The only difference between client-side and server-side upload is how API authentication works.
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
index.html
<form action="#" onsubmit="upload()">
<input type="file" id="file1" />
<input type="submit" />
</form>
<script type="text/javascript" src="../dist/imagekit.js"></script>
<script>
/*
SDK initilization
authenticationEndpoint should be implemented on your server
as shown above
*/
var imagekit = new ImageKit({
publicKey : "your_public_api_key",
urlEndpoint : "https://ik.imagekit.io/your_imagekit_id",
authenticationEndpoint : "https://www.yourserver.com/auth"
});
// Upload function internally uses the ImageKit.io javascript SDK
function upload(data) {
var file = document.getElementById("file1");
imagekit.upload({
file : file.files[0],
fileName : "abc.jpg",
tags : ["tag1"]
}, function(err, result) {
console.log(arguments);
console.log(imagekit.url({
src: result.url,
transformation : [{ height: 300, width: 400}]
}));
})
}
</script>
<form action="#" onsubmit="upload()">
<input type="file" id="file1" />
<input type="submit" />
</form>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.4.1/jquery.min.js" integrity="sha256-CSXorXvZcTkaix6Yvo6HppcZGetbYMGWSFlBw8HfCJo=" crossorigin="anonymous"></script>
<script>
// This endpoint should be implemented on your server as shown above
var authenticationEndpoint = "https://www.yourserver.com/auth";
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
$.ajax({
url : authenticationEndpoint,
method : "GET",
dataType : "json",
success : function(body) {
formData.append("signature", body.signature || "");
formData.append("expire", body.expire || 0);
formData.append("token", body.token);
// Now call ImageKit.io upload API
$.ajax({
url : "https://upload.imagekit.io/api/v1/files/upload",
method : "POST",
mimeType : "multipart/form-data",
dataType : "json",
data : formData,
processData : false,
contentType : false,
error : function(jqxhr, text, error) {
console.log(error)
},
success : function(body) {
console.log(body)
}
});
},
error : function(jqxhr, text, error) {
console.log(arguments);
}
});
}
</script>
import React from 'react';
import { IKImage, IKContext, IKUpload } from 'imagekitio-react'
function App() {
const publicKey = "your_public_api_key";
let urlEndpoint = "https://ik.imagekit.io/your_imagekit_id";
const authenticationEndpoint = "https://www.yourserver.com/auth";
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} />
</IKContext>
</div>
);
}
export default App;
<template>
<div class="sample-app">
<p>Upload</p>
<IKContext
:publicKey="publicKey"
:urlEndpoint="urlEndpoint"
:authenticationEndpoint="authenticationEndpoint"
>
<IKUpload fileName="abc.jpg" v-bind:tags="['tag1']" v-bind:responseFields="['tags']"/>
</IKContext>
<p>To use this funtionality please remember to setup the server</p>
</div>
</template>
<script>
import { IKImage, IKContext, IKUpload } from "imagekitio-vue";
let urlEndpoint= "https://ik.imagekit.io/your_imagekit_id";
export default {
name: "app",
components: {
IKImage,
IKContext,
IKUpload
},
data() {
return {
urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
publicKey: "your_public_api_key",
authenticationEndpoint: "https://www.yourserver.com/auth"
};
}
};
</script>
Last modified 11d ago