Server side file upload
You can upload files to the ImageKit.io media library from your server-side using private API key authentication.
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:
- 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 - https://www.example.com/rest-of-the-image-path.jpg.
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. |
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, ImageKit.io 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.
- 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 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.
- 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.
|
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, and customMetadata. |
extensions optional | Stringified JSON object with an array of extensions to be applied to the image. |
webhookUrl optional | The 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 uploaded 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 |
type | Type of item. It can be either file or folder. |
name | Name of the file or folder. |
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. |
thumbnail | In the case of an image, a small thumbnail URL. |
fileType | The type of file could be either image or non-image. |
mime | MIME Type of the file. For example - image/jpeg |
height | Height of the image in pixels (Only for images) |
width | Width of the image in pixels (Only for Images) |
size | Size of the image file in Bytes |
hasAlpha | A boolean indicating if the image has an alpha layer or not. |
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. |
createdAt | The date and time when the file was first uploaded. The format is YYYY-MM-DDTHH:mm:ss.sssZ |
updatedAt | The date and time when the file was last updated. The format is YYYY-MM-DDTHH:mm:ss.sssZ |
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. |
Here are some example requests and responses to understand the API usage.
cURL
Node.js
Python
PHP
Java
Ruby
Go
.Net
curl -X POST "https://upload.imagekit.io/api/v1/files/upload" \
-u your_private_api_key: \
-F '[email protected]/Users/username/Desktop/my_file_name.jpg;type=image/jpg' \
-F 'fileName=my_file_name.jpg'
var ImageKit = require("imagekit");
var fs = require('fs');
var imagekit = new ImageKit({
publicKey : "your_public_key",
privateKey : "your_private_key",
urlEndpoint : "https://ik.imagekit.io/your_imagekit_id/"
});
fs.readFile('image.jpg', function(err, data) {
if (err) throw err; // Fail if the file can't be read.
imagekit.upload({
file : data, //required
fileName : "my_file_name.jpg", //required
tags: ["tag1", "tag2"]
}, function(error, result) {
if(error) console.log(error);
else console.log(result);
});
});
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'
)
upload = imagekit.upload(
file=open("image.jpg", "rb"),
file_name="my_file_name.jpg",
options=UploadFileRequestOptions(
tags = ["tag1", "tag2"]
)
)
print("Upload binary", upload)
# Raw Response
print(upload.response_metadata.raw)
# print that uploaded file's ID
print(upload.file_id)
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
);
// Upload Image - Binary
$uploadFile = $imageKit->uploadFile([
"file" => fopen(__DIR__."/image.jpg", "r"),
"fileName" => "my_file_name.jpg",
"tags" => ["tag1", "tag2"]
]);
echo ("Upload binary file : " . json_encode($uploadFile));
byte[] bytes= Files.readAllBytes(Paths.get("/path/to/file.jpg"));
FileCreateRequest fileCreateRequest =new FileCreateRequest(bytes, "sample_image.jpg");
fileCreateRequest.setUseUniqueFileName(false);
Result result = ImageKit.getInstance().upload(fileCreateRequest);
imagekitio = ImageKit::ImageKitClient.new("your_private_key", "your_public_key", "your_url_endpoint")
file = open("sample.jpg", "rb")
upload = imagekitio.upload_file(file, "my_file_name.jpg", {
tags: %w[tag1 tag2]
})
ik, err := ImageKit.New()
const base64Image = "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7"
resp, err := ik.Upload.Upload(ctx, base64Image, uploader.UploadParam{})
var imagekit = new ImageKit({
publicKey : "your_public_api_key",
privateKey : "your_private_api_key",
urlEndpoint : "https://ik.imagekit.io/your_imagekit_id/"
});
byte[] bytes = File.ReadAllBytes("/path/to/file.jpg");
FileCreateRequest ob = new FileCreateRequest
{
file = bytes,
fileName = "file_name1.jpg"
};
Result resp2 = imagekit.Upload(ob);
cURL
Node.js
Python
PHP
Java
Ruby
Go
.Net
curl -X POST "https://upload.imagekit.io/api/v1/files/upload" \
-u your_private_api_key: \
-F 'file=iVBORw0KGgoAAAAN' \
-F 'fileName=my_file_name.jpg' \
-F 'tags=tag1,tag2'
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 base64Img = "iVBORw0KGgoAAAAN";
imagekit.upload({
file : base64Img, //required
fileName : "my_file_name.jpg", //required
tags: ["tag1","tag2"]
}, function(error, result) {
if(error) console.log(error);
else console.log(result);
});
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'
)
with open("image.jpg", mode="rb") as img:
imgstr = base64.b64encode(img.read())
upload = imagekit.upload(
file=imgstr,
file_name="my_file_name.jpg",
options=UploadFileRequestOptions(
response_fields = ["is_private_file", "custom_metadata", "tags"],
is_private_file = False,
tags = ["tag1", "tag2"],
webhook_url = "url",
overwrite_file = False,
overwrite_ai_tags = False,
overwrite_tags = False,
overwrite_custom_metadata = True,
custom_metadata = {"test": 11})
),
)
print("Upload base64", upload)
# Raw Response
print(upload.response_metadata.raw)
# print that uploaded file's ID
print(upload.file_id)
# print that uploaded file's version ID
print(upload.version_info.id)
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
);
$img = file_get_contents(__DIR__."/image.jpg");
// Encode the image string data into base64
$base64Img = base64_encode($img);
// Upload Image - base64
$uploadFile = $imageKit->uploadFile([
"file" => $base64Img,
"fileName" => "my_file_name.jpg",
"tags" => ["tag1", "tag2"]
]);
echo ("Upload base64" . json_encode($uploadFile));
FileCreateRequest fileCreateRequest =new FileCreateRequest(base64, "sample_base64_image.jpg");
Result result = ImageKit.getInstance().upload(fileCreateRequest);
imagekitio = ImageKitIo::Client.new("your_private_key", "your_public_key", "your_url_endpoint")
image64 = Base64.encode64(File.open("sample.jpg", "rb").read)
upload = imagekitio.upload_file(
file: image64,
file_name: "my_file_name.jpg",
tags: %w[tag1 tag2]
)
ik, err := ImageKit.New()
const base64Image = "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7"
resp, err := ik.Upload.Upload(ctx, base64Image, uploader.UploadParam{
FileName: "my_file_name.jpg",
Tags: "tag1,tag2",
})
var imagekit = new ImageKit({
publicKey : "your_public_api_key",
privateKey : "your_private_api_key",
urlEndpoint : "https://ik.imagekit.io/your_imagekit_id/"
});
var base64ImageRepresentation = "iVBORw0KGgoAAAAN";
FileCreateRequest ob2 = new FileCreateRequest
{
file = base64ImageRepresentation,
fileName = Guid.NewGuid().ToString(),
};
List<string> tags = new List<string>
{
"tags1",
"tags2"
};
ob.tags = tags;
Result resp = imagekit.Upload(ob2);
cURL
Node.js
Python
PHP
Java
Ruby
Go
.Net
curl -X POST "https://upload.imagekit.io/api/v1/files/upload" \
-u your_private_api_key: \
-F 'file=https://imagekit.io/image.jpg' \
-F 'fileName=my_file_name.jpg'
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/"
});
imagekit.upload({
file : "https://imagekit.io/image.jpg", //required
fileName : "my_file_name.jpg" //required
}, function(error, result) {
if(error) console.log(error);
else console.log(result);
});
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'
)
with open("image.jpg", mode="rb") as img:
imgstr = base64.b64encode(img.read())
upload = imagekit.upload(
file="https://imagekit.io/image.jpg",
file_name="my_file_name.jpg",
options=UploadFileRequestOptions(),
)
print("Upload url", upload)
# Raw Response
print(upload.response_metadata.raw)
# print that uploaded file's ID
print(upload.file_id)
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
);
// Upload Image - URL
$uploadFile = $imageKit->uploadFile([
"file" => "https://imagekit.io/image.jpg",
"fileName" => "my_file_name.jpg"
]);
echo ("Upload URL" . json_encode($uploadFile));
FileCreateRequest fileCreateRequest = new FileCreateRequest("image_url", "my_file_name.jpg");
Result result = ImageKit.getInstance().upload(fileCreateRequest);
imagekitio = ImageKit::ImageKitClient.new("your_private_key", "your_public_key", "your_url_endpoint")
upload = imagekitio.upload_file(
file: "image_url",
file_name: "my_file_name.jpg"
)
url := "https://imagekit.io/image.jpg"
resp, err := ik.Upload.Upload(ctx, url, uploader.UploadParam{
FileName: "my_file_name.jpg",
})
var imagekit = new ImageKit({
publicKey : "your_public_api_key",
privateKey : "your_private_api_key",
urlEndpoint : "https://ik.imagekit.io/your_imagekit_id/"
});
FileCreateRequest request = new FileCreateRequest
{
file = "image_url",
fileName = "file_name.jpg"
};
Result resp1 = imagekit.Upload(request);
cURL
Node.js
Python
PHP
Java
Ruby
Go
.Net
curl -X POST "https://upload.imagekit.io/api/v1/files/upload" \
-u your_private_api_key: \
-F 'file=https://ik.imagekit.io/ikmedia/red_dress_woman.jpeg' \
-F 'fileName=women_in_red.jpg' \
-F 'customMetadata={"brand":"Nike", "color":"red"}'
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/"
});
imagekit.upload({
file : "https://ik.imagekit.io/ikmedia/red_dress_woman.jpeg",
fileName : "women_in_red.jpg",
customMetadata : {
"brand": "Nike",
"color": "red"
}
}, function(error, result) {
if(error) console.log(error);
else console.log(result);
});
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'
)
with open("image.jpg", mode="rb") as img:
imgstr = base64.b64encode(img.read())
upload = imagekit.upload(
file="https://ik.imagekit.io/ikmedia/red_dress_woman.jpeg",
file_name="women_in_red.jpg",
options=UploadFileRequestOptions(
custom_metadata = {"brand":"Nike", "color":"red"}
),
)
print("Upload url", upload)
# Raw Response
print(upload.response_metadata.raw)
# print that uploaded file's ID
print(upload.file_id)
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
);
// Upload Image - URL
$uploadFile = $imageKit->uploadFile([
"file" => "https://ik.imagekit.io/ikmedia/red_dress_woman.jpeg",
"fileName" => "women_in_red.jpg",
"customMetadata" => [
"brand" => "Nike",
"color" => "red",
]
]);
echo ("Upload URL" . json_encode($uploadFile));
FileCreateRequest fileCreateRequest = new FileCreateRequest("https://ik.imagekit.io/ikmedia/red_dress_woman.jpeg", "women_in_red.jpg");
JsonObject jsonObjectCustomMetadata = new JsonObject();
jsonObjectCustomMetadata.addProperty("brand", "Nike");
jsonObjectCustomMetadata.addProperty("color", "red");
fileCreateRequest.setCustomMetadata(jsonObjectCustomMetadata);
Result result=ImageKit.getInstance().upload(fileCreateRequest);
System.out.println(result);
imagekitio = ImageKitIo::Client.new("your_private_key", "your_public_key", "your_url_endpoint")
upload = imagekitio.upload_file(
file: "https://ik.imagekit.io/ikmedia/red_dress_woman.jpeg",
file_name: "women_in_red.jpg",
custom_metadata: {
"brand": "Nike",
"color": "red"
}
)
url := "https://imagekit.io/image.jpg"
resp, err := ik.Upload.Upload(ctx, url, uploader.UploadParam{
FileName: "women_in_red.jpg",
CustomMetadata: `{"brand":"Nike", "color":"red"}`,
})
var imagekit = new ImageKit({
publicKey : "your_public_api_key",
privateKey : "your_private_api_key",
urlEndpoint : "https://ik.imagekit.io/your_imagekit_id/"
});
var base64ImageRepresentation = "iVBORw0KGgoAAAAN";
FileCreateRequest ob2 = new FileCreateRequest
{
file = base64ImageRepresentation,
fileName = Guid.NewGuid().ToString()
};
Hashtable model = new Hashtable
{
{ "brand", "Nike" },
{ "color", "red" }
};
ob2.customMetadata = model;
Result resp = imagekit.Upload(ob2);
cURL
Node.js
Python
PHP
Java
Go
.Net
curl -X POST "https://upload.imagekit.io/api/v1/files/upload" \
-u your_private_api_key: \
-F '[email protected]/Users/username/Desktop/my_file_name.jpg' \
-F 'fileName=my_file_name.jpg' \
-F 'extensions=[{"name":"remove-bg","options":{"add_shadow":true,"bg_colour":"green"}},{"name":"google-auto-tagging","maxTags":5,"minConfidence":95}]'
var ImageKit = require("imagekit");
var fs = require('fs');
var imagekit = new ImageKit({
publicKey : "your_public_key",
privateKey : "your_private_key",
urlEndpoint : "https://ik.imagekit.io/your_imagekit_id/"
});
fs.readFile('image.jpg', function(err, data) {
if (err) throw err; // Fail if the file can't be read.
imagekit.upload({
file : data, //required
fileName : "my_file_name.jpg", //required
extensions: '[
{
"name": "remove-bg",
"options": {
"add_shadow": true,
"bg_colour": "green"
}
},
{
"name": "google-auto-tagging",
"maxTags": 5,
"minConfidence": 95
}
]'
}, function(error, result) {
if(error) console.log(error);
else console.log(result);
});
});
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'
)
with open("image.jpg", mode="rb") as img:
imgstr = base64.b64encode(img.read())
upload = imagekit.upload(
file="https://ik.imagekit.io/ikmedia/red_dress_woman.jpeg",
file_name="women_in_red.jpg",
options=UploadFileRequestOptions(
extensions = [{"name": "remove-bg", "options": {"add_shadow": True, "bg_color": "pink"}},
{"name": "google-auto-tagging", "minConfidence": 80, "maxTags": 10}]
),
)
print("Upload url", upload)
# Raw Response
print(upload.response_metadata.raw)
# print that uploaded file's ID
print(upload.file_id)
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
);
// Upload Image - URL
$uploadFile = $imageKit->upload([