Getting started

Integration & migration

Image & video API

DAM user guide

API overview

Account

Pre & Post-upload transformations

Transform an image or a video before or immediately after uploading it to the ImageKit DAM.


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.

Pre-Transformation

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.

Post-Transformation

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:

Supported types of post-transformations:

How to Use Pre-Transformations and Post-Transformations?

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:

Field NameTypeRequiredDescription
prestring-Request parameter for Pre-Transformation
postarray of objects-Request parameter for Post-Transformation
post.typestringYesType of required post-transformation. Allowed Values: abs, thumbnail, transformation, gif-to-video
post.valuestringIf post.type is transformationValue of required post-transformation.
post.protocolstringIf post.type is absABS Streaming Protocol. Allowed Values: hls, dashSee Adaptive Bitrate Streaming for more details.

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:

Copy
// 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:

Copy
// 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.

Copy
// 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.

Asynchronous behaviour

  • 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.

Before receiving pre & post-transformation-related events, you must configure webhooks in your ImageKit account.

Pre-Transformation Events

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

upload.pre-transform.success

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

Example payload looks like below:

Copy
{
  "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.

FieldDescription
typeType of event.
idUnique identifier of the event.
createdAtTimestamp of the event in ISO8601 format.
request.x_request_idA unique request ID to identify the request.
request.transformationThe requested transformation as a string.
dataSame as the Upload API response. Refer Upload File API for the payload structure.

upload.pre-transform.error

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

Example payload looks like below:

Copy
{
  "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.

FieldDescription
typeType of event.
idUnique identifier of the event.
createdAtTimestamp of the event in ISO8601 format.
request.x_request_idA unique request ID to identify the request.
request.transformationThe requested transformation as a string.
data.nameName of the file.
data.pathPath of the file.
data.transformation.error.reasonReason for the post-transformation failing.

Post-transformation Events

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

upload.post-transform.success

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:

Copy
{
  "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.

FieldDescription
typeType of event.
idUnique identifier of the event.
createdAtTimestamp of the event in ISO8601 format.
request.x_request_idA unique request ID to identify the request.
request.transformation.typeType of the requested post-transformation. Can be transformation, abs, gif-to-video or thumbnail.
request.transformation.valueValue for the requested type of transformation.
request.transformation.protocolOnly applicable if request.transformation.type is abs. Possible values are hls, dash.
data.fileIdUnique ID of the originally saved file.
data.urlURL of the requested post-transformation.
data.nameName of the file.

upload.post-transform.error

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

Example payload looks like below:

Copy
{
  "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.

FieldDescription
typeType of event.
idUnique identifier of the event.
createdAtTimestamp of the event in ISO8601 format.
request.x_request_idA unique request ID to identify the request.
request.transformation.typeType of the requested post-transformation. Can be transformation, abs, gif-to-video or thumbnail.
request.transformation.valueValue for the requested type of transformation.
request.transformation.protocolOnly applicable if request.transformation.type is abs. Possible values are hls, dash.
data.fileIdUnique ID of the originally saved file.
data.urlURL of the requested post-transformation.
data.nameName of the file.
data.pathPath of the file.
data.transformation.error.reasonReason for the post-transformation failing.