ImageKit Upload File API
The Upload File API from ImageKit — 2 operation(s) for upload file.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/imagekit-upload-file-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: ImageKit Upload File API
version: 1.0.0
description: Checkout [API overview](/docs/api-overview) to learn about ImageKit's APIs, authentication, rate limits, and error codes etc.
contact:
email: developer@imagekit.io
name: ImageKit Team
url: https://imagekit.io
termsOfService: https://imagekit.io/terms/
servers:
- url: https://api.imagekit.io
security:
- basicAuth: []
tags:
- name: Upload File
paths:
/api/v1/files/upload:
servers:
- url: https://upload.imagekit.io
post:
tags:
- Upload File
operationId: upload-file
summary: Upload file V1
description: 'ImageKit.io allows you to upload files directly from both the server and client sides. For server-side uploads, private API key authentication is used. For client-side uploads, generate a one-time `token`, `signature`, and `expire` from your secure backend using private API. [Learn more](/docs/api-reference/upload-file/upload-file#how-to-implement-client-side-file-upload) about how to implement client-side file upload.
The [V2 API](/docs/api-reference/upload-file/upload-file-v2) enhances security by verifying the entire payload using JWT.
**File size limit** \
On the free plan, the maximum upload file sizes are 25MB for images, audio, and raw files and 100MB for videos. On the Lite paid plan, these limits increase to 40MB for images, audio, and raw files and 300MB for videos, whereas on the Pro paid plan, these limits increase to 50MB for images, audio, and raw files and 2GB for videos. These limits can be further increased with enterprise plans.
**Version limit** \
A file can have a maximum of 100 versions.
**Demo applications**
- A full-fledged [upload widget using Uppy](https://github.com/imagekit-samples/uppy-uploader), supporting file selections from local storage, URL, Dropbox, Google Drive, Instagram, and more.
- [Quick start guides](/docs/quick-start-guides) for various frameworks and technologies.
'
requestBody:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/FileUploadV1'
responses:
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'200':
description: File uploaded successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Upload'
examples:
Simple image file:
value:
$ref: '#/components/examples/UploadResponseImage'
Simple video file:
value:
$ref: '#/components/examples/UploadResonseVideo'
Image with EmbeddedMetadata:
value:
$ref: '#/components/examples/UploadResponseWithEmbeddedMetadata'
'202':
description: File accepted for upload. Pre transformation for video is being processed.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The pre-transformation has been queued successfully.
'400':
description: Bad request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
- Your request is missing file parameter.
- Your request contains both signature and basic auth parameter. Use only one method, you might be exposing your private API key.
- Your request contains invalid expire parameter. Expire parameter should be a Unix time in less than 1 hour into the future.
- A file with the same name already exists at the exact location. We could not overwrite it because both overwriteFile and useUniqueFileName are set to false.
- Your request contains invalid file parameter. The file size exceeds limits.
- Upload Limit Exceeded.
- Extensions quota exceeded.
- The file could not be uploaded because the transformation field is invalid.
- The file could not be uploaded because transformations are supported only for image and video files.
- The file could not be uploaded because the detected file type & post-transformation are incompatible.
- You have sent too many requests to update the file recently. Please try again later.
- Your request contains invalid syntax for the checks parameter.
- Your request failed 'checks' validation.
help:
type: string
example: For support kindly contact us at support@imagekit.io.
/api/v2/files/upload:
servers:
- url: https://upload.imagekit.io
post:
tags:
- Upload File
operationId: upload-file-v2
summary: Upload file V2
description: 'The V2 API enhances security by verifying the entire payload using JWT. This API is in beta.
ImageKit.io allows you to upload files directly from both the server and client sides. For server-side uploads, private API key authentication is used. For client-side uploads, generate a one-time `token` from your secure backend using private API. [Learn more](/docs/api-reference/upload-file/upload-file-v2#how-to-implement-secure-client-side-file-upload) about how to implement secure client-side file upload.
**File size limit** \
On the free plan, the maximum upload file sizes are 25MB for images, audio, and raw files, and 100MB for videos. On the Lite paid plan, these limits increase to 40MB for images, audio, and raw files and 300MB for videos, whereas on the Pro paid plan, these limits increase to 50MB for images, audio, and raw files and 2GB for videos. These limits can be further increased with enterprise plans.
**Version limit** \
A file can have a maximum of 100 versions.
**Demo applications**
- A full-fledged [upload widget using Uppy](https://github.com/imagekit-samples/uppy-uploader), supporting file selections from local storage, URL, Dropbox, Google Drive, Instagram, and more.
- [Quick start guides](/docs/quick-start-guides) for various frameworks and technologies.
'
requestBody:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/FileUploadV2'
responses:
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'200':
description: File uploaded successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Upload'
examples:
Simple image file:
value:
$ref: '#/components/examples/UploadResponseImage'
Simple video file:
value:
$ref: '#/components/examples/UploadResonseVideo'
Image with EmbeddedMetadata:
value:
$ref: '#/components/examples/UploadResponseWithEmbeddedMetadata'
'202':
description: File accepted for upload. Pre transformation for video is being processed.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: The pre-transformation has been queued successfully.
'400':
description: Bad request.
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
- Your request is missing file parameter.
- Your request contains both token and basic auth parameter. Use only one method, you might be exposing your private API key.
- Your request contains invalid payload. It does not match with the payload used to generate token.
- Your request is missing token parameter.
- Your request contains expired token.
- Your request has invalid token.
- A file with the same name already exists at the exact location. We could not overwrite it because both overwriteFile and useUniqueFileName are set to false.
- Your request contains invalid file parameter. The file size exceeds limits.
- Upload Limit Exceeded.
- Extensions quota exceeded.
- The file could not be uploaded because the transformation field is invalid.
- The file could not be uploaded because transformations are supported only for image and video files.
- The file could not be uploaded because the detected file type & post-transformation are incompatible.
- You have sent too many requests to update the file recently. Please try again later.
- Your request contains invalid syntax for the checks parameter.
- Your request failed 'checks' validation.
help:
type: string
example: For support kindly contact us at support@imagekit.io.
components:
schemas:
AutoTaggingExtension:
title: Auto tagging
type: object
required:
- name
- minConfidence
- maxTags
properties:
name:
type: string
enum:
- google-auto-tagging
- aws-auto-tagging
description: Specifies the auto-tagging extension used.
minConfidence:
type: integer
description: Minimum confidence level for tags to be considered valid.
maxTags:
type: integer
description: Maximum number of tags to attach to the asset.
ExifImage:
description: Object containing EXIF image information.
type: object
additionalProperties: true
properties:
Make:
type: string
Model:
type: string
ImageDescription:
type: string
Artist:
type: string
Copyright:
type: string
Orientation:
type: integer
XResolution:
type: number
YResolution:
type: number
ResolutionUnit:
type: integer
Software:
type: string
ModifyDate:
type: string
YCbCrPositioning:
type: integer
ExifOffset:
type: integer
GPSInfo:
type: integer
SavedExtensionReference:
title: Saved Extension Reference
type: object
required:
- name
- id
properties:
name:
type: string
description: Indicates this is a reference to a saved extension.
enum:
- saved-extension
id:
type: string
description: The unique ID of the saved extension to apply.
example: ext_abc123
AutoDescriptionExtension:
title: Auto description
type: object
required:
- name
properties:
name:
type: string
description: Specifies the auto description extension.
enum:
- ai-auto-description
SelectedFieldsSchema:
type: object
description: 'This field is included in the response only if the Path policy feature is available in the plan.
It contains schema definitions for the custom metadata fields selected for the specified file path.
Field selection can only be done when the Path policy feature is enabled.
Keys are the names of the custom metadata fields; the value object has details about the custom metadata schema.
'
additionalProperties:
type: object
required:
- type
properties:
type:
description: Type of the custom metadata field.
type: string
enum:
- Text
- Textarea
- Number
- Date
- Boolean
- SingleSelect
- MultiSelect
selectOptions:
type: array
items:
oneOf:
- type: string
- type: number
- type: boolean
description: 'An array of allowed values when field type is `SingleSelect` or `MultiSelect`.
'
example:
- small
- medium
- large
- 30
- 40
- true
selectOptionsTruncated:
type: boolean
description: 'Specifies if the selectOptions array is truncated. It is truncated when number of options are > 100.
'
defaultValue:
description: 'The default value for this custom metadata field. The value should match the `type` of custom metadata field.
'
oneOf:
- type: string
- type: number
- type: boolean
- type: array
x-stainless-variantName: Mixed
title: Mixed
items:
oneOf:
- type: string
- type: number
- type: boolean
description: 'Default value should be of type array when custom metadata field type is set to `MultiSelect`.
'
example:
- true
- 10
- Hello
isValueRequired:
type: boolean
description: 'Specifies if the custom metadata field is required or not.
'
readOnly:
type: boolean
description: 'Indicates whether the custom metadata field is read only. A read only field cannot be modified after being set. This field is configurable only via the **Path policy** feature.
'
minValue:
description: 'Minimum value of the field. Only set if field type is `Date` or `Number`. For `Date` type field, the value will be in ISO8601 string format. For `Number` type field, it will be a numeric value.
'
oneOf:
- type: string
- type: number
maxValue:
description: 'Maximum value of the field. Only set if field type is `Date` or `Number`. For `Date` type field, the value will be in ISO8601 string format. For `Number` type field, it will be a numeric value.
'
oneOf:
- type: string
- type: number
minLength:
description: 'Minimum length of string. Only set if `type` is set to `Text` or `Textarea`.
'
type: number
maxLength:
description: 'Maximum length of string. Only set if `type` is set to `Text` or `Textarea`.
'
type: number
TransformationObject:
type: object
additionalProperties: false
x-stainless-naming:
java:
type_name: UploadTransformation
description: "Configure pre-processing (`pre`) and post-processing (`post`) transformations.\n\n- `pre` — applied before the file is uploaded to the Media Library. \n Useful for reducing file size or applying basic optimizations upfront (e.g., resize, compress).\n\n- `post` — applied immediately after upload. \n Ideal for generating transformed versions (like video encodes or thumbnails) in advance, so they're ready for delivery without delay.\n\nYou can mix and match any combination of post-processing types.\n"
properties:
pre:
type: string
description: 'Transformation string to apply before uploading the file to the Media Library. Useful for optimizing files at ingestion.
'
example: w-300,h-300,q-80
post:
type: array
description: "List of transformations to apply *after* the file is uploaded. \nEach item must match one of the following types:\n`transformation`, `gif-to-video`, `thumbnail`, `abs`.\n"
items:
discriminator:
propertyName: type
oneOf:
- type: object
title: Simple post-transformation
required:
- type
- value
additionalProperties: false
properties:
type:
type: string
description: Transformation type.
enum:
- transformation
value:
type: string
description: "Transformation string (e.g. `w-200,h-200`). \nSame syntax as ImageKit URL-based transformations.\n"
example:
type: transformation
value: w-400,h-400,q-70
- type: object
title: Convert GIF to video
required:
- type
additionalProperties: false
properties:
type:
type: string
description: Converts an animated GIF into an MP4.
enum:
- gif-to-video
value:
type: string
description: "Optional transformation string to apply to the output video. \n**Example**: `q-80`\n"
example:
type: gif-to-video
value: q-90
- type: object
title: Generate a thumbnail
required:
- type
additionalProperties: false
properties:
type:
type: string
description: Generates a thumbnail image.
enum:
- thumbnail
value:
type: string
description: "Optional transformation string. \n**Example**: `w-150,h-150`\n"
example:
type: thumbnail
value: w-150,h-150
- type: object
title: Adaptive Bitrate Streaming
required:
- type
- value
- protocol
additionalProperties: false
properties:
type:
type: string
description: Adaptive Bitrate Streaming (ABS) setup.
enum:
- abs
value:
type: string
description: 'List of different representations you want to create separated by an underscore.
'
protocol:
type: string
enum:
- hls
- dash
description: Streaming protocol to use (`hls` or `dash`).
example:
type: abs
value: sr-240_360_480_720_1080
protocol: hls
example:
post:
- type: thumbnail
value: w-150,h-150
- type: abs
value: sr-240_360_480_720_1080
protocol: dash
CustomMetadata:
type: object
description: 'A key-value data associated with the asset.
'
additionalProperties: true
AITaskYesNo:
title: AI Task - Yes/No
type: object
required:
- type
- instruction
properties:
type:
type: string
description: Task type that asks a yes/no question and executes actions based on the answer.
enum:
- yes_no
instruction:
type: string
minLength: 1
maxLength: 2000
description: The yes/no question for the AI to answer about the image.
example: Is this a luxury or high-end fashion item?
on_yes:
$ref: '#/components/schemas/AITaskAction'
description: Actions to execute if the AI answers yes.
on_no:
$ref: '#/components/schemas/AITaskAction'
description: Actions to execute if the AI answers no.
on_unknown:
$ref: '#/components/schemas/AITaskAction'
description: Actions to execute if the AI cannot determine the answer.
Extensions:
title: Extensions Array
type: array
items:
discriminator:
propertyName: name
anyOf:
- $ref: '#/components/schemas/RemovedotBGExtension'
- $ref: '#/components/schemas/AutoTaggingExtension'
- $ref: '#/components/schemas/AutoDescriptionExtension'
- $ref: '#/components/schemas/AITasksExtension'
- $ref: '#/components/schemas/SavedExtensionReference'
description: 'Array of extensions to be applied to the asset. Each extension can be configured with specific parameters based on the extension type.
'
example:
- name: remove-bg
options:
add_shadow: true
bg_colour: green
- name: google-auto-tagging
maxTags: 5
minConfidence: 95
- name: ai-auto-description
- name: ai-tasks
tasks:
- type: select_tags
instruction: What types of clothing items are visible in this image?
vocabulary:
- shirt
- tshirt
- dress
- trousers
- jacket
- type: yes_no
instruction: Is this a luxury or high-end fashion item?
on_yes:
add_tags:
- luxury
- premium
- name: saved-extension
id: ext_abc123
FileUploadV2:
type: object
required:
- file
- fileName
properties:
file:
type: string
format: binary
contentEncoding: binary
description: 'The API accepts any of the following:
- **Binary data** – send the raw bytes as `multipart/form-data`.
- **HTTP / HTTPS URL** – a publicly reachable URL that ImageKit’s servers can fetch.
- **Base64 string** – the file encoded as a Base64 data URI or plain Base64.
When supplying a URL, the server must receive the response headers within 8 seconds; otherwise the request fails with 400 Bad Request.
'
fileName:
type: string
description: 'The name with which the file has to be uploaded.
'
token:
type: string
description: 'This is the client-generated JSON Web Token (JWT). The ImageKit.io server uses it to authenticate and check that the upload request parameters have not been tampered with after the token has been generated. Learn how to create the token on the page below. This field is only required for authentication when uploading a file from the client side.
**Note**: Sending a JWT 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 token.
**⚠️Warning**: JWT must be generated on the server-side because it is generated using your account''s private API key. This field is required for authentication when uploading a file from the client-side.
'
useUniqueFileName:
type: boolean
default: true
description: 'Whether to use a unique filename for this file or not.
If `true`, ImageKit.io will add a unique suffix to the filename parameter to get a unique filename.
If `false`, then the image is uploaded with the provided filename parameter, and any existing file with the same name is replaced.
'
tags:
type: array
items:
type: string
description: 'Set the tags while uploading the file.
Provide an array of tag strings (e.g. `["tag1", "tag2", "tag3"]`). The combined length of all tag characters must not exceed 500, and the `%` character is not allowed.
If this field is not specified and the file is overwritten, the existing tags will be removed.
'
example:
- t-shirt
- round-neck
- men
folder:
type: string
description: 'The folder path in which the image has to be uploaded. If the folder(s) didn''t exist before, a new folder(s) is created. Using multiple `/` creates a nested folder.
'
default: /
isPrivateFile:
type: boolean
default: false
description: 'Whether to mark the file as private or not.
If `true`, the file is marked as private and is accessible only using named transformation or signed URL.
'
isPublished:
type: boolean
default: true
description: 'Whether to upload file as published or not.
If `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.
'
customCoordinates:
type: string
description: "Define an important area in the image. This is only relevant for image type files.\n\n - 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`\n - Can be used with fo-customtransformation.\n - If this field is not specified and the file is overwritten, then customCoordinates will be removed.\n"
responseFields:
type: array
items:
type: string
enum:
- tags
- customCoordinates
- isPrivateFile
- embeddedMetadata
- isPublished
- customMetadata
- metadata
- selectedFieldsSchema
description: 'Array of response field keys to include in the API response body.
'
example:
- tags
- customCoordinates
- isPrivateFile
extensions:
$ref: '#/components/schemas/Extensions'
webhookUrl:
type: string
format: uri
description: 'The final status of extensions after they have completed execution will be delivered to this endpoint as a POST request. [Learn more](/docs/api-reference/digital-asset-management-dam/managing-assets/update-file-details#webhook-payload-structure) about the webhook payload structure.
'
overwriteFile:
type: boolean
default: true
description: 'If `false` and `useUniqueFileName` is also `false`, and a file already exists at the exact location, upload API will return an error immediately.
'
overwriteAITags:
type: boolean
default: true
description: '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:
type: boolean
default: true
description: 'If the request does not have `tags`, and a file already exists at the exact location, existing tags will be removed.
'
overwriteCustomMetadata:
type: boolean
default: true
description: 'If the request does not have `customMetadata`, and a file already exists at the exact location, existing customMetadata will be removed.
'
customMetadata:
type: object
additionalProperties: true
description: 'JSON key-value pairs to associate with the asset. Create the custom metadata fields before setting these values.
'
example:
brand: Nike
color: red
transformation:
type: object
$ref: '#/components/schemas/TransformationObject'
checks:
type: string
description: 'Server-side checks to run on the asset.
Read more about [Upload API checks](/docs/api-reference/upload-file/upload-file-v2#upload-api-checks).
'
example: '"request.folder" : "marketing/"
'
description:
type: string
description: 'Optional text to describe the contents of the file.
'
example: Running shoes
AITasksExtension:
title: AI Tasks
type: object
required:
- name
- tasks
properties:
name:
type: string
description: Specifies the AI tasks extension for automated image analysis using AI models.
enum:
- ai-tasks
tasks:
type: array
minItems: 1
maxItems: 10
description: Array of task objects defining AI operations to perform on the asset.
items:
discriminator:
propertyName: type
oneOf:
- $ref: '#/components/schemas/AITaskSelectTags'
- $ref: '#/components/schemas/AITaskSelectMetadata'
- $ref: '#/components/schemas/AITaskYesNo'
Thumbnail:
description: Object containing Thumbnail information.
type: object
additionalProperties: true
properties:
Compression:
type: integer
XResolution:
type: number
YResolution:
type: number
ResolutionUnit:
type: integer
ThumbnailOffset:
type: integer
ThumbnailLength:
type: integer
Upload:
description: Object containing details of a successful upload.
type: object
properties:
fileId:
type: string
description: Unique fileId. Store this fileld in your database, as this will be used to perform update action on this file.
name:
type: string
description: Name of the asset.
filePath:
type: string
description: The relative path of the file in the media library e.g. `/marketing-assets/new-banner.jpg`.
url:
type: string
description: A publicly accessible URL of the file.
thumbnailUrl:
type: string
description: In the case of an image, a small thumbnail URL.
height:
type: number
description: Height of the image in pixels (Only for images)
width:
type: number
description: Width of the image in pixels (Only for Images)
size:
type: number
description: Size of the image file in Bytes.
bitRate:
type: integer
description: The bit rate of the video in kbps (only for video).
duration:
type: integer
description: The duration of the video in seconds (only for video).
audioCodec:
type: string
description: The audio codec used in the video (only for video).
videoCodec:
type: string
description: The video codec used in the video (only for video).
tags:
type: array
items:
type: string
description: The array of tags associated with the asset. If no tags are set, it will be `null`. Send `tags` in `responseFields` in API request to get the value of this field.
AITags:
type: array
items:
$ref: '#/components/schemas/AITag'
description: 'An array of tags assigned to the uploaded file by auto tagging.
'
versionInfo:
$ref: '#/components/schemas/VersionInfo'
isPrivateFile:
type: boolean
description: 'Is the file marked as private. It can be either `true` or `false`. Send `isPrivateFile` in `responseFields` in API request to get the value of this field.
'
isPublished:
# --- truncated at 32 KB (72 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/imagekit/refs/heads/main/openapi/imagekit-upload-file-api-openapi.yml