Pre & Post-upload transformations

Using ImageKit.io, you can specify pre-transformations and post-transformations on image or video files at the time of upload.

Pre-transformations lets you modify image or video files before they're uploaded.

Post-transformations help you eagerly generate transformations after an image or video file has been uploaded to ensure fast delivery to your users.

A pre-transformation is applied before the file is uploaded to ImageKit's Media Library. You can only request a single pre-transformation on an asset.

Some things you can use a pre-transformation for:

• Features like PNG compression to upload smaller files & save on storage costs.
• Change the height or width of an image or video file
• Add some text or logo to an image (using overlays on Image) or a video (using overlays on Video).
• Trim a video to a max duration.
• Crop a profile image uploaded by a user.

A post-transformation is applied after a file has been successfully in the Media Library. You can request multiple post-transformations on an asset.

These transformations are uploaded in addition to the original asset.

Note: ImageKit also generates transformations for images and videos when accessed via their transformed URL for the first time. This is the default way to deliver transformed assets on websites and apps. You should use post-transformations only to generate complex transforms for large files readily available for fast delivery or to store the transforms permanently in the Media Library.

Some things you can use post-transformations for:

• Keeping the thumbnail ready for a video.
• Using Adaptive Bitrate Streaming to eagerly generate the best video streams for various devices.
• Create images with high DPR (device pixel ratio) for premium mobile devices.

Supported types of post-transformations:

• For Images

  • transformation : See Image Transformations.
  • gif-to-video : (Only applicable for GIF files) See GIF to MP4.

• For Videos

  • abs : See Adaptive Bitrate Streaming.
  • thumbnail : See Get thumbnail from a video.
  • transformation : For all transformations in Video Transformations except ABS & thumbnail.

During an Upload API call, specify a pre-transformation or post-transformations under the transformation request parameter.

The transformation parameter for the Upload API is an object with the following properties:

Note: A single pre-transformation is allowed per file, but you can combine multiple parameters (separated by commas) in the pre-transformation string.

For an example, if you want to modify a video to have height as 300px, width as 400px & have a 5px red border before it's uploaded, you can specify h-300,w-400,b-5_red in the pre request parameter.

Example of a request with a pre-transformation:

// Request Body (multipart/form-data) for Upload API
{
    /*
   ...rest of the Upload API request parameters
   */
    "transformation": {
        "pre": "rt-90"
    }
}

Example of a request with multiple post-transformations:

// Request Body (multipart/form-data) for Upload API
{
    /*
   ...rest of the Upload API request parameters
   */
    "transformation": {
        "post": [
            {
                "type": "abs",
                "value: "sr-240_360_480_720_1080",
                "protocol": "dash"
            },
            {
                "type": "transformation",
                "value": "h-300"
            }
        ]
    }
}

You can also combine pre-transformations and post-transformations in a single request. For example, we have a request with a pre-transformation to change a video's andto "500px" & then eagerly generate a thumbnail for it using a post-transformation.

// Request Body (multipart/form-data) for Upload API
{
    /*
   ...rest of the Upload API request parameters
   */
    "transformation": {
        "pre": "w-500",
        "post": [
            {
                "type": "thumbnail"
            }
        ]
    }
}

Note: Don't forget to stringify the contents of the post property before making a request.

• Post-transformations are always async.
• Pre-transformation is sync for image files but async for video files.

You can use webhooks to receive success and failure event notifications for pre & post-transformations after they complete execution.

You can integrate these events in your media workflow to ensure that a pre- or post-transformation happens as requested.

• upload.pre-transform.success
• upload.pre-transform.error

This event is triggered when a pre-transform happens successfully.

Example payload looks like below:

{
    "type": "upload.pre-transform.success",
    "id": "c9a09db9-b5e2-49ed-ac2d-dfac88a6457a",
    "created_at": "2023-10-30T14:44:08.165Z",
    "request": {
        "x_request_id": "1bfe7bb6-afb3-4ccf-81f2-6bef7dae48e9",
        "transformation": "rt-90"
    },
    "data": {
        "fileId": "6540dbea002322e4ebe30de2",
        "name": "image_iEyH1dQme.jpg",
        "size": 2300818,
        "versionInfo": {
            "id": "6540dbea002322e4ebe30de2",
            "name": "Version 1"
        },
        "filePath": "/image_iEyH1dQme.jpg",
        "url": "https://stage-ik.imagekit.io/demo/image_iEyH1dQme.jpg",
        "fileType": "image",
        "height": 4608,
        "width": 3456,
        "thumbnailUrl": "https://stage-ik.imagekit.io/demo/tr:n-ik_ml_thumbnail/image_iEyH1dQme.jpg",
        "AITags": null
    }
}

Here is the description of all fields.

Triggered if an error occurs during the pre-transformation. If you face any unexpected errors, contact our support team.

Example payload looks like below:

{
    "type": "upload.pre-transform.error",
    "id": "502d1c52-e750-4277-8b64-52d43c2ec022",
    "created_at": "2023-10-31T13:49:28.046Z",
    "request": {
        "x_request_id": "722809dc-d6b7-4357-9262-74cdce554350",
        "transformation": "so-70"
    },
    "data": {
        "name": "vid_aKyz6pCpi.mp4",
        "path": "/myfolder/vid_aKyz6pCpi.mp4",
        "transformation": {
            "error": {
                "reason": "encoding_failed"
            }
        }
    }
}

Here is the description of all fields.

• upload.post-transform.success
• upload.post-transform.error

This event is triggered when a post-transform happens successfully. Note that each post-transformation will have it's separate webhook sent.

Example payload looks like below:

{
    "type": "upload.post-transform.success",
    "id": "08c12452-1efb-4c35-a28d-378c94e5674b",
    "created_at": "2023-10-30T15:04:59.462Z",
    "request": {
        "x_request_id": "0658b87f-bce3-41ae-8075-ebc26f44ff30",
        "transformation": {
            "type": "transformation",
            "value": "rt-90"
        }
    },
    "data": {
        "fileId": "653fc60e002322e4ebd5b5b7",
        "url": "http://stage-ik.imagekit.io/demo/video_wCqv9BewP.mp4?tr=rt-90",
        "name": "video_wCqv9BewP.mp4"
    }
}

Here is the description of all fields.

Triggered if an error occurs during the pre-transformation. If you face any unexpected errors, contact our support team.

Example payload looks like below:

{
    "type": "upload.post-transform.error",
    "id": "738f13b0-05e9-40cd-a856-8cc3e48b6e94",
    "created_at": "2023-10-31T13:51:10.627Z",
    "request": {
        "x_request_id": "49022ce9-e532-4a6c-8321-52925d519eec",
        "transformation": {
            "type": "transformation",
            "value": "so-70"
        }
    },
    "data": {
        "fileId": "65410644002322e4ebe6c880",
        "url": "http://stage-ik.imagekit.io/demo/vid_93HC1Daow.mp4?tr=so-70",
        "name": "vid_93HC1Daow.mp4",
        "path": "/vid_93HC1Daow.mp4",
        "transformation": {
            "error": {
                "reason": "encoding_failed"
            }
        }
    }
}

Here is the description of all fields.