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.
Endpoint
Method | Endpoint |
---|---|
POST |
Request structure (multipart/form-data)
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 |
fileName required | The name with which the file has to be uploaded.
The file name can contain:
- Alphanumeric Characters: - Special Characters: Any other character including space will be replaced by |
useUniqueFileName optional | Whether to use a unique filename for this file or not.
- Accepts |
tags optional | Set the tags while uploading the file.
- Comma-separated value of tags in the format |
folder optional | The folder path (e.g. - Special Characters: |
isPrivateFile optional | Whether to mark the file as private or not. This is only relevant for image type files.
- Accepts |
isPublished optional | Whether to upload file as published or not.
- Accepts |
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 |
extensions optional | Stringified JSON object with an array of extensions to be applied to the image. For reference about extensions read here. |
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 |
overwriteAITags optional | Default is |
overwriteTags optional | Default is |
overwriteCustomMetadata optional | Default is |
customMetadata optional | Stringified JSON key-value data to be associated with the asset. Checkout |
transformation optional | Stringified JSON object with the properties:
|
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.
Understanding response
The JSON-encoded response contains details of the uploaded file which can have the following properties:
Property name | Description |
---|---|
fileId | Unique |
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 |
AITags | Array of |
versionInfo | An object containing the file or file version's |
isPrivateFile | Is the file marked as private. It can be either |
customCoordinates | Value of custom coordinates associated with the image in the format |
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 |
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 |
embeddedMetadata | Consolidated embedded metadata associated with the file. It includes |
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. |
Examples
Here are some example requests and responses to understand the API usage.
Uploading file from file system
Uploading base64 encoded file with some tags
Uploading file via URL
Setting custom metadata during upload
Applying extensions while uploading
Applying pre & post transformations while uploading
Last updated