ImageKit Upload File API

openapi: 3.0.3
info:
  title: ImageKit Account Management API 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:
    RemovedotBGExtension:
      title: Remove background
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: Specifies the background removal extension.
          enum:
          - remove-bg
        options:
          type: object
          properties:
            add_shadow:
              type: boolean
              description: 'Whether to add an artificial shadow to the result. Default is false. Note: Adding shadows is currently only supported for car photos.

                '
              default: false
            semitransparency:
              type: boolean
              description: 'Allows semi-transparent regions in the result. Default is true. Note: Semitransparency is currently only supported for car windows.

                '
              default: true
            bg_color:
              type: string
              description: 'Specifies a solid color background using hex code (e.g., "81d4fa", "fff") or color name (e.g., "green"). If this parameter is set, `bg_image_url` must be empty.

                '
            bg_image_url:
              type: string
              description: 'Sets a background image from a URL. If this parameter is set, `bg_color` must be empty.

                '
    Gps:
      description: Object containing GPS information.
      type: object
      additionalProperties: true
      properties:
        GPSVersionID:
          type: array
          items:
            type: integer
        GPSLatitudeRef:
          type: string
        GPSLatitude:
          type: array
          items:
            type: number
        GPSLongitudeRef:
          type: string
        GPSLongitude:
          type: array
          items:
            type: number
        GPSAltitudeRef:
          type: integer
        GPSAltitude:
          type: number
        GPSTimeStamp:
          type: array
          items:
            type: number
        GPSImgDirectionRef:
          type: string
        GPSImgDirection:
          type: number
        GPSDateStamp:
          type: string
    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
    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.
    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
    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.
    AITaskAction:
      title: AI Task Action
      type: object
      description: Defines actions to perform based on AI task results.
      properties:
        add_tags:
          type: array
          description: Array of tag strings to add to the asset.
          items:
            type: string
          example:
          - luxury
          - premium
        remove_tags:
          type: array
          description: Array of tag strings to remove from the asset.
          items:
            type: string
          example:
          - budget
          - affordable
        set_metadata:
          type: array
          description: Array of custom metadata field updates.
          items:
            type: object
            required:
            - field
            - value
            properties:
              field:
                type: string
                description: Name of the custom metadata field to set.
              value:
                description: Value to set for the custom metadata field. The value type should match the custom metadata field type.
                oneOf:
                - type: string
                - type: number
                - type: boolean
                - type: array
                  x-stainless-variantName: Mixed
                  title: Mixed
                  items:
                    title: Metadata value item
                    oneOf:
                    - type: string
                    - type: number
                    - type: boolean
          example:
          - field: price_range
            value: premium
        unset_metadata:
          type: array
          description: Array of custom metadata fields to remove.
          items:
            type: object
            required:
            - field
            properties:
              field:
                type: string
                description: Name of the custom metadata field to remove.
          example:
          - field: price_range
    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
    AITaskSelectMetadata:
      title: AI Task - Select Metadata
      type: object
      required:
      - type
      - instruction
      - field
      properties:
        type:
          type: string
          description: Task type that analyzes the image and sets a custom metadata field value from a vocabulary.
          enum:
          - select_metadata
        instruction:
          type: string
          minLength: 1
          maxLength: 2000
          description: The question or instruction for the AI to analyze the image.
          example: What is the primary color of the clothing?
        field:
          type: string
          description: Name of the custom metadata field to set. The field must exist in your account.
          example: primary_color
        vocabulary:
          type: array
          minItems: 1
          maxItems: 30
          description: An array of possible values matching the custom metadata field type. If not provided for SingleSelect or MultiSelect field types, all values from the custom metadata field definition will be used. When providing large vocabularies (above 30 items), the AI may not strictly adhere to the list.
          items:
            oneOf:
            - type: string
            - type: number
            - type: boolean
          example:
          - red
          - blue
          - green
          - black
          - white
        min_selections:
          type: integer
          minimum: 0
          description: Minimum number of values to select from the vocabulary.
        max_selections:
          type: integer
          minimum: 1
          description: Maximum number of values to select from the vocabulary.
    Metadata:
      description: JSON object containing metadata.
      type: object
      additionalProperties: true
      properties:
        height:
          type: integer
          description: The height of the image or video in pixels.
        width:
          type: integer
          description: The width of the image or video in pixels.
        size:
          type: integer
          description: The file size in bytes.
        format:
          type: string
          description: The format of the file (e.g., 'jpg', 'mp4').
        hasColorProfile:
          type: boolean
          description: Indicates if the image has a color profile.
        quality:
          type: integer
          description: The quality indicator of the image.
        density:
          type: integer
          description: The density of the image in DPI.
        hasTransparency:
          type: boolean
          description: Indicates if the image contains transparent areas.
        pHash:
          type: string
          description: Perceptual hash of the image.
        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).
        exif:
          type: object
          additionalProperties: true
          properties:
            image:
              $ref: '#/components/schemas/ExifImage'
            thumbnail:
              $ref: '#/components/schemas/Thumbnail'
            exif:
              $ref: '#/components/schemas/ExifDetails'
            gps:
              $ref: '#/components/schemas/Gps'
            interoperability:
              $ref: '#/components/schemas/Interoperability'
            makernote:
              type: object
              additionalProperties: true
    CustomMetadata:
      type: object
      description: 'A key-value data associated with the asset.

        '
      additionalProperties: true
    EmbeddedMetadata:
      type: object
      additionalProperties: true
      description: Consolidated embedded metadata associated with the file. It includes exif, iptc, and xmp data.
    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:
             

# --- truncated at 32 KB (72 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/apis-json-v1-9-imagekit/refs/heads/main/openapi/imagekit-upload-file-api-openapi.yml