From 879e057035c3504271a6cd39c3ca17fda406c7fd Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Fri, 16 Jan 2026 14:41:32 +0530 Subject: [PATCH 1/4] feat: add layer mode support in overlay transformations and update URL generation tests - Enhanced the `processOverlay` function to include a new `layerMode` property for overlays. - Updated the URL generation tests to include new transformation parameters such as `aiEdit`, `colorReplace`, and `distort`. - Added comprehensive tests for various layer modes (multiply, cutter, cutout, displace) to ensure correct URL generation. --- src/constants/supportedTransforms.ts | 4 + src/interfaces/Transformation.ts | 957 ++++++++++++++++----------- src/url.ts | 7 +- test/url-generation/basic.js | 8 +- test/url-generation/overlay.js | 71 ++ 5 files changed, 651 insertions(+), 396 deletions(-) diff --git a/src/constants/supportedTransforms.ts b/src/constants/supportedTransforms.ts index 8353ceb..aee5fe3 100644 --- a/src/constants/supportedTransforms.ts +++ b/src/constants/supportedTransforms.ts @@ -39,6 +39,7 @@ export const supportedTransforms: { [key: string]: string } = { aiVariation: "e-genvar", aiDropShadow: "e-dropshadow", aiChangeBackground: "e-changebg", + aiEdit: "e-edit", aiRemoveBackground: "e-bgremove", aiRemoveBackgroundExternal: "e-removedotbg", contrastStretch: "e-contrast", @@ -46,6 +47,8 @@ export const supportedTransforms: { [key: string]: string } = { sharpen: "e-sharpen", unsharpMask: "e-usm", gradient: "e-gradient", + colorReplace: "cr", + distort: "e-distort", // Other flags & finishing progressive: "pr", @@ -56,6 +59,7 @@ export const supportedTransforms: { [key: string]: string } = { trim: "t", zoom: "z", page: "pg", + layerMode: "lm", // Text overlay transformations which are not defined yet fontSize: "fs", diff --git a/src/interfaces/Transformation.ts b/src/interfaces/Transformation.ts index 6396b37..f517855 100644 --- a/src/interfaces/Transformation.ts +++ b/src/interfaces/Transformation.ts @@ -1,507 +1,587 @@ +/** + * By default, the transformation string is added as a query parameter in the URL, + * e.g., `?tr=w-100,h-100`. If you want to add the transformation string in the + * path of the URL, set this to `path`. Learn more in the + * [Transformations guide](https://imagekit.io/docs/transformations). + */ export type TransformationPosition = "path" | "query"; export type StreamingResolution = "240" | "360" | "480" | "720" | "1080" | "1440" | "2160"; /** - * The SDK provides easy-to-use names for transformations. These names are converted to the corresponding transformation string before being added to the URL. - * SDKs are updated regularly to support new transformations. If you want to use a transformation that is not supported by the SDK, - * You can use the `raw` parameter to pass the transformation string directly. - * - * [Transformations Documentation](https://imagekit.io/docs/transformations) + * The SDK provides easy-to-use names for transformations. These names are + * converted to the corresponding transformation string before being added to the + * URL. SDKs are updated regularly to support new transformations. If you want to + * use a transformation that is not supported by the SDK, You can use the `raw` + * parameter to pass the transformation string directly. See the + * [Transformations documentation](https://imagekit.io/docs/transformations). */ export interface Transformation { /** - * Specifies the width of the output. If a value between 0 and 1 is provided, it is treated as a percentage (e.g., `0.4` represents 40% of the original width). - * You can also supply arithmetic expressions (e.g., `iw_div_2`). - * - * Width transformation - [Images](https://imagekit.io/docs/image-resize-and-crop#width---w) | [Videos](https://imagekit.io/docs/video-resize-and-crop#width---w) + * Uses AI to change the background. Provide a text prompt or a base64-encoded + * prompt, e.g., `prompt-snow road` or `prompte-[urlencoded_base64_encoded_text]`. + * Not supported inside overlay. See + * [AI Change Background](https://imagekit.io/docs/ai-transformations#change-background-e-changebg). */ - width?: number | string; + aiChangeBackground?: string; /** - * Specifies the height of the output. If a value between 0 and 1 is provided, it is treated as a percentage (e.g., `0.5` represents 50% of the original height). - * You can also supply arithmetic expressions (e.g., `ih_mul_0.5`). - * - * Height transformation - [Images](https://imagekit.io/docs/image-resize-and-crop#height---h) | [Videos](https://imagekit.io/docs/video-resize-and-crop#height---h) + * Adds an AI-based drop shadow around a foreground object on a transparent or + * removed background. Optionally, control the direction, elevation, and saturation + * of the light source (e.g., `az-45` to change light direction). Pass `true` for + * the default drop shadow, or provide a string for a custom drop shadow. Supported + * inside overlay. See + * [AI Drop Shadow](https://imagekit.io/docs/ai-transformations#ai-drop-shadow-e-dropshadow). */ - height?: number | string; + aiDropShadow?: true | string; /** - * Specifies the aspect ratio for the output, e.g., "ar-4-3". Typically used with either width or height (but not both). - * For example: aspectRatio = `4:3`, `4_3`, or an expression like `iar_div_2`. - * - * [Image Resize and Crop - Aspect Ratio](https://imagekit.io/docs/image-resize-and-crop#aspect-ratio---ar) + * Uses AI to edit images based on a text prompt. Provide a text prompt or a + * base64-encoded prompt, e.g., `prompt-snow road` or + * `prompte-[urlencoded_base64_encoded_text]`. Not supported inside overlay. + * See [AI Edit](https://imagekit.io/docs/ai-transformations#edit-image-e-edit). */ - aspectRatio?: number | string; + aiEdit?: string; /** - * Specifies the background to be used in conjunction with certain cropping strategies when resizing an image. - * - A solid color: e.g., `red`, `F3F3F3`, `AAFF0010`. - * - * [Effects and Enhancements - Solid Color Background](https://imagekit.io/docs/effects-and-enhancements#solid-color-background) - * - * - A blurred background: e.g., `blurred`, `blurred_25_N15`, etc. - * - * [Effects and Enhancements - Blurred Background](https://imagekit.io/docs/effects-and-enhancements#blurred-background) - * - * - Expand the image boundaries using generative fill: `genfill`. Not supported inside overlay. Optionally, control the background scene by passing a text prompt: - * `genfill[:-prompt-${text}]` or `genfill[:-prompte-${urlencoded_base64_encoded_text}]`. - * - * [AI Transformations - Generative Fill Background](https://imagekit.io/docs/ai-transformations#generative-fill-bg-genfill) + * Applies ImageKit's in-house background removal. Supported inside overlay. See + * [AI Background Removal](https://imagekit.io/docs/ai-transformations#imagekit-background-removal-e-bgremove). */ - background?: string; + aiRemoveBackground?: true; /** - * Adds a border to the output media. Accepts a string in the format `_` - * (e.g., `5_FFF000` for a 5px yellow border), or an expression like `ih_div_20_FF00FF`. - * - * [Effects and Enhancements - Border](https://imagekit.io/docs/effects-and-enhancements#border---b) + * Uses third-party background removal. Note: It is recommended to use + * aiRemoveBackground, ImageKit's in-house solution, which is more cost-effective. + * Supported inside overlay. See + * [External Background Removal](https://imagekit.io/docs/ai-transformations#background-removal-e-removedotbg). */ - border?: string; + aiRemoveBackgroundExternal?: true; /** - * [Image Resize and Crop - Crop Modes](https://imagekit.io/docs/image-resize-and-crop#crop-crop-modes--focus) + * Performs AI-based retouching to improve faces or product shots. Not supported + * inside overlay. See + * [AI Retouch](https://imagekit.io/docs/ai-transformations#retouch-e-retouch). */ - crop?: "force" | "at_max" | "at_max_enlarge" | "at_least" | "maintain_ratio"; + aiRetouch?: true; /** - * [Image Resize and Crop - Crop Modes](https://imagekit.io/docs/image-resize-and-crop#crop-crop-modes--focus) + * Upscales images beyond their original dimensions using AI. Not supported inside + * overlay. See + * [AI Upscale](https://imagekit.io/docs/ai-transformations#upscale-e-upscale). */ - cropMode?: "pad_resize" | "extract" | "pad_extract"; + aiUpscale?: true; /** - * Accepts values between 0.1 and 5, or `auto` for automatic device pixel ratio (DPR) calculation. - * - * [Image Resize and Crop - DPR](https://imagekit.io/docs/image-resize-and-crop#dpr---dpr) + * Generates a variation of an image using AI. This produces a new image with + * slight variations from the original, such as changes in color, texture, and + * other visual elements, while preserving the structure and essence of the + * original image. Not supported inside overlay. See + * [AI Generate Variations](https://imagekit.io/docs/ai-transformations#generate-variations-of-an-image-e-genvar). */ - dpr?: number + aiVariation?: true; /** - * This parameter can be used with pad resize, maintain ratio, or extract crop to modify the padding or cropping behavior. - * - * [Image Resize and Crop - Focus](https://imagekit.io/docs/image-resize-and-crop#focus---fo) + * Specifies the aspect ratio for the output, e.g., "ar-4-3". Typically used with + * either width or height (but not both). For example: aspectRatio = `4:3`, `4_3`, + * or an expression like `iar_div_2`. See + * [Image resize and crop – Aspect ratio](https://imagekit.io/docs/image-resize-and-crop#aspect-ratio---ar). */ - focus?: string; + aspectRatio?: number | string; /** - * Specifies the quality of the output image for lossy formats such as JPEG, WebP, and AVIF. - * A higher quality value results in a larger file size with better quality, while a lower value produces a smaller file size with reduced quality. - * - * [Image Optimization - Quality](https://imagekit.io/docs/image-optimization#quality---q) + * Specifies the audio codec, e.g., `aac`, `opus`, or `none`. See + * [Audio codec](https://imagekit.io/docs/video-optimization#audio-codec---ac). */ - quality?: number; + audioCodec?: 'aac' | 'opus' | 'none'; /** - * [Image Resize and Crop - Focus Using Cropped Image Coordinates](https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates) + * Specifies the background to be used in conjunction with certain cropping + * strategies when resizing an image. + * + * - A solid color: e.g., `red`, `F3F3F3`, `AAFF0010`. See + * [Solid color background](https://imagekit.io/docs/effects-and-enhancements#solid-color-background). + * - Dominant color: `dominant` extracts the dominant color from the image. See + * [Dominant color background](https://imagekit.io/docs/effects-and-enhancements#dominant-color-background). + * - Gradient: `gradient_dominant` or `gradient_dominant_2` creates a gradient + * using the dominant colors. Optionally specify palette size (2 or 4), e.g., + * `gradient_dominant_4`. See + * [Gradient background](https://imagekit.io/docs/effects-and-enhancements#gradient-background). + * - A blurred background: e.g., `blurred`, `blurred_25_N15`, etc. See + * [Blurred background](https://imagekit.io/docs/effects-and-enhancements#blurred-background). + * - Expand the image boundaries using generative fill: `genfill`. Not supported + * inside overlay. Optionally, control the background scene by passing a text + * prompt: `genfill[:-prompt-${text}]` or + * `genfill[:-prompte-${urlencoded_base64_encoded_text}]`. See + * [Generative fill background](https://imagekit.io/docs/ai-transformations#generative-fill-bg-genfill). */ - x?: number | string; + background?: string; /** - * [Image Resize and Crop - Focus Using Cropped Image Coordinates](https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates) + * Specifies the Gaussian blur level. Accepts an integer value between 1 and 100, + * or an expression like `bl-10`. See + * [Blur](https://imagekit.io/docs/effects-and-enhancements#blur---bl). */ - xCenter?: number | string; + blur?: number; /** - * [Image Resize and Crop - Focus Using Cropped Image Coordinates](https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates) + * Adds a border to the output media. Accepts a string in the format + * `_` (e.g., `5_FFF000` for a 5px yellow border), or an + * expression like `ih_div_20_FF00FF`. See + * [Border](https://imagekit.io/docs/effects-and-enhancements#border---b). */ - y?: number | string; + border?: string; /** - * [Image Resize and Crop - Focus Using Cropped Image Coordinates](https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates) + * Indicates whether the output image should retain the original color profile. See + * [Color profile](https://imagekit.io/docs/image-optimization#color-profile---cp). */ - yCenter?: number | string; + colorProfile?: boolean; /** - * Specifies the output format for images or videos, e.g., `jpg`, `png`, `webp`, `mp4`, or `auto`. - * You can also pass `orig` for images to return the original format. - * ImageKit automatically delivers images and videos in the optimal format based on device support unless overridden by the dashboard settings or the format parameter. - * - * [Image Optimization - Format](https://imagekit.io/docs/image-optimization#format---f) & [Video Optimization - Format](https://imagekit.io/docs/video-optimization#format---f) + * Replaces colors in the image. Supports three formats: + * + * - `toColor` - Replace dominant color with the specified color. + * - `toColor_tolerance` - Replace dominant color with specified tolerance (0-100). + * - `toColor_tolerance_fromColor` - Replace a specific color with another within + * tolerance range. Colors can be hex codes (e.g., `FF0022`) or names (e.g., + * `red`, `blue`). See + * [Color replacement](https://imagekit.io/docs/effects-and-enhancements#color-replace---cr). */ - format?: "auto" | "webp" | "jpg" | "jpeg" | "png" | "gif" | "svg" | "mp4" | "webm" | "avif" | "orig"; + colorReplace?: string; /** - * Specifies the video codec, e.g., `h264`, `vp9`, `av1`, or `none`. - * - * [Video Optimization - Video Codec](https://imagekit.io/docs/video-optimization#video-codec---vc) + * Automatically enhances the contrast of an image (contrast stretch). See + * [Contrast Stretch](https://imagekit.io/docs/effects-and-enhancements#contrast-stretch---e-contrast). */ - videoCodec?: "h264" | "vp9" | "av1" | "none"; + contrastStretch?: true; /** - * Specifies the audio codec, e.g., `aac`, `opus`, or `none`. - * - * [Video Optimization - Audio Codec](https://imagekit.io/docs/video-optimization#audio-codec---ac) + * Crop modes for image resizing. See + * [Crop modes & focus](https://imagekit.io/docs/image-resize-and-crop#crop-crop-modes--focus). */ - audioCodec?: "aac" | "opus" | "none"; + crop?: 'force' | 'at_max' | 'at_max_enlarge' | 'at_least' | 'maintain_ratio'; /** - * Specifies the corner radius for rounded corners (e.g., 20) or `max` for circular/oval shapes. - * - * [Effects and Enhancements - Radius](https://imagekit.io/docs/effects-and-enhancements#radius---r) + * Additional crop modes for image resizing. See + * [Crop modes & focus](https://imagekit.io/docs/image-resize-and-crop#crop-crop-modes--focus). */ - radius?: number | "max"; + cropMode?: 'pad_resize' | 'extract' | 'pad_extract'; /** - * Specifies the rotation angle in degrees. Positive values rotate the image clockwise; you can also use, for example, `N40` for counterclockwise rotation - * or `auto` to use the orientation specified in the image's EXIF data. - * For videos, only the following values are supported: 0, 90, 180, 270, or 360. - * - * [Effects and Enhancements - Rotate](https://imagekit.io/docs/effects-and-enhancements#rotate---rt) + * Specifies a fallback image if the resource is not found, e.g., a URL or file + * path. See + * [Default image](https://imagekit.io/docs/image-transformation#default-image---di). */ - rotation?: number | string; + defaultImage?: string; /** - * Specifies the Gaussian blur level. Accepts an integer value between 1 and 100, or an expression like `bl-10`. - * - * [Effects and Enhancements - Blur](https://imagekit.io/docs/effects-and-enhancements#blur---bl) + * Distorts the shape of an image. Supports two modes: + * + * - Perspective distortion: `p-x1_y1_x2_y2_x3_y3_x4_y4` changes the position of + * the four corners starting clockwise from top-left. + * - Arc distortion: `a-degrees` curves the image upwards (positive values) or + * downwards (negative values). See + * [Distort effect](https://imagekit.io/docs/effects-and-enhancements#distort---e-distort). */ - blur?: number; + distort?: string; /** - * [Transformations - Named Transformations](https://imagekit.io/docs/transformations#named-transformations) + * Accepts values between 0.1 and 5, or `auto` for automatic device pixel ratio + * (DPR) calculation. Also accepts arithmetic expressions. + * + * - Learn about + * [Arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations). + * - See [DPR](https://imagekit.io/docs/image-resize-and-crop#dpr---dpr). */ - named?: string; + dpr?: number; /** - * Specifies a fallback image if the resource is not found, e.g., a URL or file path. - * - * [Image Transformation - Default Image](https://imagekit.io/docs/image-transformation#default-image---di) + * Specifies the duration (in seconds) for trimming videos, e.g., `5` or `10.5`. + * Typically used with startOffset to indicate the length from the start offset. + * Arithmetic expressions are supported. See + * [Trim videos – Duration](https://imagekit.io/docs/trim-videos#duration---du). */ - defaultImage?: string; + duration?: number | string; /** - * Flips or mirrors an image either horizontally, vertically, or both. - * Acceptable values: `h` (horizontal), `v` (vertical), `h_v` (horizontal and vertical), or `v_h`. - * - * [Effects and Enhancements - Flip](https://imagekit.io/docs/effects-and-enhancements#flip---fl) + * Specifies the end offset (in seconds) for trimming videos, e.g., `5` or `10.5`. + * Typically used with startOffset to define a time window. Arithmetic expressions + * are supported. See + * [Trim videos – End offset](https://imagekit.io/docs/trim-videos#end-offset---eo). */ - flip?: "h" | "v" | "h_v" | "v_h"; + endOffset?: number | string; /** - * If set to true, serves the original file without applying any transformations. - * - * [Core Delivery Features - Deliver Original File As Is](https://imagekit.io/docs/core-delivery-features#deliver-original-file-as-is---orig-true) + * Flips or mirrors an image either horizontally, vertically, or both. Acceptable + * values: `h` (horizontal), `v` (vertical), `h_v` (horizontal and vertical), or + * `v_h`. See [Flip](https://imagekit.io/docs/effects-and-enhancements#flip---fl). */ - original?: boolean; + flip?: 'h' | 'v' | 'h_v' | 'v_h'; /** - * Specifies the start offset (in seconds) for trimming videos, e.g., `5` or `10.5`. - * Arithmetic expressions are also supported. - * - * [Trim Videos - Start Offset](https://imagekit.io/docs/trim-videos#start-offset---so) + * Refines padding and cropping behavior for pad resize, maintain ratio, and + * extract crop modes. Supports manual positions and coordinate-based focus. With + * AI-based cropping, you can automatically keep key subjects in frame—such as + * faces or detected objects (e.g., `fo-face`, `fo-person`, `fo-car`)— while + * resizing. + * + * - See [Focus](https://imagekit.io/docs/image-resize-and-crop#focus---fo). + * - [Object aware cropping](https://imagekit.io/docs/image-resize-and-crop#object-aware-cropping---fo-object-name) */ - startOffset?: number | string; + focus?: string; /** - * Specifies the end offset (in seconds) for trimming videos, e.g., `5` or `10.5`. - * Typically used with startOffset to define a time window. Arithmetic expressions are supported. - * - * [Trim Videos - End Offset](https://imagekit.io/docs/trim-videos#end-offset---eo) + * Specifies the output format for images or videos, e.g., `jpg`, `png`, `webp`, + * `mp4`, or `auto`. You can also pass `orig` for images to return the original + * format. ImageKit automatically delivers images and videos in the optimal format + * based on device support unless overridden by the dashboard settings or the + * format parameter. See + * [Image format](https://imagekit.io/docs/image-optimization#format---f) and + * [Video format](https://imagekit.io/docs/video-optimization#format---f). */ - endOffset?: number | string; + format?: 'auto' | 'webp' | 'jpg' | 'jpeg' | 'png' | 'gif' | 'svg' | 'mp4' | 'webm' | 'avif' | 'orig'; /** - * Specifies the duration (in seconds) for trimming videos, e.g., `5` or `10.5`. - * Typically used with startOffset to indicate the length from the start offset. Arithmetic expressions are supported. - * - * [Trim Videos - Duration](https://imagekit.io/docs/trim-videos#duration---du) + * Creates a linear gradient with two colors. Pass `true` for a default gradient, + * or provide a string for a custom gradient. See + * [Gradient](https://imagekit.io/docs/effects-and-enhancements#gradient---e-gradient). */ - duration?: number | string; + gradient?: true | string; /** - * An array of resolutions for adaptive bitrate streaming, e.g., [`240`, `360`, `480`, `720`, `1080`]. - * - * [Adaptive Bitrate Streaming](https://imagekit.io/docs/adaptive-bitrate-streaming) + * Enables a grayscale effect for images. See + * [Grayscale](https://imagekit.io/docs/effects-and-enhancements#grayscale---e-grayscale). */ - streamingResolutions?: StreamingResolution[]; + grayscale?: true; /** - * Enables a grayscale effect for images. - * - * [Effects and Enhancements - Grayscale](https://imagekit.io/docs/effects-and-enhancements#grayscale---e-grayscale) + * Specifies the height of the output. If a value between 0 and 1 is provided, it + * is treated as a percentage (e.g., `0.5` represents 50% of the original height). + * You can also supply arithmetic expressions (e.g., `ih_mul_0.5`). Height + * transformation – + * [Images](https://imagekit.io/docs/image-resize-and-crop#height---h) · + * [Videos](https://imagekit.io/docs/video-resize-and-crop#height---h) */ - grayscale?: true; + height?: number | string; /** - * Upscales images beyond their original dimensions using AI. Not supported inside overlay. - * - * [AI Transformations - Upscale](https://imagekit.io/docs/ai-transformations#upscale-e-upscale) + * Specifies whether the output image (in JPEG or PNG) should be compressed + * losslessly. See + * [Lossless compression](https://imagekit.io/docs/image-optimization#lossless-webp-and-png---lo). */ - aiUpscale?: true + lossless?: boolean; /** - * Performs AI-based retouching to improve faces or product shots. Not supported inside overlay. - * - * [AI Transformations - Retouch](https://imagekit.io/docs/ai-transformations#retouch-e-retouch) + * By default, ImageKit removes all metadata during automatic image compression. + * Set this to true to preserve metadata. See + * [Image metadata](https://imagekit.io/docs/image-optimization#image-metadata---md). */ - aiRetouch?: true + metadata?: boolean; /** - * Generates a variation of an image using AI. This produces a new image with slight variations from the original, - * such as changes in color, texture, and other visual elements, while preserving the structure and essence of the original image. Not supported inside overlay. - * - * [AI Transformations - Generate Variations](https://imagekit.io/docs/ai-transformations#generate-variations-of-an-image-e-genvar) + * Named transformation reference. See + * [Named transformations](https://imagekit.io/docs/transformations#named-transformations). */ - aiVariation?: true + named?: string; /** - * Adds an AI-based drop shadow around a foreground object on a transparent or removed background. - * Optionally, control the direction, elevation, and saturation of the light source (e.g., `az-45` to change light direction). - * Pass `true` for the default drop shadow, or provide a string for a custom drop shadow. - * Supported inside overlay. - * - * [AI Transformations - Drop Shadow](https://imagekit.io/docs/ai-transformations#ai-drop-shadow-e-dropshadow) + * Specifies the opacity level of the output image. See + * [Opacity](https://imagekit.io/docs/effects-and-enhancements#opacity---o). */ - aiDropShadow?: true | string + opacity?: number; /** - * Uses AI to change the background. Provide a text prompt or a base64-encoded prompt, - * e.g., `prompt-snow road` or `prompte-[urlencoded_base64_encoded_text]`. - * Not supported inside overlay. - * - * [AI Transformations - Change Background](https://imagekit.io/docs/ai-transformations#change-background-e-changebg) + * If set to true, serves the original file without applying any transformations. + * See + * [Deliver original file as-is](https://imagekit.io/docs/core-delivery-features#deliver-original-file-as-is---orig-true). */ - aiChangeBackground?: string; + original?: boolean; /** - * Applies ImageKit’s in-house background removal. - * Supported inside overlay. - * - * [AI Transformations - Background Removal](https://imagekit.io/docs/ai-transformations#imagekit-background-removal-e-bgremove) + * Specifies an overlay to be applied on the parent image or video. ImageKit + * supports overlays including images, text, videos, subtitles, and solid colors. + * See + * [Overlay using layers](https://imagekit.io/docs/transformations#overlay-using-layers). */ - aiRemoveBackground?: true + overlay?: Overlay; /** - * Uses third-party background removal. - * Note: It is recommended to use aiRemoveBackground, ImageKit’s in-house solution, which is more cost-effective. - * Supported inside overlay. - * - * [AI Transformations - External Background Removal](https://imagekit.io/docs/ai-transformations#background-removal-e-removedotbg) + * Extracts a specific page or frame from multi-page or layered files (PDF, PSD, + * AI). For example, specify by number (e.g., `2`), a range (e.g., `3-4` for the + * 2nd and 3rd layers), or by name (e.g., `name-layer-4` for a PSD layer). See + * [Thumbnail extraction](https://imagekit.io/docs/vector-and-animated-images#get-thumbnail-from-psd-pdf-ai-eps-and-animated-files). */ - aiRemoveBackgroundExternal?: true + page?: number | string; /** - * Automatically enhances the contrast of an image (contrast stretch). - * - * [Effects and Enhancements - Contrast Stretch](https://imagekit.io/docs/effects-and-enhancements#contrast-stretch---e-contrast) + * Specifies whether the output JPEG image should be rendered progressively. + * Progressive loading begins with a low-quality, pixelated version of the full + * image, which gradually improves to provide a faster perceived load time. See + * [Progressive images](https://imagekit.io/docs/image-optimization#progressive-image---pr). */ - contrastStretch?: true + progressive?: boolean; /** - * Adds a shadow beneath solid objects in an image with a transparent background. - * For AI-based drop shadows, refer to aiDropShadow. - * Pass `true` for a default shadow, or provide a string for a custom shadow. - * - * [Effects and Enhancements - Shadow](https://imagekit.io/docs/effects-and-enhancements#shadow---e-shadow) + * Specifies the quality of the output image for lossy formats such as JPEG, WebP, + * and AVIF. A higher quality value results in a larger file size with better + * quality, while a lower value produces a smaller file size with reduced quality. + * See [Quality](https://imagekit.io/docs/image-optimization#quality---q). */ - shadow?: true | string + quality?: number; /** - * Sharpens the input image, highlighting edges and finer details. - * Pass `true` for default sharpening, or provide a numeric value for custom sharpening. - * - * [Effects and Enhancements - Sharpen](https://imagekit.io/docs/effects-and-enhancements#sharpen---e-sharpen) + * Specifies the corner radius for rounded corners. + * + * - Single value (positive integer): Applied to all corners (e.g., `20`). + * - `max`: Creates a circular or oval shape. + * - Per-corner array: Provide four underscore-separated values representing + * top-left, top-right, bottom-right, and bottom-left corners respectively (e.g., + * `10_20_30_40`). See + * [Radius](https://imagekit.io/docs/effects-and-enhancements#radius---r). */ - sharpen?: true | number + radius?: number | 'max' | string; /** - * Applies Unsharp Masking (USM), an image sharpening technique. - * Pass `true` for a default unsharp mask, or provide a string for a custom unsharp mask. - * - * [Effects and Enhancements - Unsharp Mask](https://imagekit.io/docs/effects-and-enhancements#unsharp-mask---e-usm) + * Pass any transformation not directly supported by the SDK. This transformation + * string is appended to the URL as provided. */ - unsharpMask?: true | string; + raw?: string; /** - * Creates a linear gradient with two colors. Pass `true` for a default gradient, or provide a string for a custom gradient. - * - * [Effects and Enhancements - Gradient](https://imagekit.io/docs/effects-and-enhancements#gradient---e-gradient) + * Specifies the rotation angle in degrees. Positive values rotate the image + * clockwise; you can also use, for example, `N40` for counterclockwise rotation or + * `auto` to use the orientation specified in the image's EXIF data. For videos, + * only the following values are supported: 0, 90, 180, 270, or 360. See + * [Rotate](https://imagekit.io/docs/effects-and-enhancements#rotate---rt). */ - gradient?: true | string; + rotation?: number | string; /** - * Specifies whether the output JPEG image should be rendered progressively. Progressive loading begins with a low-quality, - * pixelated version of the full image, which gradually improves to provide a faster perceived load time. - * - * [Image Optimization - Progressive Image](https://imagekit.io/docs/image-optimization#progressive-image---pr) + * Adds a shadow beneath solid objects in an image with a transparent background. + * For AI-based drop shadows, refer to aiDropShadow. Pass `true` for a default + * shadow, or provide a string for a custom shadow. See + * [Shadow](https://imagekit.io/docs/effects-and-enhancements#shadow---e-shadow). */ - progressive?: boolean; + shadow?: true | string; /** - * Specifies whether the output image (in JPEG or PNG) should be compressed losslessly. - * - * [Image Optimization - Lossless Compression](https://imagekit.io/docs/image-optimization#lossless-webp-and-png---lo) + * Sharpens the input image, highlighting edges and finer details. Pass `true` for + * default sharpening, or provide a numeric value for custom sharpening. See + * [Sharpen](https://imagekit.io/docs/effects-and-enhancements#sharpen---e-sharpen). */ - lossless?: boolean + sharpen?: true | number; /** - * Indicates whether the output image should retain the original color profile. - * - * [Image Optimization - Color Profile](https://imagekit.io/docs/image-optimization#color-profile---cp) + * Specifies the start offset (in seconds) for trimming videos, e.g., `5` or + * `10.5`. Arithmetic expressions are also supported. See + * [Trim videos – Start offset](https://imagekit.io/docs/trim-videos#start-offset---so). */ - colorProfile?: boolean; + startOffset?: number | string; /** - * By default, ImageKit removes all metadata during automatic image compression. - * Set this to true to preserve metadata. - * - * [Image Optimization - Image Metadata](https://imagekit.io/docs/image-optimization#image-metadata---md) + * An array of resolutions for adaptive bitrate streaming, e.g., [`240`, `360`, + * `480`, `720`, `1080`]. See + * [Adaptive Bitrate Streaming](https://imagekit.io/docs/adaptive-bitrate-streaming). */ - metadata?: boolean; + streamingResolutions?: Array; /** - * Specifies the opacity level of the output image. - * - * [Effects and Enhancements - Opacity](https://imagekit.io/docs/effects-and-enhancements#opacity---o) + * Useful for images with a solid or nearly solid background and a central object. + * This parameter trims the background, leaving only the central object in the + * output image. See + * [Trim edges](https://imagekit.io/docs/effects-and-enhancements#trim-edges---t). */ - opacity?: number; + trim?: true | number; /** - * Useful for images with a solid or nearly solid background and a central object. This parameter trims the background, - * leaving only the central object in the output image. - * - * [Effects and Enhancements - Trim Edges](https://imagekit.io/docs/effects-and-enhancements#trim-edges---t) + * Applies Unsharp Masking (USM), an image sharpening technique. Pass `true` for a + * default unsharp mask, or provide a string for a custom unsharp mask. See + * [Unsharp Mask](https://imagekit.io/docs/effects-and-enhancements#unsharp-mask---e-usm). */ - trim?: true | number; + unsharpMask?: true | string; /** - * Accepts a numeric value that determines how much to zoom in or out of the cropped area. - * It should be used in conjunction with fo-face or fo-. - * - * [Image Resize and Crop - Zoom](https://imagekit.io/docs/image-resize-and-crop#zoom---z) + * Specifies the video codec, e.g., `h264`, `vp9`, `av1`, or `none`. See + * [Video codec](https://imagekit.io/docs/video-optimization#video-codec---vc). */ - zoom?: number; + videoCodec?: 'h264' | 'vp9' | 'av1' | 'none'; /** - * Extracts a specific page or frame from multi-page or layered files (PDF, PSD, AI). - * For example, specify by number (e.g., `2`), a range (e.g., `3-4` for the 2nd and 3rd layers), - * or by name (e.g., `name-layer-4` for a PSD layer). - * - * [Vector and Animated Images - Thumbnail Extraction](https://imagekit.io/docs/vector-and-animated-images#get-thumbnail-from-psd-pdf-ai-eps-and-animated-files) + * Specifies the width of the output. If a value between 0 and 1 is provided, it is + * treated as a percentage (e.g., `0.4` represents 40% of the original width). You + * can also supply arithmetic expressions (e.g., `iw_div_2`). Width transformation + * – [Images](https://imagekit.io/docs/image-resize-and-crop#width---w) · + * [Videos](https://imagekit.io/docs/video-resize-and-crop#width---w) */ - page?: number | string; + width?: number | string; /** - * Pass any transformation not directly supported by the SDK. - * This transformation string is appended to the URL as provided. + * Focus using cropped image coordinates - X coordinate. See + * [Focus using cropped coordinates](https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates). */ - raw?: string; + x?: number | string; + + /** + * Focus using cropped image coordinates - X center coordinate. See + * [Focus using cropped coordinates](https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates). + */ + xCenter?: number | string; + /** + * Focus using cropped image coordinates - Y coordinate. See + * [Focus using cropped coordinates](https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates). + */ + y?: number | string; /** - * Specifies an overlay to be applied on the parent image or video. - * ImageKit supports overlays including images, text, videos, subtitles, and solid colors. - * - * [Transformations - Overlay Using Layers](https://imagekit.io/docs/transformations#overlay-using-layers) + * Focus using cropped image coordinates - Y center coordinate. See + * [Focus using cropped coordinates](https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates). */ - overlay?: Overlay; + yCenter?: number | string; + + /** + * Accepts a numeric value that determines how much to zoom in or out of the + * cropped area. It should be used in conjunction with fo-face or fo-. + * See [Zoom](https://imagekit.io/docs/image-resize-and-crop#zoom---z). + */ + zoom?: number; } -export type Overlay = - | TextOverlay - | ImageOverlay - | VideoOverlay - | SubtitleOverlay - | SolidColorOverlay +/** + * Specifies an overlay to be applied on the parent image or video. ImageKit + * supports overlays including images, text, videos, subtitles, and solid colors. + * See + * [Overlay using layers](https://imagekit.io/docs/transformations#overlay-using-layers). + */ +export type Overlay = TextOverlay | ImageOverlay | VideoOverlay | SubtitleOverlay | SolidColorOverlay; export interface BaseOverlay { /** - * Specifies the overlay's position relative to the parent asset. - * Accepts a JSON object with `x` and `y` (or `focus`) properties. - * - * [Transformations - Position of Layer](https://imagekit.io/docs/transformations#position-of-layer) + * Controls how the layer blends with the base image or underlying content. Maps to + * `lm` in the URL. By default, layers completely cover the base image beneath + * them. Layer modes change this behavior: + * + * - `multiply`: Multiplies the pixel values of the layer with the base image. The + * result is always darker than the original images. This is ideal for applying + * shadows or color tints. + * - `displace`: Uses the layer as a displacement map to distort pixels in the base + * image. The red channel controls horizontal displacement, and the green channel + * controls vertical displacement. Requires `x` or `y` parameter to control + * displacement magnitude. + * - `cutout`: Acts as an inverse mask where opaque areas of the layer turn the + * base image transparent, while transparent areas leave the base image + * unchanged. This mode functions like a hole-punch, effectively cutting the + * shape of the layer out of the underlying image. + * - `cutter`: Acts as a shape mask where only the parts of the base image that + * fall inside the opaque area of the layer are preserved. This mode functions + * like a cookie-cutter, trimming the base image to match the specific dimensions + * and shape of the layer. See + * [Layer modes](https://imagekit.io/docs/add-overlays-on-images#layer-modes). + */ + layerMode?: 'multiply' | 'cutter' | 'cutout' | 'displace'; + + /** + * Specifies the overlay's position relative to the parent asset. See + * [Position of Layer](https://imagekit.io/docs/transformations#position-of-layer). */ position?: OverlayPosition; /** - * Specifies timing information for the overlay (only applicable if the base asset is a video). - * Accepts a JSON object with `start` (`lso`), `end` (`leo`), and `duration` (`ldu`) properties. - * - * [Transformations - Position of Layer](https://imagekit.io/docs/transformations#position-of-layer) + * Specifies timing information for the overlay (only applicable if the base asset + * is a video). See + * [Position of Layer](https://imagekit.io/docs/transformations#position-of-layer). */ timing?: OverlayTiming; } export interface OverlayPosition { /** - * Specifies the x-coordinate of the top-left corner of the base asset where the overlay's top-left corner will be positioned. - * It also accepts arithmetic expressions such as `bw_mul_0.4` or `bw_sub_cw`. - * Maps to `lx` in the URL. - * - * Learn about [Arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations) + * Specifies the position of the overlay relative to the parent image or video. + * Maps to `lfo` in the URL. */ - x?: number | string; + focus?: + | 'center' + | 'top' + | 'left' + | 'bottom' + | 'right' + | 'top_left' + | 'top_right' + | 'bottom_left' + | 'bottom_right'; /** - * Specifies the y-coordinate of the top-left corner of the base asset where the overlay's top-left corner will be positioned. - * It also accepts arithmetic expressions such as `bh_mul_0.4` or `bh_sub_ch`. - * Maps to `ly` in the URL. - * - * Learn about [Arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations) + * Specifies the x-coordinate of the top-left corner of the base asset where the + * overlay's top-left corner will be positioned. It also accepts arithmetic + * expressions such as `bw_mul_0.4` or `bw_sub_cw`. Maps to `lx` in the URL. Learn + * about + * [Arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations). */ - y?: number | string; + x?: number | string; /** - * Specifies the position of the overlay relative to the parent image or video. - * Acceptable values: `center`, `top`, `left`, `bottom`, `right`, `top_left`, `top_right`, `bottom_left`, or `bottom_right`. - * Maps to `lfo` in the URL. + * Specifies the y-coordinate of the top-left corner of the base asset where the + * overlay's top-left corner will be positioned. It also accepts arithmetic + * expressions such as `bh_mul_0.4` or `bh_sub_ch`. Maps to `ly` in the URL. Learn + * about + * [Arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations). */ - focus?: `center` | `top` | `left` | `bottom` | `right` | `top_left` | `top_right` | `bottom_left` | `bottom_right`; + y?: number | string; } export interface OverlayTiming { /** - * Specifies the start time (in seconds) for when the overlay should appear on the base video. - * Accepts a positive number up to two decimal places (e.g., `20` or `20.50`) and arithmetic expressions such as `bdu_mul_0.4` or `bdu_sub_idu`. - * Applies only if the base asset is a video. - * - * Maps to `lso` in the URL. + * Specifies the duration (in seconds) during which the overlay should appear on + * the base video. Accepts a positive number up to two decimal places (e.g., `20` + * or `20.50`) and arithmetic expressions such as `bdu_mul_0.4` or `bdu_sub_idu`. + * Applies only if the base asset is a video. Maps to `ldu` in the URL. */ - start?: number | string; + duration?: number | string; /** - * Specifies the duration (in seconds) during which the overlay should appear on the base video. - * Accepts a positive number up to two decimal places (e.g., `20` or `20.50`) and arithmetic expressions such as `bdu_mul_0.4` or `bdu_sub_idu`. - * Applies only if the base asset is a video. - * - * Maps to `ldu` in the URL. + * Specifies the end time (in seconds) for when the overlay should disappear from + * the base video. If both end and duration are provided, duration is ignored. + * Accepts a positive number up to two decimal places (e.g., `20` or `20.50`) and + * arithmetic expressions such as `bdu_mul_0.4` or `bdu_sub_idu`. Applies only if + * the base asset is a video. Maps to `leo` in the URL. */ - duration?: number | string; + end?: number | string; /** - * Specifies the end time (in seconds) for when the overlay should disappear from the base video. - * If both end and duration are provided, duration is ignored. - * Accepts a positive number up to two decimal places (e.g., `20` or `20.50`) and arithmetic expressions such as `bdu_mul_0.4` or `bdu_sub_idu`. - * Applies only if the base asset is a video. - * - * Maps to `leo` in the URL. + * Specifies the start time (in seconds) for when the overlay should appear on the + * base video. Accepts a positive number up to two decimal places (e.g., `20` or + * `20.50`) and arithmetic expressions such as `bdu_mul_0.4` or `bdu_sub_idu`. + * Applies only if the base asset is a video. Maps to `lso` in the URL. */ - end?: number | string; + start?: number | string; } export interface TextOverlay extends BaseOverlay { - type: "text"; - /** - * Specifies the text to be displayed in the overlay. The SDK automatically handles special characters and encoding. + * Specifies the text to be displayed in the overlay. The SDK automatically handles + * special characters and encoding. */ text: string; + type: 'text'; + /** - * Text can be included in the layer as either `i-{input}` (plain text) or `ie-{base64_encoded_input}` (base64). - * By default, the SDK selects the appropriate format based on the input text. - * To always use base64 (`ie-{base64}`), set this parameter to `base64`. - * To always use plain text (`i-{input}`), set it to `plain`. - * - * Regardless of the encoding method, the input text is always percent-encoded to ensure it is URL-safe. + * Text can be included in the layer as either `i-{input}` (plain text) or + * `ie-{base64_encoded_input}` (base64). By default, the SDK selects the + * appropriate format based on the input text. To always use base64 + * (`ie-{base64}`), set this parameter to `base64`. To always use plain text + * (`i-{input}`), set it to `plain`. + * + * Regardless of the encoding method, the input text is always percent-encoded to + * ensure it is URL-safe. */ - - encoding?: "auto" | "plain" | "base64"; + encoding?: 'auto' | 'plain' | 'base64'; /** - * Control styling of the text overlay. + * Control styling of the text overlay. See + * [Text overlays](https://imagekit.io/docs/add-overlays-on-images#text-overlay). */ - transformation?: TextOverlayTransformation[]; + transformation?: Array; } export interface ImageOverlay extends BaseOverlay { @@ -533,206 +613,297 @@ export interface ImageOverlay extends BaseOverlay { } export interface VideoOverlay extends BaseOverlay { - type: "video"; /** * Specifies the relative path to the video used as an overlay. */ input: string; + type: 'video'; + /** - * The input path can be included in the layer as either `i-{input}` or `ie-{base64_encoded_input}`. - * By default, the SDK determines the appropriate format automatically. - * To always use base64 encoding (`ie-{base64}`), set this parameter to `base64`. - * To always use plain text (`i-{input}`), set it to `plain`. - * + * The input path can be included in the layer as either `i-{input}` or + * `ie-{base64_encoded_input}`. By default, the SDK determines the appropriate + * format automatically. To always use base64 encoding (`ie-{base64}`), set this + * parameter to `base64`. To always use plain text (`i-{input}`), set it to + * `plain`. + * * Regardless of the encoding method: + * * - Leading and trailing slashes are removed. - * - Remaining slashes within the path are replaced with `@@` when using plain text. + * - Remaining slashes within the path are replaced with `@@` when using plain + * text. */ - encoding?: "auto" | "plain" | "base64"; + encoding?: 'auto' | 'plain' | 'base64'; /** - * Array of transformation to be applied to the overlay video. Except `streamingResolutions`, all other video transformations are supported. - * - * [Video Transformations](https://imagekit.io/docs/video-transformation) + * Array of transformation to be applied to the overlay video. Except + * `streamingResolutions`, all other video transformations are supported. See + * [Video transformations](https://imagekit.io/docs/video-transformation). */ - transformation?: Transformation[]; + transformation?: Array; } export interface SubtitleOverlay extends BaseOverlay { - type: "subtitle"; /** * Specifies the relative path to the subtitle file used as an overlay. */ input: string; + type: 'subtitle'; + /** - * The input path can be included in the layer as either `i-{input}` or `ie-{base64_encoded_input}`. - * By default, the SDK determines the appropriate format automatically. - * To always use base64 encoding (`ie-{base64}`), set this parameter to `base64`. - * To always use plain text (`i-{input}`), set it to `plain`. - * + * The input path can be included in the layer as either `i-{input}` or + * `ie-{base64_encoded_input}`. By default, the SDK determines the appropriate + * format automatically. To always use base64 encoding (`ie-{base64}`), set this + * parameter to `base64`. To always use plain text (`i-{input}`), set it to + * `plain`. + * * Regardless of the encoding method: + * * - Leading and trailing slashes are removed. - * - Remaining slashes within the path are replaced with `@@` when using plain text. + * - Remaining slashes within the path are replaced with `@@` when using plain + * text. */ - encoding?: "auto" | "plain" | "base64"; + encoding?: 'auto' | 'plain' | 'base64'; /** - * Control styling of the subtitle. - * - * [Styling subtitles](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer) + * Control styling of the subtitle. See + * [Styling subtitles](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer). */ - transformation?: SubtitleOverlayTransformation[]; + transformation?: Array; } export interface SolidColorOverlay extends BaseOverlay { - type: "solidColor"; /** - * Specifies the color of the block using an RGB hex code (e.g., `FF0000`), an RGBA code (e.g., `FFAABB50`), or a color name (e.g., `red`). - * If an 8-character value is provided, the last two characters represent the opacity level (from `00` for 0.00 to `99` for 0.99). + * Specifies the color of the block using an RGB hex code (e.g., `FF0000`), an RGBA + * code (e.g., `FFAABB50`), or a color name (e.g., `red`). If an 8-character value + * is provided, the last two characters represent the opacity level (from `00` for + * 0.00 to `99` for 0.99). */ color: string; + type: 'solidColor'; + /** - * Control width and height of the solid color overlay. Supported transformations depend on the base/parent asset. - * - * [Image](https://imagekit.io/docs/add-overlays-on-images#apply-transformation-on-solid-color-overlay) | [Video](https://imagekit.io/docs/add-overlays-on-videos#apply-transformations-on-solid-color-block-overlay) + * Control width and height of the solid color overlay. Supported transformations + * depend on the base/parent asset. See overlays on + * [Images](https://imagekit.io/docs/add-overlays-on-images#apply-transformation-on-solid-color-overlay) + * and + * [Videos](https://imagekit.io/docs/add-overlays-on-videos#apply-transformations-on-solid-color-block-overlay). */ - transformation?: SolidColorOverlayTransformation[]; + transformation?: Array; } -export type TextOverlayTransformation = { +export interface TextOverlayTransformation { /** - * Specifies the maximum width (in pixels) of the overlaid text. The text wraps automatically, and arithmetic expressions (e.g., `bw_mul_0.2` or `bh_div_2`) are supported. Useful when used in conjunction with the `background`. + * Specifies the transparency level of the text overlay. Accepts integers from `1` + * to `9`. */ - width?: number | string; + alpha?: number; /** - * Specifies the font size of the overlaid text. Accepts a numeric value or an arithmetic expression. + * Specifies the background color of the text overlay. Accepts an RGB hex code, an + * RGBA code, or a color name. */ - fontSize?: number | string; + background?: string; /** - * Specifies the font family of the overlaid text. Choose from the [supported fonts list](https://imagekit.io/docs/add-overlays-on-images#supported-text-font-list) or use a [custom font](https://imagekit.io/docs/add-overlays-on-images#change-font-family-in-text-overlay). + * Flip/mirror the text horizontally, vertically, or in both directions. Acceptable + * values: `h` (horizontal), `v` (vertical), `h_v` (horizontal and vertical), or + * `v_h`. */ - fontFamily?: string; + flip?: 'h' | 'v' | 'h_v' | 'v_h'; /** - * Specifies the font color of the overlaid text. Accepts an RGB hex code (e.g., `FF0000`), an RGBA code (e.g., `FFAABB50`), or a color name. + * Specifies the font color of the overlaid text. Accepts an RGB hex code (e.g., + * `FF0000`), an RGBA code (e.g., `FFAABB50`), or a color name. */ fontColor?: string; /** - * Specifies the inner alignment of the text when width is more than the text length. - * Supported values: `left`, `right`, and `center` (default). + * Specifies the font family of the overlaid text. Choose from the supported fonts + * list or use a custom font. See + * [Supported fonts](https://imagekit.io/docs/add-overlays-on-images#supported-text-font-list) + * and + * [Custom font](https://imagekit.io/docs/add-overlays-on-images#change-font-family-in-text-overlay). */ - innerAlignment?: "left" | "right" | "center"; + fontFamily?: string; /** - * Specifies the padding around the overlaid text. - * Can be provided as a single positive integer or multiple values separated by underscores (following CSS shorthand order). - * Arithmetic expressions are also accepted. + * Specifies the font size of the overlaid text. Accepts a numeric value or an + * arithmetic expression. */ - padding?: number | string; + fontSize?: number | string; /** - * Specifies the transparency level of the text overlay. Accepts integers from `1` to `9`. + * Specifies the inner alignment of the text when width is more than the text + * length. */ - alpha?: number; + innerAlignment?: 'left' | 'right' | 'center'; /** - * Specifies the typography style of the text. - * Supported values: `b` for bold, `i` for italics, and `b_i` for bold with italics. + * Specifies the line height for multi-line text overlays. It will come into effect + * only if the text wraps over multiple lines. Accepts either an integer value or + * an arithmetic expression. */ - typography?: "b" | "i" | "b_i"; + lineHeight?: number | string; /** - * Specifies the background color of the text overlay. - * Accepts an RGB hex code, an RGBA code, or a color name. + * Specifies the padding around the overlaid text. Can be provided as a single + * positive integer or multiple values separated by underscores (following CSS + * shorthand order). Arithmetic expressions are also accepted. */ - background?: string; + padding?: number | string; /** - * Specifies the corner radius of the text overlay. - * Set to `max` to achieve a circular or oval shape. + * Specifies the corner radius: + * + * - Single value (positive integer): Applied to all corners (e.g., `20`). + * - `max`: Creates a circular or oval shape. + * - Per-corner array: Provide four underscore-separated values representing + * top-left, top-right, bottom-right, and bottom-left corners respectively (e.g., + * `10_20_30_40`). See + * [Radius](https://imagekit.io/docs/effects-and-enhancements#radius---r). */ - radius?: number | "max"; + radius?: number | 'max' | string; /** - * Specifies the rotation angle of the text overlay. - * Accepts a numeric value for clockwise rotation or a string prefixed with "N" for counter-clockwise rotation. + * Specifies the rotation angle of the text overlay. Accepts a numeric value for + * clockwise rotation or a string prefixed with "N" for counter-clockwise rotation. */ rotation?: number | string; /** - * Flip/mirror the text horizontally, vertically, or in both directions. - * Acceptable values: `h` (horizontal), `v` (vertical), `h_v` (horizontal and vertical), or `v_h`. + * Specifies the typography style of the text. Supported values: + * + * - Single styles: `b` (bold), `i` (italic), `strikethrough`. + * - Combinations: Any combination separated by underscores, e.g., `b_i`, + * `b_i_strikethrough`. */ - flip?: "h" | "v" | "h_v" | "v_h"; + typography?: string; /** - * Specifies the line height for multi-line text overlays. It will come into effect only if the text wraps over multiple lines. - * Accepts either an integer value or an arithmetic expression. + * Specifies the maximum width (in pixels) of the overlaid text. The text wraps + * automatically, and arithmetic expressions (e.g., `bw_mul_0.2` or `bh_div_2`) are + * supported. Useful when used in conjunction with the `background`. Learn about + * [Arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations). */ - lineHeight?: number | string; + width?: number | string; } -export type SubtitleOverlayTransformation = { + +/** + * Subtitle styling options. + * [Learn more](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer) + * from the docs. + */ +export interface SubtitleOverlayTransformation { /** - * Specifies the subtitle background color using a standard color name, an RGB color code (e.g., `FF0000`), or an RGBA color code (e.g., `FFAABB50`). + * Specifies the subtitle background color using a standard color name, an RGB + * color code (e.g., FF0000), or an RGBA color code (e.g., FFAABB50). + * + * [Subtitle styling options](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer) */ background?: string; + /** - * Sets the font size of subtitle text. + * Sets the font color of the subtitle text using a standard color name, an RGB + * color code (e.g., FF0000), or an RGBA color code (e.g., FFAABB50). + * + * [Subtitle styling options](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer) */ - fontSize?: number | string; + color?: string; + /** - * Sets the font family of subtitle text. - * Refer to the [supported fonts documented](https://imagekit.io/docs/add-overlays-on-images#supported-text-font-list) in the ImageKit transformations guide. + * Sets the font family of subtitle text. Refer to the + * [supported fonts documented](https://imagekit.io/docs/add-overlays-on-images#supported-text-font-list) + * in the ImageKit transformations guide. */ fontFamily?: string; + /** - * Sets the font color of the subtitle text using a standard color name, an RGB color code (e.g., `FF0000`), or an RGBA color code (e.g., `FFAABB50`). + * Sets the font outline of the subtitle text. Requires the outline width (an + * integer) and the outline color (as an RGB color code, RGBA color code, or + * standard web color name) separated by an underscore. Example: `fol-2_blue` + * (outline width of 2px and outline color blue), `fol-2_A1CCDD` (outline width of + * 2px and outline color `#A1CCDD`) and `fol-2_A1CCDD50` (outline width of 2px and + * outline color `#A1CCDD` at 50% opacity). + * + * [Subtitle styling options](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer) */ - color?: string; + fontOutline?: string; + /** - * Sets the typography style of the subtitle text. - * Supported values: `b` for bold, `i` for italics, and `b_i` for bold with italics. + * Sets the font shadow for the subtitle text. Requires the shadow color (as an RGB + * color code, RGBA color code, or standard web color name) and shadow indent (an + * integer) separated by an underscore. Example: `fsh-blue_2` (shadow color blue, + * indent of 2px), `fsh-A1CCDD_3` (shadow color `#A1CCDD`, indent of 3px), + * `fsh-A1CCDD50_3` (shadow color `#A1CCDD` at 50% opacity, indent of 3px). + * + * [Subtitle styling options](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer) */ - typography?: "b" | "i" | "b_i"; + fontShadow?: string; + /** - * Sets the font outline of the subtitle text. - * Requires the outline width (an integer) and the outline color (as an RGB color code, RGBA color code, or standard web color name) separated by an underscore. - * Examples: `2_blue`, `2_A1CCDD`, or `2_A1CCDD50`. + * Sets the font size of subtitle text. + * + * [Subtitle styling options](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer) */ - fontOutline?: string; + fontSize?: number; + /** - * Sets the font shadow for the subtitle text. - * Requires the shadow color (as an RGB color code, RGBA color code, or standard web color name) and the shadow indent (an integer) separated by an underscore. - * Examples: `blue_2`, `A1CCDD_3`, or `A1CCDD50_3`. + * Sets the typography style of the subtitle text. Supports values are `b` for + * bold, `i` for italics, and `b_i` for bold with italics. + * + * [Subtitle styling options](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer) */ - fontShadow?: string; + typography?: 'b' | 'i' | 'b_i'; } -export type SolidColorOverlayTransformation = Pick & { +export interface SolidColorOverlayTransformation { /** - * Specifies the transparency level of the overlaid solid color layer. Supports integers from `1` to `9`. + * Specifies the transparency level of the overlaid solid color layer. Supports + * integers from `1` to `9`. */ alpha?: number; /** - * Specifies the background color of the solid color overlay. - * Accepts an RGB hex code, an RGBA code, or a color name. + * Specifies the background color of the solid color overlay. Accepts an RGB hex + * code (e.g., `FF0000`), an RGBA code (e.g., `FFAABB50`), or a color name. */ background?: string; /** - * Only works if base asset is an image. - * - * Creates a linear gradient with two colors. Pass `true` for a default gradient, or provide a string for a custom gradient. - * - * [Effects and Enhancements - Gradient](https://imagekit.io/docs/effects-and-enhancements#gradient---e-gradient) + * Creates a linear gradient with two colors. Pass `true` for a default gradient, + * or provide a string for a custom gradient. Only works if the base asset is an + * image. See + * [gradient](https://imagekit.io/docs/effects-and-enhancements#gradient---e-gradient). */ - gradient?: Transformation["gradient"] + gradient?: true | string; + + /** + * Controls the height of the solid color overlay. Accepts a numeric value or an + * arithmetic expression. Learn about + * [arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations). + */ + height?: number | string; + + /** + * Specifies the corner radius of the solid color overlay. + * + * - Single value (positive integer): Applied to all corners (e.g., `20`). + * - `max`: Creates a circular or oval shape. + * - Per-corner array: Provide four underscore-separated values representing + * top-left, top-right, bottom-right, and bottom-left corners respectively (e.g., + * `10_20_30_40`). See + * [Radius](https://imagekit.io/docs/effects-and-enhancements#radius---r). + */ + radius?: number | 'max' | string; + + /** + * Controls the width of the solid color overlay. Accepts a numeric value or an + * arithmetic expression (e.g., `bw_mul_0.2` or `bh_div_2`). Learn about + * [arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations). + */ + width?: number | string; } diff --git a/src/url.ts b/src/url.ts index 836bb8e..62a12c2 100644 --- a/src/url.ts +++ b/src/url.ts @@ -124,7 +124,7 @@ function processText(str: string, enccoding: TextOverlay["encoding"]): string { function processOverlay(overlay: Transformation["overlay"]): string | undefined { const entries = []; - const { type, position = {}, timing = {}, transformation = [] } = overlay || {}; + const { type, layerMode, position = {}, timing = {}, transformation = [] } = overlay || {}; if (!type) { return; @@ -192,6 +192,11 @@ function processOverlay(overlay: Transformation["overlay"]): string | undefined break; } + // Add layer mode if specified + if (layerMode) { + entries.push(`lm-${layerMode}`); + } + const { x, y, focus } = position; if (x) { entries.push(`lx-${x}`); diff --git a/test/url-generation/basic.js b/test/url-generation/basic.js index 739958c..da928ee 100644 --- a/test/url-generation/basic.js +++ b/test/url-generation/basic.js @@ -1267,6 +1267,7 @@ describe("URL generation", function () { aiVariation: true, aiDropShadow: true, aiChangeBackground: "prompt-car", + aiEdit: 'prompt-make it vintage', aiRemoveBackground: true, contrastStretch: true, shadow: "bl-15_st-40_x-10_y-N5", @@ -1275,13 +1276,16 @@ describe("URL generation", function () { gradient: "from-red_to-white", original: true, page: "2_4", - raw: "h-200,w-300,l-image,i-logo.png,l-end" + raw: "h-200,w-300,l-image,i-logo.png,l-end", + // New transformation parameters + colorReplace: 'FF0000_50_00FF00', + distort: 'p-50_50_150_50_150_150_50_150', } ] }); expect(url).equal( - `https://ik.imagekit.io/test_url_endpoint/test_path.jpg?tr=h-300,w-400,ar-4-3,q-40,c-force,cm-extract,fo-left,f-jpeg,r-50,bg-A94D34,b-5-A94D34,rt-90,bl-10,n-some_name,pr-true,lo-true,t-5,md-true,cp-true,di-folder@@file.jpg,dpr-3,x-10,y-20,xc-30,yc-40,fl-h,o-0.8,z-2,vc-h264,ac-aac,so-5,eo-15,du-10,sr-1440_1080,e-grayscale,e-upscale,e-retouch,e-genvar,e-dropshadow,e-changebg-prompt-car,e-bgremove,e-contrast,e-shadow-bl-15_st-40_x-10_y-N5,e-sharpen-10,e-usm-2-2-0.8-0.024,e-gradient-from-red_to-white,orig-true,pg-2_4,h-200,w-300,l-image,i-logo.png,l-end` + `https://ik.imagekit.io/test_url_endpoint/test_path.jpg?tr=h-300,w-400,ar-4-3,q-40,c-force,cm-extract,fo-left,f-jpeg,r-50,bg-A94D34,b-5-A94D34,rt-90,bl-10,n-some_name,pr-true,lo-true,t-5,md-true,cp-true,di-folder@@file.jpg,dpr-3,x-10,y-20,xc-30,yc-40,fl-h,o-0.8,z-2,vc-h264,ac-aac,so-5,eo-15,du-10,sr-1440_1080,e-grayscale,e-upscale,e-retouch,e-genvar,e-dropshadow,e-changebg-prompt-car,e-edit-prompt-make it vintage,e-bgremove,e-contrast,e-shadow-bl-15_st-40_x-10_y-N5,e-sharpen-10,e-usm-2-2-0.8-0.024,e-gradient-from-red_to-white,orig-true,pg-2_4,h-200,w-300,l-image,i-logo.png,l-end,cr-FF0000_50_00FF00,e-distort-p-50_50_150_50_150_150_50_150` ); }); }); diff --git a/test/url-generation/overlay.js b/test/url-generation/overlay.js index 0ade645..b1edd4c 100644 --- a/test/url-generation/overlay.js +++ b/test/url-generation/overlay.js @@ -509,4 +509,75 @@ describe("Overlay encoding test cases", function () { }); expect(url).equal(`https://ik.imagekit.io/demo/sample.jpg?tr=l-text,i-Minimal%20Text,l-end`); }); + + // Layer Mode Tests + describe("Layer Mode Tests", function () { + it('should generate correct URL with multiply layer mode', function () { + const url = buildSrc({ + transformationPosition: "path", + urlEndpoint: "https://ik.imagekit.io/test_url_endpoint", + src: "/base-image.jpg", + transformation: [{ + overlay: { + type: "image", + input: "overlay-image.jpg", + layerMode: "multiply" + } + }] + }); + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:l-image,i-overlay-image.jpg,lm-multiply,l-end/base-image.jpg`); + }); + + it('should generate correct URL with cutter layer mode', function () { + const url = buildSrc({ + transformationPosition: "path", + urlEndpoint: "https://ik.imagekit.io/test_url_endpoint", + src: "/base-image.jpg", + transformation: [{ + overlay: { + type: "image", + input: "overlay-image.jpg", + layerMode: "cutter" + } + }] + }); + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:l-image,i-overlay-image.jpg,lm-cutter,l-end/base-image.jpg`); + }); + + it('should generate correct URL with cutout layer mode', function () { + const url = buildSrc({ + transformationPosition: "path", + urlEndpoint: "https://ik.imagekit.io/test_url_endpoint", + src: "/base-image.jpg", + transformation: [{ + overlay: { + type: "image", + input: "overlay-image.jpg", + layerMode: "cutout" + } + }] + }); + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:l-image,i-overlay-image.jpg,lm-cutout,l-end/base-image.jpg`); + }); + + it('should generate correct URL with displace layer mode', function () { + const url = buildSrc({ + transformationPosition: "path", + urlEndpoint: "https://ik.imagekit.io/test_url_endpoint", + src: "/base-image.jpg", + transformation: [{ + overlay: { + type: "image", + input: "overlay-image.jpg", + layerMode: "displace", + position: { + x: 10, + y: 10 + } + } + }] + }); + expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:l-image,i-overlay-image.jpg,lm-displace,lx-10,ly-10,l-end/base-image.jpg`); + }); + }); }); From e6fedf93fa1e9ffcf47830ebf02fc80f0458443c Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Fri, 16 Jan 2026 16:43:05 +0530 Subject: [PATCH 2/4] Pick types from generated Node.js SDK --- src/index.ts | 16 +- src/interfaces/SrcOptions.ts | 35 - src/interfaces/Transformation.ts | 909 ---------------- src/interfaces/UploadOptions.ts | 340 ++++-- src/interfaces/UploadResponse.ts | 587 +++++++--- src/interfaces/index.ts | 5 +- src/interfaces/shared.ts | 1725 ++++++++++++++++++++++++++++++ src/responsive.ts | 59 +- src/url.ts | 3 +- 9 files changed, 2432 insertions(+), 1247 deletions(-) delete mode 100644 src/interfaces/SrcOptions.ts delete mode 100644 src/interfaces/Transformation.ts create mode 100644 src/interfaces/shared.ts diff --git a/src/index.ts b/src/index.ts index bf68707..dbbfb11 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,14 +1,12 @@ -import type { SrcOptions, Transformation, UploadOptions, UploadResponse } from "./interfaces"; +import type { GetImageAttributesOptions, ResponsiveImageAttributes, SrcOptions, Transformation, UploadOptions, UploadResponse } from "./interfaces"; +import type { } from "./responsive"; +import { getResponsiveImageAttributes } from "./responsive"; import { ImageKitAbortError, ImageKitInvalidRequestError, ImageKitServerError, ImageKitUploadNetworkError, upload } from "./upload"; import { buildSrc, buildTransformationString } from "./url"; -import { getResponsiveImageAttributes } from "./responsive"; -import type { GetImageAttributesOptions, ResponsiveImageAttributes } from "./responsive"; -export { buildSrc, buildTransformationString, upload, getResponsiveImageAttributes, ImageKitInvalidRequestError, ImageKitAbortError, ImageKitServerError, ImageKitUploadNetworkError }; +export { buildSrc, buildTransformationString, getResponsiveImageAttributes, ImageKitAbortError, ImageKitInvalidRequestError, ImageKitServerError, ImageKitUploadNetworkError, upload }; export type { - Transformation, - SrcOptions, - UploadOptions, - UploadResponse, - GetImageAttributesOptions, ResponsiveImageAttributes + GetImageAttributesOptions, ResponsiveImageAttributes, SrcOptions, Transformation, UploadOptions, + UploadResponse }; + diff --git a/src/interfaces/SrcOptions.ts b/src/interfaces/SrcOptions.ts deleted file mode 100644 index 4b0187e..0000000 --- a/src/interfaces/SrcOptions.ts +++ /dev/null @@ -1,35 +0,0 @@ -import { Transformation } from "./Transformation"; -import { TransformationPosition } from "."; - -export interface SrcOptions { - /** - * Accepts a relative or absolute path of the resource. If a relative path is provided, it is appended to the `urlEndpoint`. - * If an absolute path is provided, `urlEndpoint` is ignored. - */ - src: string; - - /** - * Get your urlEndpoint from the [ImageKit dashboard](https://imagekit.io/dashboard/url-endpoints). - */ - urlEndpoint: string; - - /** - * An array of objects specifying the transformations to be applied in the URL. If more than one transformation is specified, they are applied in the order they are specified as chained transformations. - * - * {@link https://imagekit.io/docs/transformations#chained-transformations} - */ - transformation?: Array; - - /** - * These are additional query parameters that you want to add to the final URL. - * They can be any query parameters and not necessarily related to ImageKit. - * This is especially useful if you want to add a versioning parameter to your URLs. - */ - queryParameters?: { [key: string]: string | number }; - - /** - * By default, the transformation string is added as a query parameter in the URL, e.g., `?tr=w-100,h-100`. - * If you want to add the transformation string in the path of the URL, set this to `path`. - */ - transformationPosition?: TransformationPosition; -} diff --git a/src/interfaces/Transformation.ts b/src/interfaces/Transformation.ts deleted file mode 100644 index f517855..0000000 --- a/src/interfaces/Transformation.ts +++ /dev/null @@ -1,909 +0,0 @@ -/** - * By default, the transformation string is added as a query parameter in the URL, - * e.g., `?tr=w-100,h-100`. If you want to add the transformation string in the - * path of the URL, set this to `path`. Learn more in the - * [Transformations guide](https://imagekit.io/docs/transformations). - */ -export type TransformationPosition = "path" | "query"; - -export type StreamingResolution = "240" | "360" | "480" | "720" | "1080" | "1440" | "2160"; - -/** - * The SDK provides easy-to-use names for transformations. These names are - * converted to the corresponding transformation string before being added to the - * URL. SDKs are updated regularly to support new transformations. If you want to - * use a transformation that is not supported by the SDK, You can use the `raw` - * parameter to pass the transformation string directly. See the - * [Transformations documentation](https://imagekit.io/docs/transformations). - */ -export interface Transformation { - /** - * Uses AI to change the background. Provide a text prompt or a base64-encoded - * prompt, e.g., `prompt-snow road` or `prompte-[urlencoded_base64_encoded_text]`. - * Not supported inside overlay. See - * [AI Change Background](https://imagekit.io/docs/ai-transformations#change-background-e-changebg). - */ - aiChangeBackground?: string; - - /** - * Adds an AI-based drop shadow around a foreground object on a transparent or - * removed background. Optionally, control the direction, elevation, and saturation - * of the light source (e.g., `az-45` to change light direction). Pass `true` for - * the default drop shadow, or provide a string for a custom drop shadow. Supported - * inside overlay. See - * [AI Drop Shadow](https://imagekit.io/docs/ai-transformations#ai-drop-shadow-e-dropshadow). - */ - aiDropShadow?: true | string; - - /** - * Uses AI to edit images based on a text prompt. Provide a text prompt or a - * base64-encoded prompt, e.g., `prompt-snow road` or - * `prompte-[urlencoded_base64_encoded_text]`. Not supported inside overlay. - * See [AI Edit](https://imagekit.io/docs/ai-transformations#edit-image-e-edit). - */ - aiEdit?: string; - - /** - * Applies ImageKit's in-house background removal. Supported inside overlay. See - * [AI Background Removal](https://imagekit.io/docs/ai-transformations#imagekit-background-removal-e-bgremove). - */ - aiRemoveBackground?: true; - - /** - * Uses third-party background removal. Note: It is recommended to use - * aiRemoveBackground, ImageKit's in-house solution, which is more cost-effective. - * Supported inside overlay. See - * [External Background Removal](https://imagekit.io/docs/ai-transformations#background-removal-e-removedotbg). - */ - aiRemoveBackgroundExternal?: true; - - /** - * Performs AI-based retouching to improve faces or product shots. Not supported - * inside overlay. See - * [AI Retouch](https://imagekit.io/docs/ai-transformations#retouch-e-retouch). - */ - aiRetouch?: true; - - /** - * Upscales images beyond their original dimensions using AI. Not supported inside - * overlay. See - * [AI Upscale](https://imagekit.io/docs/ai-transformations#upscale-e-upscale). - */ - aiUpscale?: true; - - /** - * Generates a variation of an image using AI. This produces a new image with - * slight variations from the original, such as changes in color, texture, and - * other visual elements, while preserving the structure and essence of the - * original image. Not supported inside overlay. See - * [AI Generate Variations](https://imagekit.io/docs/ai-transformations#generate-variations-of-an-image-e-genvar). - */ - aiVariation?: true; - - /** - * Specifies the aspect ratio for the output, e.g., "ar-4-3". Typically used with - * either width or height (but not both). For example: aspectRatio = `4:3`, `4_3`, - * or an expression like `iar_div_2`. See - * [Image resize and crop – Aspect ratio](https://imagekit.io/docs/image-resize-and-crop#aspect-ratio---ar). - */ - aspectRatio?: number | string; - - /** - * Specifies the audio codec, e.g., `aac`, `opus`, or `none`. See - * [Audio codec](https://imagekit.io/docs/video-optimization#audio-codec---ac). - */ - audioCodec?: 'aac' | 'opus' | 'none'; - - /** - * Specifies the background to be used in conjunction with certain cropping - * strategies when resizing an image. - * - * - A solid color: e.g., `red`, `F3F3F3`, `AAFF0010`. See - * [Solid color background](https://imagekit.io/docs/effects-and-enhancements#solid-color-background). - * - Dominant color: `dominant` extracts the dominant color from the image. See - * [Dominant color background](https://imagekit.io/docs/effects-and-enhancements#dominant-color-background). - * - Gradient: `gradient_dominant` or `gradient_dominant_2` creates a gradient - * using the dominant colors. Optionally specify palette size (2 or 4), e.g., - * `gradient_dominant_4`. See - * [Gradient background](https://imagekit.io/docs/effects-and-enhancements#gradient-background). - * - A blurred background: e.g., `blurred`, `blurred_25_N15`, etc. See - * [Blurred background](https://imagekit.io/docs/effects-and-enhancements#blurred-background). - * - Expand the image boundaries using generative fill: `genfill`. Not supported - * inside overlay. Optionally, control the background scene by passing a text - * prompt: `genfill[:-prompt-${text}]` or - * `genfill[:-prompte-${urlencoded_base64_encoded_text}]`. See - * [Generative fill background](https://imagekit.io/docs/ai-transformations#generative-fill-bg-genfill). - */ - background?: string; - - /** - * Specifies the Gaussian blur level. Accepts an integer value between 1 and 100, - * or an expression like `bl-10`. See - * [Blur](https://imagekit.io/docs/effects-and-enhancements#blur---bl). - */ - blur?: number; - - /** - * Adds a border to the output media. Accepts a string in the format - * `_` (e.g., `5_FFF000` for a 5px yellow border), or an - * expression like `ih_div_20_FF00FF`. See - * [Border](https://imagekit.io/docs/effects-and-enhancements#border---b). - */ - border?: string; - - /** - * Indicates whether the output image should retain the original color profile. See - * [Color profile](https://imagekit.io/docs/image-optimization#color-profile---cp). - */ - colorProfile?: boolean; - - /** - * Replaces colors in the image. Supports three formats: - * - * - `toColor` - Replace dominant color with the specified color. - * - `toColor_tolerance` - Replace dominant color with specified tolerance (0-100). - * - `toColor_tolerance_fromColor` - Replace a specific color with another within - * tolerance range. Colors can be hex codes (e.g., `FF0022`) or names (e.g., - * `red`, `blue`). See - * [Color replacement](https://imagekit.io/docs/effects-and-enhancements#color-replace---cr). - */ - colorReplace?: string; - - /** - * Automatically enhances the contrast of an image (contrast stretch). See - * [Contrast Stretch](https://imagekit.io/docs/effects-and-enhancements#contrast-stretch---e-contrast). - */ - contrastStretch?: true; - - /** - * Crop modes for image resizing. See - * [Crop modes & focus](https://imagekit.io/docs/image-resize-and-crop#crop-crop-modes--focus). - */ - crop?: 'force' | 'at_max' | 'at_max_enlarge' | 'at_least' | 'maintain_ratio'; - - /** - * Additional crop modes for image resizing. See - * [Crop modes & focus](https://imagekit.io/docs/image-resize-and-crop#crop-crop-modes--focus). - */ - cropMode?: 'pad_resize' | 'extract' | 'pad_extract'; - - /** - * Specifies a fallback image if the resource is not found, e.g., a URL or file - * path. See - * [Default image](https://imagekit.io/docs/image-transformation#default-image---di). - */ - defaultImage?: string; - - /** - * Distorts the shape of an image. Supports two modes: - * - * - Perspective distortion: `p-x1_y1_x2_y2_x3_y3_x4_y4` changes the position of - * the four corners starting clockwise from top-left. - * - Arc distortion: `a-degrees` curves the image upwards (positive values) or - * downwards (negative values). See - * [Distort effect](https://imagekit.io/docs/effects-and-enhancements#distort---e-distort). - */ - distort?: string; - - /** - * Accepts values between 0.1 and 5, or `auto` for automatic device pixel ratio - * (DPR) calculation. Also accepts arithmetic expressions. - * - * - Learn about - * [Arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations). - * - See [DPR](https://imagekit.io/docs/image-resize-and-crop#dpr---dpr). - */ - dpr?: number; - - /** - * Specifies the duration (in seconds) for trimming videos, e.g., `5` or `10.5`. - * Typically used with startOffset to indicate the length from the start offset. - * Arithmetic expressions are supported. See - * [Trim videos – Duration](https://imagekit.io/docs/trim-videos#duration---du). - */ - duration?: number | string; - - /** - * Specifies the end offset (in seconds) for trimming videos, e.g., `5` or `10.5`. - * Typically used with startOffset to define a time window. Arithmetic expressions - * are supported. See - * [Trim videos – End offset](https://imagekit.io/docs/trim-videos#end-offset---eo). - */ - endOffset?: number | string; - - /** - * Flips or mirrors an image either horizontally, vertically, or both. Acceptable - * values: `h` (horizontal), `v` (vertical), `h_v` (horizontal and vertical), or - * `v_h`. See [Flip](https://imagekit.io/docs/effects-and-enhancements#flip---fl). - */ - flip?: 'h' | 'v' | 'h_v' | 'v_h'; - - /** - * Refines padding and cropping behavior for pad resize, maintain ratio, and - * extract crop modes. Supports manual positions and coordinate-based focus. With - * AI-based cropping, you can automatically keep key subjects in frame—such as - * faces or detected objects (e.g., `fo-face`, `fo-person`, `fo-car`)— while - * resizing. - * - * - See [Focus](https://imagekit.io/docs/image-resize-and-crop#focus---fo). - * - [Object aware cropping](https://imagekit.io/docs/image-resize-and-crop#object-aware-cropping---fo-object-name) - */ - focus?: string; - - /** - * Specifies the output format for images or videos, e.g., `jpg`, `png`, `webp`, - * `mp4`, or `auto`. You can also pass `orig` for images to return the original - * format. ImageKit automatically delivers images and videos in the optimal format - * based on device support unless overridden by the dashboard settings or the - * format parameter. See - * [Image format](https://imagekit.io/docs/image-optimization#format---f) and - * [Video format](https://imagekit.io/docs/video-optimization#format---f). - */ - format?: 'auto' | 'webp' | 'jpg' | 'jpeg' | 'png' | 'gif' | 'svg' | 'mp4' | 'webm' | 'avif' | 'orig'; - - /** - * Creates a linear gradient with two colors. Pass `true` for a default gradient, - * or provide a string for a custom gradient. See - * [Gradient](https://imagekit.io/docs/effects-and-enhancements#gradient---e-gradient). - */ - gradient?: true | string; - - /** - * Enables a grayscale effect for images. See - * [Grayscale](https://imagekit.io/docs/effects-and-enhancements#grayscale---e-grayscale). - */ - grayscale?: true; - - /** - * Specifies the height of the output. If a value between 0 and 1 is provided, it - * is treated as a percentage (e.g., `0.5` represents 50% of the original height). - * You can also supply arithmetic expressions (e.g., `ih_mul_0.5`). Height - * transformation – - * [Images](https://imagekit.io/docs/image-resize-and-crop#height---h) · - * [Videos](https://imagekit.io/docs/video-resize-and-crop#height---h) - */ - height?: number | string; - - /** - * Specifies whether the output image (in JPEG or PNG) should be compressed - * losslessly. See - * [Lossless compression](https://imagekit.io/docs/image-optimization#lossless-webp-and-png---lo). - */ - lossless?: boolean; - - /** - * By default, ImageKit removes all metadata during automatic image compression. - * Set this to true to preserve metadata. See - * [Image metadata](https://imagekit.io/docs/image-optimization#image-metadata---md). - */ - metadata?: boolean; - - /** - * Named transformation reference. See - * [Named transformations](https://imagekit.io/docs/transformations#named-transformations). - */ - named?: string; - - /** - * Specifies the opacity level of the output image. See - * [Opacity](https://imagekit.io/docs/effects-and-enhancements#opacity---o). - */ - opacity?: number; - - /** - * If set to true, serves the original file without applying any transformations. - * See - * [Deliver original file as-is](https://imagekit.io/docs/core-delivery-features#deliver-original-file-as-is---orig-true). - */ - original?: boolean; - - /** - * Specifies an overlay to be applied on the parent image or video. ImageKit - * supports overlays including images, text, videos, subtitles, and solid colors. - * See - * [Overlay using layers](https://imagekit.io/docs/transformations#overlay-using-layers). - */ - overlay?: Overlay; - - /** - * Extracts a specific page or frame from multi-page or layered files (PDF, PSD, - * AI). For example, specify by number (e.g., `2`), a range (e.g., `3-4` for the - * 2nd and 3rd layers), or by name (e.g., `name-layer-4` for a PSD layer). See - * [Thumbnail extraction](https://imagekit.io/docs/vector-and-animated-images#get-thumbnail-from-psd-pdf-ai-eps-and-animated-files). - */ - page?: number | string; - - /** - * Specifies whether the output JPEG image should be rendered progressively. - * Progressive loading begins with a low-quality, pixelated version of the full - * image, which gradually improves to provide a faster perceived load time. See - * [Progressive images](https://imagekit.io/docs/image-optimization#progressive-image---pr). - */ - progressive?: boolean; - - /** - * Specifies the quality of the output image for lossy formats such as JPEG, WebP, - * and AVIF. A higher quality value results in a larger file size with better - * quality, while a lower value produces a smaller file size with reduced quality. - * See [Quality](https://imagekit.io/docs/image-optimization#quality---q). - */ - quality?: number; - - /** - * Specifies the corner radius for rounded corners. - * - * - Single value (positive integer): Applied to all corners (e.g., `20`). - * - `max`: Creates a circular or oval shape. - * - Per-corner array: Provide four underscore-separated values representing - * top-left, top-right, bottom-right, and bottom-left corners respectively (e.g., - * `10_20_30_40`). See - * [Radius](https://imagekit.io/docs/effects-and-enhancements#radius---r). - */ - radius?: number | 'max' | string; - - /** - * Pass any transformation not directly supported by the SDK. This transformation - * string is appended to the URL as provided. - */ - raw?: string; - - /** - * Specifies the rotation angle in degrees. Positive values rotate the image - * clockwise; you can also use, for example, `N40` for counterclockwise rotation or - * `auto` to use the orientation specified in the image's EXIF data. For videos, - * only the following values are supported: 0, 90, 180, 270, or 360. See - * [Rotate](https://imagekit.io/docs/effects-and-enhancements#rotate---rt). - */ - rotation?: number | string; - - /** - * Adds a shadow beneath solid objects in an image with a transparent background. - * For AI-based drop shadows, refer to aiDropShadow. Pass `true` for a default - * shadow, or provide a string for a custom shadow. See - * [Shadow](https://imagekit.io/docs/effects-and-enhancements#shadow---e-shadow). - */ - shadow?: true | string; - - /** - * Sharpens the input image, highlighting edges and finer details. Pass `true` for - * default sharpening, or provide a numeric value for custom sharpening. See - * [Sharpen](https://imagekit.io/docs/effects-and-enhancements#sharpen---e-sharpen). - */ - sharpen?: true | number; - - /** - * Specifies the start offset (in seconds) for trimming videos, e.g., `5` or - * `10.5`. Arithmetic expressions are also supported. See - * [Trim videos – Start offset](https://imagekit.io/docs/trim-videos#start-offset---so). - */ - startOffset?: number | string; - - /** - * An array of resolutions for adaptive bitrate streaming, e.g., [`240`, `360`, - * `480`, `720`, `1080`]. See - * [Adaptive Bitrate Streaming](https://imagekit.io/docs/adaptive-bitrate-streaming). - */ - streamingResolutions?: Array; - - /** - * Useful for images with a solid or nearly solid background and a central object. - * This parameter trims the background, leaving only the central object in the - * output image. See - * [Trim edges](https://imagekit.io/docs/effects-and-enhancements#trim-edges---t). - */ - trim?: true | number; - - /** - * Applies Unsharp Masking (USM), an image sharpening technique. Pass `true` for a - * default unsharp mask, or provide a string for a custom unsharp mask. See - * [Unsharp Mask](https://imagekit.io/docs/effects-and-enhancements#unsharp-mask---e-usm). - */ - unsharpMask?: true | string; - - /** - * Specifies the video codec, e.g., `h264`, `vp9`, `av1`, or `none`. See - * [Video codec](https://imagekit.io/docs/video-optimization#video-codec---vc). - */ - videoCodec?: 'h264' | 'vp9' | 'av1' | 'none'; - - /** - * Specifies the width of the output. If a value between 0 and 1 is provided, it is - * treated as a percentage (e.g., `0.4` represents 40% of the original width). You - * can also supply arithmetic expressions (e.g., `iw_div_2`). Width transformation - * – [Images](https://imagekit.io/docs/image-resize-and-crop#width---w) · - * [Videos](https://imagekit.io/docs/video-resize-and-crop#width---w) - */ - width?: number | string; - - /** - * Focus using cropped image coordinates - X coordinate. See - * [Focus using cropped coordinates](https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates). - */ - x?: number | string; - - /** - * Focus using cropped image coordinates - X center coordinate. See - * [Focus using cropped coordinates](https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates). - */ - xCenter?: number | string; - - /** - * Focus using cropped image coordinates - Y coordinate. See - * [Focus using cropped coordinates](https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates). - */ - y?: number | string; - - /** - * Focus using cropped image coordinates - Y center coordinate. See - * [Focus using cropped coordinates](https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates). - */ - yCenter?: number | string; - - /** - * Accepts a numeric value that determines how much to zoom in or out of the - * cropped area. It should be used in conjunction with fo-face or fo-. - * See [Zoom](https://imagekit.io/docs/image-resize-and-crop#zoom---z). - */ - zoom?: number; -} - -/** - * Specifies an overlay to be applied on the parent image or video. ImageKit - * supports overlays including images, text, videos, subtitles, and solid colors. - * See - * [Overlay using layers](https://imagekit.io/docs/transformations#overlay-using-layers). - */ -export type Overlay = TextOverlay | ImageOverlay | VideoOverlay | SubtitleOverlay | SolidColorOverlay; - -export interface BaseOverlay { - /** - * Controls how the layer blends with the base image or underlying content. Maps to - * `lm` in the URL. By default, layers completely cover the base image beneath - * them. Layer modes change this behavior: - * - * - `multiply`: Multiplies the pixel values of the layer with the base image. The - * result is always darker than the original images. This is ideal for applying - * shadows or color tints. - * - `displace`: Uses the layer as a displacement map to distort pixels in the base - * image. The red channel controls horizontal displacement, and the green channel - * controls vertical displacement. Requires `x` or `y` parameter to control - * displacement magnitude. - * - `cutout`: Acts as an inverse mask where opaque areas of the layer turn the - * base image transparent, while transparent areas leave the base image - * unchanged. This mode functions like a hole-punch, effectively cutting the - * shape of the layer out of the underlying image. - * - `cutter`: Acts as a shape mask where only the parts of the base image that - * fall inside the opaque area of the layer are preserved. This mode functions - * like a cookie-cutter, trimming the base image to match the specific dimensions - * and shape of the layer. See - * [Layer modes](https://imagekit.io/docs/add-overlays-on-images#layer-modes). - */ - layerMode?: 'multiply' | 'cutter' | 'cutout' | 'displace'; - - /** - * Specifies the overlay's position relative to the parent asset. See - * [Position of Layer](https://imagekit.io/docs/transformations#position-of-layer). - */ - position?: OverlayPosition; - - /** - * Specifies timing information for the overlay (only applicable if the base asset - * is a video). See - * [Position of Layer](https://imagekit.io/docs/transformations#position-of-layer). - */ - timing?: OverlayTiming; -} - -export interface OverlayPosition { - /** - * Specifies the position of the overlay relative to the parent image or video. - * Maps to `lfo` in the URL. - */ - focus?: - | 'center' - | 'top' - | 'left' - | 'bottom' - | 'right' - | 'top_left' - | 'top_right' - | 'bottom_left' - | 'bottom_right'; - - /** - * Specifies the x-coordinate of the top-left corner of the base asset where the - * overlay's top-left corner will be positioned. It also accepts arithmetic - * expressions such as `bw_mul_0.4` or `bw_sub_cw`. Maps to `lx` in the URL. Learn - * about - * [Arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations). - */ - x?: number | string; - - /** - * Specifies the y-coordinate of the top-left corner of the base asset where the - * overlay's top-left corner will be positioned. It also accepts arithmetic - * expressions such as `bh_mul_0.4` or `bh_sub_ch`. Maps to `ly` in the URL. Learn - * about - * [Arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations). - */ - y?: number | string; -} - -export interface OverlayTiming { - /** - * Specifies the duration (in seconds) during which the overlay should appear on - * the base video. Accepts a positive number up to two decimal places (e.g., `20` - * or `20.50`) and arithmetic expressions such as `bdu_mul_0.4` or `bdu_sub_idu`. - * Applies only if the base asset is a video. Maps to `ldu` in the URL. - */ - duration?: number | string; - - /** - * Specifies the end time (in seconds) for when the overlay should disappear from - * the base video. If both end and duration are provided, duration is ignored. - * Accepts a positive number up to two decimal places (e.g., `20` or `20.50`) and - * arithmetic expressions such as `bdu_mul_0.4` or `bdu_sub_idu`. Applies only if - * the base asset is a video. Maps to `leo` in the URL. - */ - end?: number | string; - - /** - * Specifies the start time (in seconds) for when the overlay should appear on the - * base video. Accepts a positive number up to two decimal places (e.g., `20` or - * `20.50`) and arithmetic expressions such as `bdu_mul_0.4` or `bdu_sub_idu`. - * Applies only if the base asset is a video. Maps to `lso` in the URL. - */ - start?: number | string; -} - -export interface TextOverlay extends BaseOverlay { - /** - * Specifies the text to be displayed in the overlay. The SDK automatically handles - * special characters and encoding. - */ - text: string; - - type: 'text'; - - /** - * Text can be included in the layer as either `i-{input}` (plain text) or - * `ie-{base64_encoded_input}` (base64). By default, the SDK selects the - * appropriate format based on the input text. To always use base64 - * (`ie-{base64}`), set this parameter to `base64`. To always use plain text - * (`i-{input}`), set it to `plain`. - * - * Regardless of the encoding method, the input text is always percent-encoded to - * ensure it is URL-safe. - */ - encoding?: 'auto' | 'plain' | 'base64'; - - /** - * Control styling of the text overlay. See - * [Text overlays](https://imagekit.io/docs/add-overlays-on-images#text-overlay). - */ - transformation?: Array; -} - -export interface ImageOverlay extends BaseOverlay { - type: "image"; - - /** - * Specifies the relative path to the image used as an overlay. - */ - input: string; - - /** - * The input path can be included in the layer as either `i-{input}` or `ie-{base64_encoded_input}`. - * By default, the SDK determines the appropriate format automatically. - * To always use base64 encoding (`ie-{base64}`), set this parameter to `base64`. - * To always use plain text (`i-{input}`), set it to `plain`. - * - * Regardless of the encoding method: - * - Leading and trailing slashes are removed. - * - Remaining slashes within the path are replaced with `@@` when using plain text. - */ - encoding?: "auto" | "plain" | "base64"; - - /** - * Array of transformations to be applied to the overlay image. Supported transformations depends on the base/parent asset. - * - * [Image](https://imagekit.io/docs/add-overlays-on-images#list-of-supported-image-transformations-in-image-layers) | [Video](https://imagekit.io/docs/add-overlays-on-videos#list-of-transformations-supported-on-image-overlay) - */ - transformation?: Transformation[]; -} - -export interface VideoOverlay extends BaseOverlay { - /** - * Specifies the relative path to the video used as an overlay. - */ - input: string; - - type: 'video'; - - /** - * The input path can be included in the layer as either `i-{input}` or - * `ie-{base64_encoded_input}`. By default, the SDK determines the appropriate - * format automatically. To always use base64 encoding (`ie-{base64}`), set this - * parameter to `base64`. To always use plain text (`i-{input}`), set it to - * `plain`. - * - * Regardless of the encoding method: - * - * - Leading and trailing slashes are removed. - * - Remaining slashes within the path are replaced with `@@` when using plain - * text. - */ - encoding?: 'auto' | 'plain' | 'base64'; - - /** - * Array of transformation to be applied to the overlay video. Except - * `streamingResolutions`, all other video transformations are supported. See - * [Video transformations](https://imagekit.io/docs/video-transformation). - */ - transformation?: Array; -} - -export interface SubtitleOverlay extends BaseOverlay { - /** - * Specifies the relative path to the subtitle file used as an overlay. - */ - input: string; - - type: 'subtitle'; - - /** - * The input path can be included in the layer as either `i-{input}` or - * `ie-{base64_encoded_input}`. By default, the SDK determines the appropriate - * format automatically. To always use base64 encoding (`ie-{base64}`), set this - * parameter to `base64`. To always use plain text (`i-{input}`), set it to - * `plain`. - * - * Regardless of the encoding method: - * - * - Leading and trailing slashes are removed. - * - Remaining slashes within the path are replaced with `@@` when using plain - * text. - */ - encoding?: 'auto' | 'plain' | 'base64'; - - /** - * Control styling of the subtitle. See - * [Styling subtitles](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer). - */ - transformation?: Array; -} - -export interface SolidColorOverlay extends BaseOverlay { - /** - * Specifies the color of the block using an RGB hex code (e.g., `FF0000`), an RGBA - * code (e.g., `FFAABB50`), or a color name (e.g., `red`). If an 8-character value - * is provided, the last two characters represent the opacity level (from `00` for - * 0.00 to `99` for 0.99). - */ - color: string; - - type: 'solidColor'; - - /** - * Control width and height of the solid color overlay. Supported transformations - * depend on the base/parent asset. See overlays on - * [Images](https://imagekit.io/docs/add-overlays-on-images#apply-transformation-on-solid-color-overlay) - * and - * [Videos](https://imagekit.io/docs/add-overlays-on-videos#apply-transformations-on-solid-color-block-overlay). - */ - transformation?: Array; -} - -export interface TextOverlayTransformation { - /** - * Specifies the transparency level of the text overlay. Accepts integers from `1` - * to `9`. - */ - alpha?: number; - - /** - * Specifies the background color of the text overlay. Accepts an RGB hex code, an - * RGBA code, or a color name. - */ - background?: string; - - /** - * Flip/mirror the text horizontally, vertically, or in both directions. Acceptable - * values: `h` (horizontal), `v` (vertical), `h_v` (horizontal and vertical), or - * `v_h`. - */ - flip?: 'h' | 'v' | 'h_v' | 'v_h'; - - /** - * Specifies the font color of the overlaid text. Accepts an RGB hex code (e.g., - * `FF0000`), an RGBA code (e.g., `FFAABB50`), or a color name. - */ - fontColor?: string; - - /** - * Specifies the font family of the overlaid text. Choose from the supported fonts - * list or use a custom font. See - * [Supported fonts](https://imagekit.io/docs/add-overlays-on-images#supported-text-font-list) - * and - * [Custom font](https://imagekit.io/docs/add-overlays-on-images#change-font-family-in-text-overlay). - */ - fontFamily?: string; - - /** - * Specifies the font size of the overlaid text. Accepts a numeric value or an - * arithmetic expression. - */ - fontSize?: number | string; - - /** - * Specifies the inner alignment of the text when width is more than the text - * length. - */ - innerAlignment?: 'left' | 'right' | 'center'; - - /** - * Specifies the line height for multi-line text overlays. It will come into effect - * only if the text wraps over multiple lines. Accepts either an integer value or - * an arithmetic expression. - */ - lineHeight?: number | string; - - /** - * Specifies the padding around the overlaid text. Can be provided as a single - * positive integer or multiple values separated by underscores (following CSS - * shorthand order). Arithmetic expressions are also accepted. - */ - padding?: number | string; - - /** - * Specifies the corner radius: - * - * - Single value (positive integer): Applied to all corners (e.g., `20`). - * - `max`: Creates a circular or oval shape. - * - Per-corner array: Provide four underscore-separated values representing - * top-left, top-right, bottom-right, and bottom-left corners respectively (e.g., - * `10_20_30_40`). See - * [Radius](https://imagekit.io/docs/effects-and-enhancements#radius---r). - */ - radius?: number | 'max' | string; - - /** - * Specifies the rotation angle of the text overlay. Accepts a numeric value for - * clockwise rotation or a string prefixed with "N" for counter-clockwise rotation. - */ - rotation?: number | string; - - /** - * Specifies the typography style of the text. Supported values: - * - * - Single styles: `b` (bold), `i` (italic), `strikethrough`. - * - Combinations: Any combination separated by underscores, e.g., `b_i`, - * `b_i_strikethrough`. - */ - typography?: string; - - /** - * Specifies the maximum width (in pixels) of the overlaid text. The text wraps - * automatically, and arithmetic expressions (e.g., `bw_mul_0.2` or `bh_div_2`) are - * supported. Useful when used in conjunction with the `background`. Learn about - * [Arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations). - */ - width?: number | string; -} - - -/** - * Subtitle styling options. - * [Learn more](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer) - * from the docs. - */ -export interface SubtitleOverlayTransformation { - /** - * Specifies the subtitle background color using a standard color name, an RGB - * color code (e.g., FF0000), or an RGBA color code (e.g., FFAABB50). - * - * [Subtitle styling options](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer) - */ - background?: string; - - /** - * Sets the font color of the subtitle text using a standard color name, an RGB - * color code (e.g., FF0000), or an RGBA color code (e.g., FFAABB50). - * - * [Subtitle styling options](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer) - */ - color?: string; - - /** - * Sets the font family of subtitle text. Refer to the - * [supported fonts documented](https://imagekit.io/docs/add-overlays-on-images#supported-text-font-list) - * in the ImageKit transformations guide. - */ - fontFamily?: string; - - /** - * Sets the font outline of the subtitle text. Requires the outline width (an - * integer) and the outline color (as an RGB color code, RGBA color code, or - * standard web color name) separated by an underscore. Example: `fol-2_blue` - * (outline width of 2px and outline color blue), `fol-2_A1CCDD` (outline width of - * 2px and outline color `#A1CCDD`) and `fol-2_A1CCDD50` (outline width of 2px and - * outline color `#A1CCDD` at 50% opacity). - * - * [Subtitle styling options](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer) - */ - fontOutline?: string; - - /** - * Sets the font shadow for the subtitle text. Requires the shadow color (as an RGB - * color code, RGBA color code, or standard web color name) and shadow indent (an - * integer) separated by an underscore. Example: `fsh-blue_2` (shadow color blue, - * indent of 2px), `fsh-A1CCDD_3` (shadow color `#A1CCDD`, indent of 3px), - * `fsh-A1CCDD50_3` (shadow color `#A1CCDD` at 50% opacity, indent of 3px). - * - * [Subtitle styling options](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer) - */ - fontShadow?: string; - - /** - * Sets the font size of subtitle text. - * - * [Subtitle styling options](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer) - */ - fontSize?: number; - - /** - * Sets the typography style of the subtitle text. Supports values are `b` for - * bold, `i` for italics, and `b_i` for bold with italics. - * - * [Subtitle styling options](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer) - */ - typography?: 'b' | 'i' | 'b_i'; -} - -export interface SolidColorOverlayTransformation { - /** - * Specifies the transparency level of the overlaid solid color layer. Supports - * integers from `1` to `9`. - */ - alpha?: number; - - /** - * Specifies the background color of the solid color overlay. Accepts an RGB hex - * code (e.g., `FF0000`), an RGBA code (e.g., `FFAABB50`), or a color name. - */ - background?: string; - - /** - * Creates a linear gradient with two colors. Pass `true` for a default gradient, - * or provide a string for a custom gradient. Only works if the base asset is an - * image. See - * [gradient](https://imagekit.io/docs/effects-and-enhancements#gradient---e-gradient). - */ - gradient?: true | string; - - /** - * Controls the height of the solid color overlay. Accepts a numeric value or an - * arithmetic expression. Learn about - * [arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations). - */ - height?: number | string; - - /** - * Specifies the corner radius of the solid color overlay. - * - * - Single value (positive integer): Applied to all corners (e.g., `20`). - * - `max`: Creates a circular or oval shape. - * - Per-corner array: Provide four underscore-separated values representing - * top-left, top-right, bottom-right, and bottom-left corners respectively (e.g., - * `10_20_30_40`). See - * [Radius](https://imagekit.io/docs/effects-and-enhancements#radius---r). - */ - radius?: number | 'max' | string; - - /** - * Controls the width of the solid color overlay. Accepts a numeric value or an - * arithmetic expression (e.g., `bw_mul_0.2` or `bh_div_2`). Learn about - * [arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations). - */ - width?: number | string; -} diff --git a/src/interfaces/UploadOptions.ts b/src/interfaces/UploadOptions.ts index 1eaed4b..e57fdc8 100644 --- a/src/interfaces/UploadOptions.ts +++ b/src/interfaces/UploadOptions.ts @@ -1,42 +1,4 @@ -interface TransformationObject { - type: "transformation"; - value: string; -} - -interface GifToVideoOrThumbnailObject { - type: "gif-to-video" | "thumbnail"; - value?: string; -} - -interface AbsObject { - type: "abs"; - value: string; - protocol: "hls" | "dash"; -} - -type PostTransformation = TransformationObject | GifToVideoOrThumbnailObject | AbsObject; - -interface Transformation { - /** - * Specifies pre-transformations to be applied. Must be a valid string of transformations like "w-300,h-300". - * Refer to the docs for more details on transformations. - * - * {@link https://imagekit.io/docs/dam/pre-and-post-transformation-on-upload#pre-transformation} - */ - pre?: string; - - /** - * Specifies post-transformations to be applied. This is an array of transformation objects, each with: - * - type: One of "transformation", "gif-to-video", "thumbnail", or "abs". - * - value: A valid transformation string required if "type" is "transformation" or "abs". Optional if "type" is "gif-to-video" or "thumbnail". - * - protocol: Used only when type is "abs". Can be "hls" or "dash". - * - * Refer to the docs for more details on transformations and usage in post. - * - * {@link https://imagekit.io/docs/dam/pre-and-post-transformation-on-upload#post-transformation} - */ - post?: PostTransformation[]; -} +import * as Shared from './shared'; /** * Options used when uploading a file using the V1 API. @@ -45,143 +7,214 @@ interface Transformation { */ export interface UploadOptions { /** - * This field accepts three main input formats for the file content: - * - "binary": Directly pass the binary data. Typically used when uploading via the browser using a File or Blob. - * - "base64": A base64-encoded string of the file content. - * - "url": A direct URL from which ImageKit server will download the file and upload. + * 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. */ file: string | Blob | File; /** - * The name with which the file should be uploaded. - * - Valid characters: alphanumeric (a-z, A-Z, 0-9, including Unicode letters and numerals) and the special chars ". _ -" - * - Any other character (including space) is replaced with "_" + * The name with which the file has to be uploaded. The file name can contain: * - * Example: "company_logo.png" + * - Alphanumeric Characters: `a-z`, `A-Z`, `0-9`. + * - Special Characters: `.`, `-` + * + * Any other character including space will be replaced by `_` */ fileName: string; /** - * The HMAC-SHA1 digest of the concatenation of "token + expire". The signing key is your ImageKit private API key. - * Required for client-side authentication. Must be computed on the server side. - * Calculate this signature in your secure server and pass it to the client. + * A unique value that the ImageKit.io server will use to recognize and prevent + * subsequent retries for the same request. We suggest using V4 UUIDs, or another + * random string with enough entropy to avoid collisions. + * + * **Note**: Sending a value 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 value for this field. */ - signature: string; + token: string; /** - * A unique value to identify and prevent replays. Typically a UUID (e.g., version 4). - * Each request must carry a fresh token. The server rejects reused tokens, even if the original request failed. + * Server-side checks to run on the asset. Read more about + * [Upload API checks](/docs/api-reference/upload-file/upload-file#upload-api-checks). */ - token: string; + checks?: string; /** - * A Unix timestamp in seconds, less than 1 hour in the future. + * Define an important area in the image. This is only relevant for image type + * files. + * + * - 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` + * - Can be used with fo-customtransformation. + * - If this field is not specified and the file is overwritten, then + * customCoordinates will be removed. */ - expire: number; + customCoordinates?: string; /** - * The public API key of your ImageKit account. You can find it in the [ImageKit dashboard](https://imagekit.io/dashboard/developer/api-keys). + * JSON key-value pairs to associate with the asset. Create the custom metadata + * fields before setting these values. */ - publicKey: string; + customMetadata?: { [key: string]: unknown }; /** - * Whether to use a unique filename for this file or not. - * - Accepts true or false. - * - If set true, ImageKit.io will add a unique suffix to the filename parameter to get a unique filename. - * - If set false, then the image is uploaded with the provided filename parameter and any existing file with the same name is replaced. - * Default value - true + * Optional text to describe the contents of the file. */ - useUniqueFileName?: boolean; + description?: string; /** - * Optionally set tags on the uploaded file. - * If passing an array, the SDK automatically joins them into a comma-separated string when sending to the server. - * Example: ["t-shirt", "round-neck", "men"] => "t-shirt,round-neck,men" + * The time until your signature is valid. It must be a + * [Unix time](https://en.wikipedia.org/wiki/Unix_time) in less than 1 hour into + * the future. It should be in seconds. */ - tags?: string | string[]; + expire: number; /** - * The folder path where the file will be stored, e.g., "/images/folder/". - * - If the path doesn't exist, it is created on-the-fly. - * - Nested folders are supported by using multiple "/". - * - Default: "/" + * Array of extensions to be applied to the asset. Each extension can be configured + * with specific parameters based on the extension type. + */ + extensions?: Shared.Extensions; + + /** + * 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. + * + * The folder name can contain: + * + * - Alphanumeric Characters: `a-z` , `A-Z` , `0-9` + * - Special Characters: `/` , `_` , `-` + * + * Using multiple `/` creates a nested folder. */ folder?: string; /** - * Whether to mark the file as private (only relevant for image uploads). - * A private file requires signed URLs or named transformations for access. - * Default: false + * 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. */ isPrivateFile?: boolean; /** - * A string in "x,y,width,height" format that defines the region of interest in an image (top-left coords and area size). - * Example: "10,10,100,100". + * 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?: string; + isPublished?: boolean; /** - * A comma-separated or array-based set of fields to return in the upload response. - * Example: "tags,customCoordinates,isPrivateFile,metadata" + * 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. */ - responseFields?: string | string[]; + overwriteAITags?: boolean; /** - * An array of extension objects to apply to the image, e.g. background removal, auto-tagging, etc. - * The SDK will JSON-stringify this array automatically before sending. + * If the request does not have `customMetadata`, and a file already exists at the + * exact location, existing customMetadata will be removed. */ - extensions?: object[]; + overwriteCustomMetadata?: boolean; /** - * A webhook URL to receive the final status of any pending extensions once they've completed processing. + * If `false` and `useUniqueFileName` is also `false`, and a file already exists at + * the exact location, upload API will return an error immediately. */ - webhookUrl?: string; + overwriteFile?: boolean; /** - * Defaults to true. If false, and "useUniqueFileName" is also false, the API immediately fails if a file with the same name/folder already exists. + * If the request does not have `tags`, and a file already exists at the exact + * location, existing tags will be removed. */ - overwriteFile?: boolean; + overwriteTags?: boolean; /** - * Defaults to true. If true, and an existing file is found at the same location, its AITags are removed. Set to false to keep existing AITags. + * The public API key of your ImageKit account. + * You can find it in the [ImageKit dashboard](https://imagekit.io/dashboard/developer/api-keys). */ - overwriteAITags?: boolean; + publicKey: string; /** - * Defaults to true. If no tags are specified in the request, existing tags are removed from overwritten files. Setting to false has no effect if the request includes tags. + * Array of response field keys to include in the API response body. */ - overwriteTags?: boolean; + responseFields?: Array< + | 'tags' + | 'customCoordinates' + | 'isPrivateFile' + | 'embeddedMetadata' + | 'isPublished' + | 'customMetadata' + | 'metadata' + | 'selectedFieldsSchema' + >; /** - * Defaults to true. If no customMetadata is specified in the request, existing customMetadata is removed from overwritten files. Setting to false has no effect if the request specifies customMetadata. + * The HMAC-SHA1 digest of the concatenation of "token + expire". The signing key is your ImageKit private API key. + * Calculate this signature in your secure server and pass it to the client. */ - overwriteCustomMetadata?: boolean; + signature: string; /** - * A stringified JSON or an object containing custom metadata fields to store with the file. - * Custom metadata fields must be pre-defined in your ImageKit configuration. + * 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. */ - customMetadata?: string | Record>; + tags?: Array; /** - * Defines pre and post transformations to be applied to the file during upload. The SDK enforces certain validation rules for pre/post transformations. - * For details, see: - * {@link https://imagekit.io/docs/dam/pre-and-post-transformation-on-upload} + * Configure pre-processing (`pre`) and post-processing (`post`) transformations. + * + * - `pre` — applied before the file is uploaded to the Media Library. + * Useful for reducing file size or applying basic optimizations upfront (e.g., + * resize, compress). + * + * - `post` — applied immediately after upload. + * Ideal for generating transformed versions (like video encodes or thumbnails) + * in advance, so they're ready for delivery without delay. + * + * You can mix and match any combination of post-processing types. */ - transformation?: Transformation; + transformation?: FileUploadParams.Transformation; /** - * An optional XMLHttpRequest instance for the upload. The SDK merges it with its own logic to handle progress events, etc. - * You can listen to `progress` or other events on this object for custom logic. + * 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. */ - xhr?: XMLHttpRequest; + useUniqueFileName?: boolean; /** - * A string specifying the checks to be performed server-side before uploading to the media library, e.g. size or mime type checks. - * For format details, see: {@link https://imagekit.io/docs/api-reference/upload-file/upload-file#upload-api-checks} + * 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. */ - checks?: string; + webhookUrl?: string; + + // JS SDK specific options + + /** + * An optional XMLHttpRequest instance for the upload. The SDK merges it with its own logic to handle progress events, etc. + * You can listen to `progress` or other events on this object for custom logic. + */ + xhr?: XMLHttpRequest; /** * Optional callback function that will be called with the progress event when the file is being uploaded. @@ -194,3 +227,96 @@ export interface UploadOptions { */ abortSignal?: AbortSignal; } + +export namespace FileUploadParams { + /** + * Configure pre-processing (`pre`) and post-processing (`post`) transformations. + * + * - `pre` — applied before the file is uploaded to the Media Library. + * Useful for reducing file size or applying basic optimizations upfront (e.g., + * resize, compress). + * + * - `post` — applied immediately after upload. + * Ideal for generating transformed versions (like video encodes or thumbnails) + * in advance, so they're ready for delivery without delay. + * + * You can mix and match any combination of post-processing types. + */ + export interface Transformation { + /** + * List of transformations to apply _after_ the file is uploaded. + * Each item must match one of the following types: `transformation`, + * `gif-to-video`, `thumbnail`, `abs`. + */ + post?: Array< + | Transformation.Transformation + | Transformation.GifToVideo + | Transformation.Thumbnail + | Transformation.Abs + >; + + /** + * Transformation string to apply before uploading the file to the Media Library. + * Useful for optimizing files at ingestion. + */ + pre?: string; + } + + export namespace Transformation { + export interface Transformation { + /** + * Transformation type. + */ + type: 'transformation'; + + /** + * Transformation string (e.g. `w-200,h-200`). + * Same syntax as ImageKit URL-based transformations. + */ + value: string; + } + + export interface GifToVideo { + /** + * Converts an animated GIF into an MP4. + */ + type: 'gif-to-video'; + + /** + * Optional transformation string to apply to the output video. + * **Example**: `q-80` + */ + value?: string; + } + + export interface Thumbnail { + /** + * Generates a thumbnail image. + */ + type: 'thumbnail'; + + /** + * Optional transformation string. + * **Example**: `w-150,h-150` + */ + value?: string; + } + + export interface Abs { + /** + * Streaming protocol to use (`hls` or `dash`). + */ + protocol: 'hls' | 'dash'; + + /** + * Adaptive Bitrate Streaming (ABS) setup. + */ + type: 'abs'; + + /** + * List of different representations you want to create separated by an underscore. + */ + value: string; + } + } +} \ No newline at end of file diff --git a/src/interfaces/UploadResponse.ts b/src/interfaces/UploadResponse.ts index dbae9c0..2c9f4e8 100644 --- a/src/interfaces/UploadResponse.ts +++ b/src/interfaces/UploadResponse.ts @@ -1,97 +1,223 @@ /** - * Type of files to include in result set. Accepts three values: - * all - include all types of files in result set - * image - only search in image type files - * non-image - only search in files which are not image, e.g., JS or CSS or video files. - * - * {@link https://imagekit.io/docs/api-reference/digital-asset-management-dam/list-and-search-assets} + * JSON object containing metadata. */ -type FileType = "all" | "image" | "non-image"; +export interface Metadata { + /** + * The audio codec used in the video (only for video). + */ + audioCodec?: string; -/** - * Metadata object structure - * - * {@link https://imagekit.io/docs/api-reference/file-metadata/get-uploaded-file-metadata#Responses} - * - * Contents of Object - * - * - Exif - * - * For more information about the Exif standard, please refer to the specification found on http://www.exif.org. A comprehensive list of available Exif attributes and their meaning can be found on http://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/. - * - * - Perceptual Hash (pHash) - * - * Perceptual hashing allows you to construct a hash value that uniquely identifies an input image based on the image's contents. It is different from cryptographic hash functions like MD5 and SHA1. pHash provides similar hash value after minor distortions, like small rotations, blurring, and compression in the image. - */ -interface Metadata { - height: number; - width: number; - size: number; - format: string; - hasColorProfile: boolean; - quality: number; - density: number; - hasTransparency: boolean; - pHash: string; - exif: { - image: { - Make: string; - Model: string; - Orientation: number; - XResolution: number; - YResolution: number; - ResolutionUnit: number; - Software: string; - ModifyDate: string; - YCbCrPositioning: number; - ExifOffset: number; - GPSInfo: number; - }; - thumbnail: { - Compression: number; - XResolution: number; - YResolution: number; - ResolutionUnit: number; - ThumbnailOffset: number; - ThumbnailLength: number; - }; - exif: { - ExposureTime: number; - FNumber: number; - ExposureProgram: number; - ISO: number; - ExifVersion: string; - DateTimeOriginal: string; - CreateDate: string; - ShutterSpeedValue: number; - ApertureValue: number; - ExposureCompensation: number; - MeteringMode: number; - Flash: number; - FocalLength: number; - SubSecTime: string; - SubSecTimeOriginal: string; - SubSecTimeDigitized: string; - FlashpixVersion: string; - ColorSpace: number; - ExifImageWidth: number; - ExifImageHeight: number; - InteropOffset: number; - FocalPlaneXResolution: number; - FocalPlaneYResolution: number; - FocalPlaneResolutionUnit: number; - CustomRendered: number; - ExposureMode: number; - WhiteBalance: number; - SceneCaptureType: number; - }; - gps: { GPSVersionID: number[] }; - interoperability: { - InteropIndex: string; - InteropVersion: string; - }; - makernote: any; - }; + /** + * The bit rate of the video in kbps (only for video). + */ + bitRate?: number; + + /** + * The density of the image in DPI. + */ + density?: number; + + /** + * The duration of the video in seconds (only for video). + */ + duration?: number; + + exif?: Metadata.Exif; + + /** + * The format of the file (e.g., 'jpg', 'mp4'). + */ + format?: string; + + /** + * Indicates if the image has a color profile. + */ + hasColorProfile?: boolean; + + /** + * Indicates if the image contains transparent areas. + */ + hasTransparency?: boolean; + + /** + * The height of the image or video in pixels. + */ + height?: number; + + /** + * Perceptual hash of the image. + */ + pHash?: string; + + /** + * The quality indicator of the image. + */ + quality?: number; + + /** + * The file size in bytes. + */ + size?: number; + + /** + * The video codec used in the video (only for video). + */ + videoCodec?: string; + + /** + * The width of the image or video in pixels. + */ + width?: number; +} + +export namespace Metadata { + export interface Exif { + /** + * Object containing Exif details. + */ + exif?: Exif.Exif; + + /** + * Object containing GPS information. + */ + gps?: Exif.Gps; + + /** + * Object containing EXIF image information. + */ + image?: Exif.Image; + + /** + * JSON object. + */ + interoperability?: Exif.Interoperability; + + makernote?: { [key: string]: unknown }; + + /** + * Object containing Thumbnail information. + */ + thumbnail?: Exif.Thumbnail; + } + + export namespace Exif { + /** + * Object containing Exif details. + */ + export interface Exif { + ApertureValue?: number; + + ColorSpace?: number; + + CreateDate?: string; + + CustomRendered?: number; + + DateTimeOriginal?: string; + + ExifImageHeight?: number; + + ExifImageWidth?: number; + + ExifVersion?: string; + + ExposureCompensation?: number; + + ExposureMode?: number; + + ExposureProgram?: number; + + ExposureTime?: number; + + Flash?: number; + + FlashpixVersion?: string; + + FNumber?: number; + + FocalLength?: number; + + FocalPlaneResolutionUnit?: number; + + FocalPlaneXResolution?: number; + + FocalPlaneYResolution?: number; + + InteropOffset?: number; + + ISO?: number; + + MeteringMode?: number; + + SceneCaptureType?: number; + + ShutterSpeedValue?: number; + + SubSecTime?: string; + + WhiteBalance?: number; + } + + /** + * Object containing GPS information. + */ + export interface Gps { + GPSVersionID?: Array; + } + + /** + * Object containing EXIF image information. + */ + export interface Image { + ExifOffset?: number; + + GPSInfo?: number; + + Make?: string; + + Model?: string; + + ModifyDate?: string; + + Orientation?: number; + + ResolutionUnit?: number; + + Software?: string; + + XResolution?: number; + + YCbCrPositioning?: number; + + YResolution?: number; + } + + /** + * JSON object. + */ + export interface Interoperability { + InteropIndex?: string; + + InteropVersion?: string; + } + + /** + * Object containing Thumbnail information. + */ + export interface Thumbnail { + Compression?: number; + + ResolutionUnit?: number; + + ThumbnailLength?: number; + + ThumbnailOffset?: number; + + XResolution?: number; + + YResolution?: number; + } + } } export interface ResponseMetadata { @@ -101,72 +227,166 @@ export interface ResponseMetadata { } /** - * Response from server when file is uploaded successfully. - * - * {@link https://imagekit.io/docs/api-reference/upload-file/upload-file#Responses} + * Object containing details of a successful upload. */ export interface UploadResponse { /** - * Unique fileId. Store this fileld in your database, as this will be used to perform update action on this file. + * An array of tags assigned to the uploaded file by auto tagging. */ - fileId?: string; + AITags?: Array | null; + /** - * The name of the uploaded file. + * The audio codec used in the video (only for video). */ - name?: string; + audioCodec?: string; + /** - * The URL of the file. + * The bit rate of the video in kbps (only for video). */ - url?: string; + bitRate?: number; + /** - * In case of an image, a small thumbnail URL. + * Value of custom coordinates associated with the image in the format + * `x,y,width,height`. If `customCoordinates` are not defined, then it is `null`. + * Send `customCoordinates` in `responseFields` in API request to get the value of + * this field. */ - thumbnailUrl?: string; + customCoordinates?: string | null; + /** - * Height of the uploaded image file. Only applicable when file type is image. + * A key-value data associated with the asset. Use `responseField` in API request + * to get `customMetadata` in the upload API response. Before setting any custom + * metadata on an asset, you have to create the field using custom metadata fields + * API. Send `customMetadata` in `responseFields` in API request to get the value + * of this field. */ - height?: number; + customMetadata?: { [key: string]: unknown }; + /** - * Width of the uploaded image file. Only applicable when file type is image. + * Optional text to describe the contents of the file. Can be set by the user or + * the ai-auto-description extension. */ - width?: number; + description?: string; + /** - * Size of the uploaded file in bytes. + * The duration of the video in seconds (only for video). */ - size?: number; + duration?: number; + + /** + * Consolidated embedded metadata associated with the file. It includes exif, iptc, + * and xmp data. Send `embeddedMetadata` in `responseFields` in API request to get + * embeddedMetadata in the upload API response. + */ + embeddedMetadata?: { [key: string]: unknown }; + /** - * Type of file. It can either be image or non-image. + * Extension names with their processing status at the time of completion of the + * request. It could have one of the following status values: + * + * `success`: The extension has been successfully applied. `failed`: The extension + * has failed and will not be retried. `pending`: The extension will finish + * processing in some time. On completion, the final status (success / failed) will + * be sent to the `webhookUrl` provided. + * + * If no extension was requested, then this parameter is not returned. */ - fileType?: FileType; + extensionStatus?: FileUploadResponse.ExtensionStatus; + + /** + * Unique fileId. Store this fileld in your database, as this will be used to + * perform update action on this file. + */ + fileId?: string; + /** - * The path of the file uploaded. It includes any folder that you specified while uploading. + * The relative path of the file in the media library e.g. + * `/marketing-assets/new-banner.jpg`. */ filePath?: string; + /** - * Array of tags associated with the image. + * Type of the uploaded file. Possible values are `image`, `non-image`. */ - tags?: string[]; + fileType?: string; + + /** + * Height of the image in pixels (Only for images) + */ + height?: number; + /** - * Is the file marked as private. It can be either true or false. + * 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. */ isPrivateFile?: boolean; + /** - * Value of custom coordinates associated with the image in format x,y,width,height. + * Is the file published or in draft state. It can be either `true` or `false`. + * Send `isPublished` in `responseFields` in API request to get the value of this + * field. */ - customCoordinates?: string | null; + isPublished?: boolean; + /** - * The metadata of the upload file. Use responseFields property in request to get the metadata returned in response of upload API. + * Legacy metadata. Send `metadata` in `responseFields` in API request to get + * metadata in the upload API response. */ metadata?: Metadata; - /* - * AITags field is populated only because the google-auto-tagging extension was executed synchronously and it received a successresponse. + + /** + * Name of the asset. */ - AITags?: object[]; + name?: string; - /* - * Field object which will contain the status of each extension at the time of completion of the update/upload request. - */ - extensionStatus?: { [key: string]: string } + /** + * 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. + */ + selectedFieldsSchema?: { [key: string]: FileUploadResponse.SelectedFieldsSchema }; + + /** + * Size of the image file in Bytes. + */ + size?: number; + + /** + * 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. + */ + tags?: Array | null; + + /** + * In the case of an image, a small thumbnail URL. + */ + thumbnailUrl?: string; + + /** + * A publicly accessible URL of the file. + */ + url?: string; + + /** + * An object containing the file or file version's `id` (versionId) and `name`. + */ + versionInfo?: FileUploadResponse.VersionInfo; + + /** + * The video codec used in the video (only for video). + */ + videoCodec?: string; + + /** + * Width of the image in pixels (Only for Images) + */ + width?: number; /** * Message indicating that the file upload is accepted. This field is only present when the upload is accepted but not yet processed. @@ -180,3 +400,122 @@ export interface UploadResponse { */ readonly $ResponseMetadata: ResponseMetadata; } + +export namespace FileUploadResponse { + export interface AITag { + /** + * Confidence score of the tag. + */ + confidence?: number; + + /** + * Name of the tag. + */ + name?: string; + + /** + * Array of `AITags` associated with the image. If no `AITags` are set, it will be + * null. These tags can be added using the `google-auto-tagging` or + * `aws-auto-tagging` extensions. + */ + source?: string; + } + + /** + * Extension names with their processing status at the time of completion of the + * request. It could have one of the following status values: + * + * `success`: The extension has been successfully applied. `failed`: The extension + * has failed and will not be retried. `pending`: The extension will finish + * processing in some time. On completion, the final status (success / failed) will + * be sent to the `webhookUrl` provided. + * + * If no extension was requested, then this parameter is not returned. + */ + export interface ExtensionStatus { + 'ai-auto-description'?: 'success' | 'pending' | 'failed'; + + 'ai-tasks'?: 'success' | 'pending' | 'failed'; + + 'aws-auto-tagging'?: 'success' | 'pending' | 'failed'; + + 'google-auto-tagging'?: 'success' | 'pending' | 'failed'; + + 'remove-bg'?: 'success' | 'pending' | 'failed'; + } + + export interface SelectedFieldsSchema { + /** + * Type of the custom metadata field. + */ + type: 'Text' | 'Textarea' | 'Number' | 'Date' | 'Boolean' | 'SingleSelect' | 'MultiSelect'; + + /** + * The default value for this custom metadata field. The value should match the + * `type` of custom metadata field. + */ + defaultValue?: string | number | boolean | Array; + + /** + * Specifies if the custom metadata field is required or not. + */ + isValueRequired?: boolean; + + /** + * Maximum length of string. Only set if `type` is set to `Text` or `Textarea`. + */ + maxLength?: number; + + /** + * 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. + */ + maxValue?: string | number; + + /** + * Minimum length of string. Only set if `type` is set to `Text` or `Textarea`. + */ + minLength?: number; + + /** + * 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. + */ + minValue?: string | number; + + /** + * 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. + */ + readOnly?: boolean; + + /** + * An array of allowed values when field type is `SingleSelect` or `MultiSelect`. + */ + selectOptions?: Array; + + /** + * Specifies if the selectOptions array is truncated. It is truncated when number + * of options are > 100. + */ + selectOptionsTruncated?: boolean; + } + + /** + * An object containing the file or file version's `id` (versionId) and `name`. + */ + export interface VersionInfo { + /** + * Unique identifier of the file version. + */ + id?: string; + + /** + * Name of the file version. + */ + name?: string; + } +} \ No newline at end of file diff --git a/src/interfaces/index.ts b/src/interfaces/index.ts index 5aacf10..639daaf 100644 --- a/src/interfaces/index.ts +++ b/src/interfaces/index.ts @@ -1,7 +1,6 @@ // src/interfaces/index.ts // Re-export all interfaces so that TypeDoc includes referenced types in the documentation +export * from './shared'; export * from './UploadResponse'; -export * from './UploadOptions'; -export * from './Transformation'; -export * from './SrcOptions'; +export * from './UploadOptions'; \ No newline at end of file diff --git a/src/interfaces/shared.ts b/src/interfaces/shared.ts new file mode 100644 index 0000000..ad8245e --- /dev/null +++ b/src/interfaces/shared.ts @@ -0,0 +1,1725 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +export interface BaseOverlay { + /** + * Controls how the layer blends with the base image or underlying content. Maps to + * `lm` in the URL. By default, layers completely cover the base image beneath + * them. Layer modes change this behavior: + * + * - `multiply`: Multiplies the pixel values of the layer with the base image. The + * result is always darker than the original images. This is ideal for applying + * shadows or color tints. + * - `displace`: Uses the layer as a displacement map to distort pixels in the base + * image. The red channel controls horizontal displacement, and the green channel + * controls vertical displacement. Requires `x` or `y` parameter to control + * displacement magnitude. + * - `cutout`: Acts as an inverse mask where opaque areas of the layer turn the + * base image transparent, while transparent areas leave the base image + * unchanged. This mode functions like a hole-punch, effectively cutting the + * shape of the layer out of the underlying image. + * - `cutter`: Acts as a shape mask where only the parts of the base image that + * fall inside the opaque area of the layer are preserved. This mode functions + * like a cookie-cutter, trimming the base image to match the specific dimensions + * and shape of the layer. See + * [Layer modes](https://imagekit.io/docs/add-overlays-on-images#layer-modes). + */ + layerMode?: 'multiply' | 'cutter' | 'cutout' | 'displace'; + + /** + * Specifies the overlay's position relative to the parent asset. See + * [Position of Layer](https://imagekit.io/docs/transformations#position-of-layer). + */ + position?: OverlayPosition; + + /** + * Specifies timing information for the overlay (only applicable if the base asset + * is a video). See + * [Position of Layer](https://imagekit.io/docs/transformations#position-of-layer). + */ + timing?: OverlayTiming; +} + +/** + * Configuration object for an extension (base extensions only, not saved extension + * references). + */ +export type ExtensionConfig = + | ExtensionConfig.RemoveBg + | ExtensionConfig.AutoTaggingExtension + | ExtensionConfig.AIAutoDescription + | ExtensionConfig.AITasks; + +export namespace ExtensionConfig { + export interface RemoveBg { + /** + * Specifies the background removal extension. + */ + name: 'remove-bg'; + + options?: RemoveBg.Options; + } + + export namespace RemoveBg { + export interface Options { + /** + * Whether to add an artificial shadow to the result. Default is false. Note: + * Adding shadows is currently only supported for car photos. + */ + add_shadow?: boolean; + + /** + * 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_color?: string; + + /** + * Sets a background image from a URL. If this parameter is set, `bg_color` must be + * empty. + */ + bg_image_url?: string; + + /** + * Allows semi-transparent regions in the result. Default is true. Note: + * Semitransparency is currently only supported for car windows. + */ + semitransparency?: boolean; + } + } + + export interface AutoTaggingExtension { + /** + * Maximum number of tags to attach to the asset. + */ + maxTags: number; + + /** + * Minimum confidence level for tags to be considered valid. + */ + minConfidence: number; + + /** + * Specifies the auto-tagging extension used. + */ + name: 'google-auto-tagging' | 'aws-auto-tagging'; + } + + export interface AIAutoDescription { + /** + * Specifies the auto description extension. + */ + name: 'ai-auto-description'; + } + + export interface AITasks { + /** + * Specifies the AI tasks extension for automated image analysis using AI models. + */ + name: 'ai-tasks'; + + /** + * Array of task objects defining AI operations to perform on the asset. + */ + tasks: Array; + } + + export namespace AITasks { + export interface SelectTags { + /** + * The question or instruction for the AI to analyze the image. + */ + instruction: string; + + /** + * Task type that analyzes the image and adds matching tags from a vocabulary. + */ + type: 'select_tags'; + + /** + * Array of possible tag values. Combined length of all strings must not exceed 500 + * characters. Cannot contain the `%` character. + */ + vocabulary: Array; + + /** + * Maximum number of tags to select from the vocabulary. + */ + max_selections?: number; + + /** + * Minimum number of tags to select from the vocabulary. + */ + min_selections?: number; + } + + export interface SelectMetadata { + /** + * Name of the custom metadata field to set. The field must exist in your account. + */ + field: string; + + /** + * The question or instruction for the AI to analyze the image. + */ + instruction: string; + + /** + * Task type that analyzes the image and sets a custom metadata field value from a + * vocabulary. + */ + type: 'select_metadata'; + + /** + * Maximum number of values to select from the vocabulary. + */ + max_selections?: number; + + /** + * Minimum number of values to select from the vocabulary. + */ + min_selections?: number; + + /** + * Array of possible values matching the custom metadata field type. + */ + vocabulary?: Array; + } + + export interface YesNo { + /** + * The yes/no question for the AI to answer about the image. + */ + instruction: string; + + /** + * Task type that asks a yes/no question and executes actions based on the answer. + */ + type: 'yes_no'; + + /** + * Actions to execute if the AI answers no. + */ + on_no?: YesNo.OnNo; + + /** + * Actions to execute if the AI cannot determine the answer. + */ + on_unknown?: YesNo.OnUnknown; + + /** + * Actions to execute if the AI answers yes. + */ + on_yes?: YesNo.OnYes; + } + + export namespace YesNo { + /** + * Actions to execute if the AI answers no. + */ + export interface OnNo { + /** + * Array of tag strings to add to the asset. + */ + add_tags?: Array; + + /** + * Array of tag strings to remove from the asset. + */ + remove_tags?: Array; + + /** + * Array of custom metadata field updates. + */ + set_metadata?: Array; + + /** + * Array of custom metadata fields to remove. + */ + unset_metadata?: Array; + } + + export namespace OnNo { + export interface SetMetadata { + /** + * Name of the custom metadata field to set. + */ + field: string; + + /** + * Value to set for the custom metadata field. The value type should match the + * custom metadata field type. + */ + value: string | number | boolean | Array; + } + + export interface UnsetMetadata { + /** + * Name of the custom metadata field to remove. + */ + field: string; + } + } + + /** + * Actions to execute if the AI cannot determine the answer. + */ + export interface OnUnknown { + /** + * Array of tag strings to add to the asset. + */ + add_tags?: Array; + + /** + * Array of tag strings to remove from the asset. + */ + remove_tags?: Array; + + /** + * Array of custom metadata field updates. + */ + set_metadata?: Array; + + /** + * Array of custom metadata fields to remove. + */ + unset_metadata?: Array; + } + + export namespace OnUnknown { + export interface SetMetadata { + /** + * Name of the custom metadata field to set. + */ + field: string; + + /** + * Value to set for the custom metadata field. The value type should match the + * custom metadata field type. + */ + value: string | number | boolean | Array; + } + + export interface UnsetMetadata { + /** + * Name of the custom metadata field to remove. + */ + field: string; + } + } + + /** + * Actions to execute if the AI answers yes. + */ + export interface OnYes { + /** + * Array of tag strings to add to the asset. + */ + add_tags?: Array; + + /** + * Array of tag strings to remove from the asset. + */ + remove_tags?: Array; + + /** + * Array of custom metadata field updates. + */ + set_metadata?: Array; + + /** + * Array of custom metadata fields to remove. + */ + unset_metadata?: Array; + } + + export namespace OnYes { + export interface SetMetadata { + /** + * Name of the custom metadata field to set. + */ + field: string; + + /** + * Value to set for the custom metadata field. The value type should match the + * custom metadata field type. + */ + value: string | number | boolean | Array; + } + + export interface UnsetMetadata { + /** + * Name of the custom metadata field to remove. + */ + field: string; + } + } + } + } +} + +/** + * Array of extensions to be applied to the asset. Each extension can be configured + * with specific parameters based on the extension type. + */ +export type Extensions = Array< + | Extensions.RemoveBg + | Extensions.AutoTaggingExtension + | Extensions.AIAutoDescription + | Extensions.AITasks + | Extensions.SavedExtension +>; + +export namespace Extensions { + export interface RemoveBg { + /** + * Specifies the background removal extension. + */ + name: 'remove-bg'; + + options?: RemoveBg.Options; + } + + export namespace RemoveBg { + export interface Options { + /** + * Whether to add an artificial shadow to the result. Default is false. Note: + * Adding shadows is currently only supported for car photos. + */ + add_shadow?: boolean; + + /** + * 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_color?: string; + + /** + * Sets a background image from a URL. If this parameter is set, `bg_color` must be + * empty. + */ + bg_image_url?: string; + + /** + * Allows semi-transparent regions in the result. Default is true. Note: + * Semitransparency is currently only supported for car windows. + */ + semitransparency?: boolean; + } + } + + export interface AutoTaggingExtension { + /** + * Maximum number of tags to attach to the asset. + */ + maxTags: number; + + /** + * Minimum confidence level for tags to be considered valid. + */ + minConfidence: number; + + /** + * Specifies the auto-tagging extension used. + */ + name: 'google-auto-tagging' | 'aws-auto-tagging'; + } + + export interface AIAutoDescription { + /** + * Specifies the auto description extension. + */ + name: 'ai-auto-description'; + } + + export interface AITasks { + /** + * Specifies the AI tasks extension for automated image analysis using AI models. + */ + name: 'ai-tasks'; + + /** + * Array of task objects defining AI operations to perform on the asset. + */ + tasks: Array; + } + + export namespace AITasks { + export interface SelectTags { + /** + * The question or instruction for the AI to analyze the image. + */ + instruction: string; + + /** + * Task type that analyzes the image and adds matching tags from a vocabulary. + */ + type: 'select_tags'; + + /** + * Array of possible tag values. Combined length of all strings must not exceed 500 + * characters. Cannot contain the `%` character. + */ + vocabulary: Array; + + /** + * Maximum number of tags to select from the vocabulary. + */ + max_selections?: number; + + /** + * Minimum number of tags to select from the vocabulary. + */ + min_selections?: number; + } + + export interface SelectMetadata { + /** + * Name of the custom metadata field to set. The field must exist in your account. + */ + field: string; + + /** + * The question or instruction for the AI to analyze the image. + */ + instruction: string; + + /** + * Task type that analyzes the image and sets a custom metadata field value from a + * vocabulary. + */ + type: 'select_metadata'; + + /** + * Maximum number of values to select from the vocabulary. + */ + max_selections?: number; + + /** + * Minimum number of values to select from the vocabulary. + */ + min_selections?: number; + + /** + * Array of possible values matching the custom metadata field type. + */ + vocabulary?: Array; + } + + export interface YesNo { + /** + * The yes/no question for the AI to answer about the image. + */ + instruction: string; + + /** + * Task type that asks a yes/no question and executes actions based on the answer. + */ + type: 'yes_no'; + + /** + * Actions to execute if the AI answers no. + */ + on_no?: YesNo.OnNo; + + /** + * Actions to execute if the AI cannot determine the answer. + */ + on_unknown?: YesNo.OnUnknown; + + /** + * Actions to execute if the AI answers yes. + */ + on_yes?: YesNo.OnYes; + } + + export namespace YesNo { + /** + * Actions to execute if the AI answers no. + */ + export interface OnNo { + /** + * Array of tag strings to add to the asset. + */ + add_tags?: Array; + + /** + * Array of tag strings to remove from the asset. + */ + remove_tags?: Array; + + /** + * Array of custom metadata field updates. + */ + set_metadata?: Array; + + /** + * Array of custom metadata fields to remove. + */ + unset_metadata?: Array; + } + + export namespace OnNo { + export interface SetMetadata { + /** + * Name of the custom metadata field to set. + */ + field: string; + + /** + * Value to set for the custom metadata field. The value type should match the + * custom metadata field type. + */ + value: string | number | boolean | Array; + } + + export interface UnsetMetadata { + /** + * Name of the custom metadata field to remove. + */ + field: string; + } + } + + /** + * Actions to execute if the AI cannot determine the answer. + */ + export interface OnUnknown { + /** + * Array of tag strings to add to the asset. + */ + add_tags?: Array; + + /** + * Array of tag strings to remove from the asset. + */ + remove_tags?: Array; + + /** + * Array of custom metadata field updates. + */ + set_metadata?: Array; + + /** + * Array of custom metadata fields to remove. + */ + unset_metadata?: Array; + } + + export namespace OnUnknown { + export interface SetMetadata { + /** + * Name of the custom metadata field to set. + */ + field: string; + + /** + * Value to set for the custom metadata field. The value type should match the + * custom metadata field type. + */ + value: string | number | boolean | Array; + } + + export interface UnsetMetadata { + /** + * Name of the custom metadata field to remove. + */ + field: string; + } + } + + /** + * Actions to execute if the AI answers yes. + */ + export interface OnYes { + /** + * Array of tag strings to add to the asset. + */ + add_tags?: Array; + + /** + * Array of tag strings to remove from the asset. + */ + remove_tags?: Array; + + /** + * Array of custom metadata field updates. + */ + set_metadata?: Array; + + /** + * Array of custom metadata fields to remove. + */ + unset_metadata?: Array; + } + + export namespace OnYes { + export interface SetMetadata { + /** + * Name of the custom metadata field to set. + */ + field: string; + + /** + * Value to set for the custom metadata field. The value type should match the + * custom metadata field type. + */ + value: string | number | boolean | Array; + } + + export interface UnsetMetadata { + /** + * Name of the custom metadata field to remove. + */ + field: string; + } + } + } + } + + export interface SavedExtension { + /** + * The unique ID of the saved extension to apply. + */ + id: string; + + /** + * Indicates this is a reference to a saved extension. + */ + name: 'saved-extension'; + } +} + +/** + * Options for generating responsive image attributes including `src`, `srcSet`, + * and `sizes` for HTML `` elements. This schema extends `SrcOptions` to add + * support for responsive image generation with breakpoints. + */ +export interface GetImageAttributesOptions extends SrcOptions { + /** + * Custom list of **device-width breakpoints** in pixels. These define common + * screen widths for responsive image generation. + * + * Defaults to `[640, 750, 828, 1080, 1200, 1920, 2048, 3840]`. Sorted + * automatically. + */ + deviceBreakpoints?: Array; + + /** + * Custom list of **image-specific breakpoints** in pixels. Useful for generating + * small variants (e.g., placeholders or thumbnails). + * + * Merged with `deviceBreakpoints` before calculating `srcSet`. Defaults to + * `[16, 32, 48, 64, 96, 128, 256, 384]`. Sorted automatically. + */ + imageBreakpoints?: Array; + + /** + * The value for the HTML `sizes` attribute (e.g., `"100vw"` or + * `"(min-width:768px) 50vw, 100vw"`). + * + * - If it includes one or more `vw` units, breakpoints smaller than the + * corresponding percentage of the smallest device width are excluded. + * - If it contains no `vw` units, the full breakpoint list is used. + * + * Enables a width-based strategy and generates `w` descriptors in `srcSet`. + */ + sizes?: string; + + /** + * The intended display width of the image in pixels, used **only when the `sizes` + * attribute is not provided**. + * + * Triggers a DPR-based strategy (1x and 2x variants) and generates `x` descriptors + * in `srcSet`. + * + * Ignored if `sizes` is present. + */ + width?: number; +} + +export interface ImageOverlay extends BaseOverlay { + /** + * Specifies the relative path to the image used as an overlay. + */ + input: string; + + type: 'image'; + + /** + * The input path can be included in the layer as either `i-{input}` or + * `ie-{base64_encoded_input}`. By default, the SDK determines the appropriate + * format automatically. To always use base64 encoding (`ie-{base64}`), set this + * parameter to `base64`. To always use plain text (`i-{input}`), set it to + * `plain`. + * + * Regardless of the encoding method: + * + * - Leading and trailing slashes are removed. + * - Remaining slashes within the path are replaced with `@@` when using plain + * text. + */ + encoding?: 'auto' | 'plain' | 'base64'; + + /** + * Array of transformations to be applied to the overlay image. Supported + * transformations depends on the base/parent asset. See overlays on + * [Images](https://imagekit.io/docs/add-overlays-on-images#list-of-supported-image-transformations-in-image-layers) + * and + * [Videos](https://imagekit.io/docs/add-overlays-on-videos#list-of-transformations-supported-on-image-overlay). + */ + transformation?: Array; +} + +/** + * Specifies an overlay to be applied on the parent image or video. ImageKit + * supports overlays including images, text, videos, subtitles, and solid colors. + * See + * [Overlay using layers](https://imagekit.io/docs/transformations#overlay-using-layers). + */ +export type Overlay = TextOverlay | ImageOverlay | VideoOverlay | SubtitleOverlay | SolidColorOverlay; + +export interface OverlayPosition { + /** + * Specifies the position of the overlay relative to the parent image or video. + * Maps to `lfo` in the URL. + */ + focus?: + | 'center' + | 'top' + | 'left' + | 'bottom' + | 'right' + | 'top_left' + | 'top_right' + | 'bottom_left' + | 'bottom_right'; + + /** + * Specifies the x-coordinate of the top-left corner of the base asset where the + * overlay's top-left corner will be positioned. It also accepts arithmetic + * expressions such as `bw_mul_0.4` or `bw_sub_cw`. Maps to `lx` in the URL. Learn + * about + * [Arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations). + */ + x?: number | string; + + /** + * Specifies the y-coordinate of the top-left corner of the base asset where the + * overlay's top-left corner will be positioned. It also accepts arithmetic + * expressions such as `bh_mul_0.4` or `bh_sub_ch`. Maps to `ly` in the URL. Learn + * about + * [Arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations). + */ + y?: number | string; +} + +export interface OverlayTiming { + /** + * Specifies the duration (in seconds) during which the overlay should appear on + * the base video. Accepts a positive number up to two decimal places (e.g., `20` + * or `20.50`) and arithmetic expressions such as `bdu_mul_0.4` or `bdu_sub_idu`. + * Applies only if the base asset is a video. Maps to `ldu` in the URL. + */ + duration?: number | string; + + /** + * Specifies the end time (in seconds) for when the overlay should disappear from + * the base video. If both end and duration are provided, duration is ignored. + * Accepts a positive number up to two decimal places (e.g., `20` or `20.50`) and + * arithmetic expressions such as `bdu_mul_0.4` or `bdu_sub_idu`. Applies only if + * the base asset is a video. Maps to `leo` in the URL. + */ + end?: number | string; + + /** + * Specifies the start time (in seconds) for when the overlay should appear on the + * base video. Accepts a positive number up to two decimal places (e.g., `20` or + * `20.50`) and arithmetic expressions such as `bdu_mul_0.4` or `bdu_sub_idu`. + * Applies only if the base asset is a video. Maps to `lso` in the URL. + */ + start?: number | string; +} + +/** + * Resulting set of attributes suitable for an HTML `` element. Useful for + * enabling responsive image loading with `srcSet` and `sizes`. + */ +export interface ResponsiveImageAttributes { + /** + * URL for the _largest_ candidate (assigned to plain `src`). + */ + src: string; + + /** + * `sizes` returned (or synthesised as `100vw`). The value for the HTML `sizes` + * attribute. + */ + sizes?: string; + + /** + * Candidate set with `w` or `x` descriptors. Multiple image URLs separated by + * commas, each with a descriptor. + */ + srcSet?: string; + + /** + * Width as a number (if `width` was provided in the input options). + */ + width?: number; +} + +/** + * Saved extension object containing extension configuration. + */ +export interface SavedExtension { + /** + * Unique identifier of the saved extension. + */ + id?: string; + + /** + * Configuration object for an extension (base extensions only, not saved extension + * references). + */ + config?: ExtensionConfig; + + /** + * Timestamp when the saved extension was created. + */ + createdAt?: string; + + /** + * Description of the saved extension. + */ + description?: string; + + /** + * Name of the saved extension. + */ + name?: string; + + /** + * Timestamp when the saved extension was last updated. + */ + updatedAt?: string; +} + +export interface SolidColorOverlay extends BaseOverlay { + /** + * Specifies the color of the block using an RGB hex code (e.g., `FF0000`), an RGBA + * code (e.g., `FFAABB50`), or a color name (e.g., `red`). If an 8-character value + * is provided, the last two characters represent the opacity level (from `00` for + * 0.00 to `99` for 0.99). + */ + color: string; + + type: 'solidColor'; + + /** + * Control width and height of the solid color overlay. Supported transformations + * depend on the base/parent asset. See overlays on + * [Images](https://imagekit.io/docs/add-overlays-on-images#apply-transformation-on-solid-color-overlay) + * and + * [Videos](https://imagekit.io/docs/add-overlays-on-videos#apply-transformations-on-solid-color-block-overlay). + */ + transformation?: Array; +} + +export interface SolidColorOverlayTransformation { + /** + * Specifies the transparency level of the overlaid solid color layer. Supports + * integers from `1` to `9`. + */ + alpha?: number; + + /** + * Specifies the background color of the solid color overlay. Accepts an RGB hex + * code (e.g., `FF0000`), an RGBA code (e.g., `FFAABB50`), or a color name. + */ + background?: string; + + /** + * Creates a linear gradient with two colors. Pass `true` for a default gradient, + * or provide a string for a custom gradient. Only works if the base asset is an + * image. See + * [gradient](https://imagekit.io/docs/effects-and-enhancements#gradient---e-gradient). + */ + gradient?: true | string; + + /** + * Controls the height of the solid color overlay. Accepts a numeric value or an + * arithmetic expression. Learn about + * [arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations). + */ + height?: number | string; + + /** + * Specifies the corner radius of the solid color overlay. + * + * - Single value (positive integer): Applied to all corners (e.g., `20`). + * - `max`: Creates a circular or oval shape. + * - Per-corner array: Provide four underscore-separated values representing + * top-left, top-right, bottom-right, and bottom-left corners respectively (e.g., + * `10_20_30_40`). See + * [Radius](https://imagekit.io/docs/effects-and-enhancements#radius---r). + */ + radius?: number | 'max' | string; + + /** + * Controls the width of the solid color overlay. Accepts a numeric value or an + * arithmetic expression (e.g., `bw_mul_0.2` or `bh_div_2`). Learn about + * [arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations). + */ + width?: number | string; +} + +/** + * Options for generating ImageKit URLs with transformations. See the + * [Transformations guide](https://imagekit.io/docs/transformations). + */ +export interface SrcOptions { + /** + * Accepts a relative or absolute path of the resource. If a relative path is + * provided, it is appended to the `urlEndpoint`. If an absolute path is provided, + * `urlEndpoint` is ignored. + */ + src: string; + + /** + * Get your urlEndpoint from the + * [ImageKit dashboard](https://imagekit.io/dashboard/url-endpoints). + */ + urlEndpoint: string; + + /** + * These are additional query parameters that you want to add to the final URL. + * They can be any query parameters and not necessarily related to ImageKit. This + * is especially useful if you want to add a versioning parameter to your URLs. + */ + queryParameters?: { [key: string]: string | number }; + + /** + * An array of objects specifying the transformations to be applied in the URL. If + * more than one transformation is specified, they are applied in the order they + * are specified as chained transformations. See + * [Chained transformations](https://imagekit.io/docs/transformations#chained-transformations). + */ + transformation?: Array; + + /** + * By default, the transformation string is added as a query parameter in the URL, + * e.g., `?tr=w-100,h-100`. If you want to add the transformation string in the + * path of the URL, set this to `path`. Learn more in the + * [Transformations guide](https://imagekit.io/docs/transformations). + */ + transformationPosition?: TransformationPosition; +} + +/** + * Available streaming resolutions for + * [adaptive bitrate streaming](https://imagekit.io/docs/adaptive-bitrate-streaming) + */ +export type StreamingResolution = '240' | '360' | '480' | '720' | '1080' | '1440' | '2160'; + +export interface SubtitleOverlay extends BaseOverlay { + /** + * Specifies the relative path to the subtitle file used as an overlay. + */ + input: string; + + type: 'subtitle'; + + /** + * The input path can be included in the layer as either `i-{input}` or + * `ie-{base64_encoded_input}`. By default, the SDK determines the appropriate + * format automatically. To always use base64 encoding (`ie-{base64}`), set this + * parameter to `base64`. To always use plain text (`i-{input}`), set it to + * `plain`. + * + * Regardless of the encoding method: + * + * - Leading and trailing slashes are removed. + * - Remaining slashes within the path are replaced with `@@` when using plain + * text. + */ + encoding?: 'auto' | 'plain' | 'base64'; + + /** + * Control styling of the subtitle. See + * [Styling subtitles](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer). + */ + transformation?: Array; +} + +/** + * Subtitle styling options. + * [Learn more](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer) + * from the docs. + */ +export interface SubtitleOverlayTransformation { + /** + * Specifies the subtitle background color using a standard color name, an RGB + * color code (e.g., FF0000), or an RGBA color code (e.g., FFAABB50). + * + * [Subtitle styling options](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer) + */ + background?: string; + + /** + * Sets the font color of the subtitle text using a standard color name, an RGB + * color code (e.g., FF0000), or an RGBA color code (e.g., FFAABB50). + * + * [Subtitle styling options](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer) + */ + color?: string; + + /** + * Sets the font family of subtitle text. Refer to the + * [supported fonts documented](https://imagekit.io/docs/add-overlays-on-images#supported-text-font-list) + * in the ImageKit transformations guide. + */ + fontFamily?: string; + + /** + * Sets the font outline of the subtitle text. Requires the outline width (an + * integer) and the outline color (as an RGB color code, RGBA color code, or + * standard web color name) separated by an underscore. Example: `fol-2_blue` + * (outline width of 2px and outline color blue), `fol-2_A1CCDD` (outline width of + * 2px and outline color `#A1CCDD`) and `fol-2_A1CCDD50` (outline width of 2px and + * outline color `#A1CCDD` at 50% opacity). + * + * [Subtitle styling options](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer) + */ + fontOutline?: string; + + /** + * Sets the font shadow for the subtitle text. Requires the shadow color (as an RGB + * color code, RGBA color code, or standard web color name) and shadow indent (an + * integer) separated by an underscore. Example: `fsh-blue_2` (shadow color blue, + * indent of 2px), `fsh-A1CCDD_3` (shadow color `#A1CCDD`, indent of 3px), + * `fsh-A1CCDD50_3` (shadow color `#A1CCDD` at 50% opacity, indent of 3px). + * + * [Subtitle styling options](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer) + */ + fontShadow?: string; + + /** + * Sets the font size of subtitle text. + * + * [Subtitle styling options](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer) + */ + fontSize?: number; + + /** + * Sets the typography style of the subtitle text. Supports values are `b` for + * bold, `i` for italics, and `b_i` for bold with italics. + * + * [Subtitle styling options](https://imagekit.io/docs/add-overlays-on-videos#styling-controls-for-subtitles-layer) + */ + typography?: 'b' | 'i' | 'b_i'; +} + +export interface TextOverlay extends BaseOverlay { + /** + * Specifies the text to be displayed in the overlay. The SDK automatically handles + * special characters and encoding. + */ + text: string; + + type: 'text'; + + /** + * Text can be included in the layer as either `i-{input}` (plain text) or + * `ie-{base64_encoded_input}` (base64). By default, the SDK selects the + * appropriate format based on the input text. To always use base64 + * (`ie-{base64}`), set this parameter to `base64`. To always use plain text + * (`i-{input}`), set it to `plain`. + * + * Regardless of the encoding method, the input text is always percent-encoded to + * ensure it is URL-safe. + */ + encoding?: 'auto' | 'plain' | 'base64'; + + /** + * Control styling of the text overlay. See + * [Text overlays](https://imagekit.io/docs/add-overlays-on-images#text-overlay). + */ + transformation?: Array; +} + +export interface TextOverlayTransformation { + /** + * Specifies the transparency level of the text overlay. Accepts integers from `1` + * to `9`. + */ + alpha?: number; + + /** + * Specifies the background color of the text overlay. Accepts an RGB hex code, an + * RGBA code, or a color name. + */ + background?: string; + + /** + * Flip/mirror the text horizontally, vertically, or in both directions. Acceptable + * values: `h` (horizontal), `v` (vertical), `h_v` (horizontal and vertical), or + * `v_h`. + */ + flip?: 'h' | 'v' | 'h_v' | 'v_h'; + + /** + * Specifies the font color of the overlaid text. Accepts an RGB hex code (e.g., + * `FF0000`), an RGBA code (e.g., `FFAABB50`), or a color name. + */ + fontColor?: string; + + /** + * Specifies the font family of the overlaid text. Choose from the supported fonts + * list or use a custom font. See + * [Supported fonts](https://imagekit.io/docs/add-overlays-on-images#supported-text-font-list) + * and + * [Custom font](https://imagekit.io/docs/add-overlays-on-images#change-font-family-in-text-overlay). + */ + fontFamily?: string; + + /** + * Specifies the font size of the overlaid text. Accepts a numeric value or an + * arithmetic expression. + */ + fontSize?: number | string; + + /** + * Specifies the inner alignment of the text when width is more than the text + * length. + */ + innerAlignment?: 'left' | 'right' | 'center'; + + /** + * Specifies the line height for multi-line text overlays. It will come into effect + * only if the text wraps over multiple lines. Accepts either an integer value or + * an arithmetic expression. + */ + lineHeight?: number | string; + + /** + * Specifies the padding around the overlaid text. Can be provided as a single + * positive integer or multiple values separated by underscores (following CSS + * shorthand order). Arithmetic expressions are also accepted. + */ + padding?: number | string; + + /** + * Specifies the corner radius: + * + * - Single value (positive integer): Applied to all corners (e.g., `20`). + * - `max`: Creates a circular or oval shape. + * - Per-corner array: Provide four underscore-separated values representing + * top-left, top-right, bottom-right, and bottom-left corners respectively (e.g., + * `10_20_30_40`). See + * [Radius](https://imagekit.io/docs/effects-and-enhancements#radius---r). + */ + radius?: number | 'max' | string; + + /** + * Specifies the rotation angle of the text overlay. Accepts a numeric value for + * clockwise rotation or a string prefixed with "N" for counter-clockwise rotation. + */ + rotation?: number | string; + + /** + * Specifies the typography style of the text. Supported values: + * + * - Single styles: `b` (bold), `i` (italic), `strikethrough`. + * - Combinations: Any combination separated by underscores, e.g., `b_i`, + * `b_i_strikethrough`. + */ + typography?: string; + + /** + * Specifies the maximum width (in pixels) of the overlaid text. The text wraps + * automatically, and arithmetic expressions (e.g., `bw_mul_0.2` or `bh_div_2`) are + * supported. Useful when used in conjunction with the `background`. Learn about + * [Arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations). + */ + width?: number | string; +} + +/** + * The SDK provides easy-to-use names for transformations. These names are + * converted to the corresponding transformation string before being added to the + * URL. SDKs are updated regularly to support new transformations. If you want to + * use a transformation that is not supported by the SDK, You can use the `raw` + * parameter to pass the transformation string directly. See the + * [Transformations documentation](https://imagekit.io/docs/transformations). + */ +export interface Transformation { + /** + * Uses AI to change the background. Provide a text prompt or a base64-encoded + * prompt, e.g., `prompt-snow road` or `prompte-[urlencoded_base64_encoded_text]`. + * Not supported inside overlay. See + * [AI Change Background](https://imagekit.io/docs/ai-transformations#change-background-e-changebg). + */ + aiChangeBackground?: string; + + /** + * Adds an AI-based drop shadow around a foreground object on a transparent or + * removed background. Optionally, control the direction, elevation, and saturation + * of the light source (e.g., `az-45` to change light direction). Pass `true` for + * the default drop shadow, or provide a string for a custom drop shadow. Supported + * inside overlay. See + * [AI Drop Shadow](https://imagekit.io/docs/ai-transformations#ai-drop-shadow-e-dropshadow). + */ + aiDropShadow?: true | string; + + /** + * Uses AI to edit images based on a text prompt. Provide a text prompt or a + * base64-encoded prompt, e.g., `prompt-snow road` or + * `prompte-[urlencoded_base64_encoded_text]`. Not supported inside overlay. + * See [AI Edit](https://imagekit.io/docs/ai-transformations#edit-image-e-edit). + */ + aiEdit?: string; + + /** + * Applies ImageKit's in-house background removal. Supported inside overlay. See + * [AI Background Removal](https://imagekit.io/docs/ai-transformations#imagekit-background-removal-e-bgremove). + */ + aiRemoveBackground?: true; + + /** + * Uses third-party background removal. Note: It is recommended to use + * aiRemoveBackground, ImageKit's in-house solution, which is more cost-effective. + * Supported inside overlay. See + * [External Background Removal](https://imagekit.io/docs/ai-transformations#background-removal-e-removedotbg). + */ + aiRemoveBackgroundExternal?: true; + + /** + * Performs AI-based retouching to improve faces or product shots. Not supported + * inside overlay. See + * [AI Retouch](https://imagekit.io/docs/ai-transformations#retouch-e-retouch). + */ + aiRetouch?: true; + + /** + * Upscales images beyond their original dimensions using AI. Not supported inside + * overlay. See + * [AI Upscale](https://imagekit.io/docs/ai-transformations#upscale-e-upscale). + */ + aiUpscale?: true; + + /** + * Generates a variation of an image using AI. This produces a new image with + * slight variations from the original, such as changes in color, texture, and + * other visual elements, while preserving the structure and essence of the + * original image. Not supported inside overlay. See + * [AI Generate Variations](https://imagekit.io/docs/ai-transformations#generate-variations-of-an-image-e-genvar). + */ + aiVariation?: true; + + /** + * Specifies the aspect ratio for the output, e.g., "ar-4-3". Typically used with + * either width or height (but not both). For example: aspectRatio = `4:3`, `4_3`, + * or an expression like `iar_div_2`. See + * [Image resize and crop – Aspect ratio](https://imagekit.io/docs/image-resize-and-crop#aspect-ratio---ar). + */ + aspectRatio?: number | string; + + /** + * Specifies the audio codec, e.g., `aac`, `opus`, or `none`. See + * [Audio codec](https://imagekit.io/docs/video-optimization#audio-codec---ac). + */ + audioCodec?: 'aac' | 'opus' | 'none'; + + /** + * Specifies the background to be used in conjunction with certain cropping + * strategies when resizing an image. + * + * - A solid color: e.g., `red`, `F3F3F3`, `AAFF0010`. See + * [Solid color background](https://imagekit.io/docs/effects-and-enhancements#solid-color-background). + * - Dominant color: `dominant` extracts the dominant color from the image. See + * [Dominant color background](https://imagekit.io/docs/effects-and-enhancements#dominant-color-background). + * - Gradient: `gradient_dominant` or `gradient_dominant_2` creates a gradient + * using the dominant colors. Optionally specify palette size (2 or 4), e.g., + * `gradient_dominant_4`. See + * [Gradient background](https://imagekit.io/docs/effects-and-enhancements#gradient-background). + * - A blurred background: e.g., `blurred`, `blurred_25_N15`, etc. See + * [Blurred background](https://imagekit.io/docs/effects-and-enhancements#blurred-background). + * - Expand the image boundaries using generative fill: `genfill`. Not supported + * inside overlay. Optionally, control the background scene by passing a text + * prompt: `genfill[:-prompt-${text}]` or + * `genfill[:-prompte-${urlencoded_base64_encoded_text}]`. See + * [Generative fill background](https://imagekit.io/docs/ai-transformations#generative-fill-bg-genfill). + */ + background?: string; + + /** + * Specifies the Gaussian blur level. Accepts an integer value between 1 and 100, + * or an expression like `bl-10`. See + * [Blur](https://imagekit.io/docs/effects-and-enhancements#blur---bl). + */ + blur?: number; + + /** + * Adds a border to the output media. Accepts a string in the format + * `_` (e.g., `5_FFF000` for a 5px yellow border), or an + * expression like `ih_div_20_FF00FF`. See + * [Border](https://imagekit.io/docs/effects-and-enhancements#border---b). + */ + border?: string; + + /** + * Indicates whether the output image should retain the original color profile. See + * [Color profile](https://imagekit.io/docs/image-optimization#color-profile---cp). + */ + colorProfile?: boolean; + + /** + * Replaces colors in the image. Supports three formats: + * + * - `toColor` - Replace dominant color with the specified color. + * - `toColor_tolerance` - Replace dominant color with specified tolerance (0-100). + * - `toColor_tolerance_fromColor` - Replace a specific color with another within + * tolerance range. Colors can be hex codes (e.g., `FF0022`) or names (e.g., + * `red`, `blue`). See + * [Color replacement](https://imagekit.io/docs/effects-and-enhancements#color-replace---cr). + */ + colorReplace?: string; + + /** + * Automatically enhances the contrast of an image (contrast stretch). See + * [Contrast Stretch](https://imagekit.io/docs/effects-and-enhancements#contrast-stretch---e-contrast). + */ + contrastStretch?: true; + + /** + * Crop modes for image resizing. See + * [Crop modes & focus](https://imagekit.io/docs/image-resize-and-crop#crop-crop-modes--focus). + */ + crop?: 'force' | 'at_max' | 'at_max_enlarge' | 'at_least' | 'maintain_ratio'; + + /** + * Additional crop modes for image resizing. See + * [Crop modes & focus](https://imagekit.io/docs/image-resize-and-crop#crop-crop-modes--focus). + */ + cropMode?: 'pad_resize' | 'extract' | 'pad_extract'; + + /** + * Specifies a fallback image if the resource is not found, e.g., a URL or file + * path. See + * [Default image](https://imagekit.io/docs/image-transformation#default-image---di). + */ + defaultImage?: string; + + /** + * Distorts the shape of an image. Supports two modes: + * + * - Perspective distortion: `p-x1_y1_x2_y2_x3_y3_x4_y4` changes the position of + * the four corners starting clockwise from top-left. + * - Arc distortion: `a-degrees` curves the image upwards (positive values) or + * downwards (negative values). See + * [Distort effect](https://imagekit.io/docs/effects-and-enhancements#distort---e-distort). + */ + distort?: string; + + /** + * Accepts values between 0.1 and 5, or `auto` for automatic device pixel ratio + * (DPR) calculation. Also accepts arithmetic expressions. + * + * - Learn about + * [Arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations). + * - See [DPR](https://imagekit.io/docs/image-resize-and-crop#dpr---dpr). + */ + dpr?: number; + + /** + * Specifies the duration (in seconds) for trimming videos, e.g., `5` or `10.5`. + * Typically used with startOffset to indicate the length from the start offset. + * Arithmetic expressions are supported. See + * [Trim videos – Duration](https://imagekit.io/docs/trim-videos#duration---du). + */ + duration?: number | string; + + /** + * Specifies the end offset (in seconds) for trimming videos, e.g., `5` or `10.5`. + * Typically used with startOffset to define a time window. Arithmetic expressions + * are supported. See + * [Trim videos – End offset](https://imagekit.io/docs/trim-videos#end-offset---eo). + */ + endOffset?: number | string; + + /** + * Flips or mirrors an image either horizontally, vertically, or both. Acceptable + * values: `h` (horizontal), `v` (vertical), `h_v` (horizontal and vertical), or + * `v_h`. See [Flip](https://imagekit.io/docs/effects-and-enhancements#flip---fl). + */ + flip?: 'h' | 'v' | 'h_v' | 'v_h'; + + /** + * Refines padding and cropping behavior for pad resize, maintain ratio, and + * extract crop modes. Supports manual positions and coordinate-based focus. With + * AI-based cropping, you can automatically keep key subjects in frame—such as + * faces or detected objects (e.g., `fo-face`, `fo-person`, `fo-car`)— while + * resizing. + * + * - See [Focus](https://imagekit.io/docs/image-resize-and-crop#focus---fo). + * - [Object aware cropping](https://imagekit.io/docs/image-resize-and-crop#object-aware-cropping---fo-object-name) + */ + focus?: string; + + /** + * Specifies the output format for images or videos, e.g., `jpg`, `png`, `webp`, + * `mp4`, or `auto`. You can also pass `orig` for images to return the original + * format. ImageKit automatically delivers images and videos in the optimal format + * based on device support unless overridden by the dashboard settings or the + * format parameter. See + * [Image format](https://imagekit.io/docs/image-optimization#format---f) and + * [Video format](https://imagekit.io/docs/video-optimization#format---f). + */ + format?: 'auto' | 'webp' | 'jpg' | 'jpeg' | 'png' | 'gif' | 'svg' | 'mp4' | 'webm' | 'avif' | 'orig'; + + /** + * Creates a linear gradient with two colors. Pass `true` for a default gradient, + * or provide a string for a custom gradient. See + * [Gradient](https://imagekit.io/docs/effects-and-enhancements#gradient---e-gradient). + */ + gradient?: true | string; + + /** + * Enables a grayscale effect for images. See + * [Grayscale](https://imagekit.io/docs/effects-and-enhancements#grayscale---e-grayscale). + */ + grayscale?: true; + + /** + * Specifies the height of the output. If a value between 0 and 1 is provided, it + * is treated as a percentage (e.g., `0.5` represents 50% of the original height). + * You can also supply arithmetic expressions (e.g., `ih_mul_0.5`). Height + * transformation – + * [Images](https://imagekit.io/docs/image-resize-and-crop#height---h) · + * [Videos](https://imagekit.io/docs/video-resize-and-crop#height---h) + */ + height?: number | string; + + /** + * Specifies whether the output image (in JPEG or PNG) should be compressed + * losslessly. See + * [Lossless compression](https://imagekit.io/docs/image-optimization#lossless-webp-and-png---lo). + */ + lossless?: boolean; + + /** + * By default, ImageKit removes all metadata during automatic image compression. + * Set this to true to preserve metadata. See + * [Image metadata](https://imagekit.io/docs/image-optimization#image-metadata---md). + */ + metadata?: boolean; + + /** + * Named transformation reference. See + * [Named transformations](https://imagekit.io/docs/transformations#named-transformations). + */ + named?: string; + + /** + * Specifies the opacity level of the output image. See + * [Opacity](https://imagekit.io/docs/effects-and-enhancements#opacity---o). + */ + opacity?: number; + + /** + * If set to true, serves the original file without applying any transformations. + * See + * [Deliver original file as-is](https://imagekit.io/docs/core-delivery-features#deliver-original-file-as-is---orig-true). + */ + original?: boolean; + + /** + * Specifies an overlay to be applied on the parent image or video. ImageKit + * supports overlays including images, text, videos, subtitles, and solid colors. + * See + * [Overlay using layers](https://imagekit.io/docs/transformations#overlay-using-layers). + */ + overlay?: Overlay; + + /** + * Extracts a specific page or frame from multi-page or layered files (PDF, PSD, + * AI). For example, specify by number (e.g., `2`), a range (e.g., `3-4` for the + * 2nd and 3rd layers), or by name (e.g., `name-layer-4` for a PSD layer). See + * [Thumbnail extraction](https://imagekit.io/docs/vector-and-animated-images#get-thumbnail-from-psd-pdf-ai-eps-and-animated-files). + */ + page?: number | string; + + /** + * Specifies whether the output JPEG image should be rendered progressively. + * Progressive loading begins with a low-quality, pixelated version of the full + * image, which gradually improves to provide a faster perceived load time. See + * [Progressive images](https://imagekit.io/docs/image-optimization#progressive-image---pr). + */ + progressive?: boolean; + + /** + * Specifies the quality of the output image for lossy formats such as JPEG, WebP, + * and AVIF. A higher quality value results in a larger file size with better + * quality, while a lower value produces a smaller file size with reduced quality. + * See [Quality](https://imagekit.io/docs/image-optimization#quality---q). + */ + quality?: number; + + /** + * Specifies the corner radius for rounded corners. + * + * - Single value (positive integer): Applied to all corners (e.g., `20`). + * - `max`: Creates a circular or oval shape. + * - Per-corner array: Provide four underscore-separated values representing + * top-left, top-right, bottom-right, and bottom-left corners respectively (e.g., + * `10_20_30_40`). See + * [Radius](https://imagekit.io/docs/effects-and-enhancements#radius---r). + */ + radius?: number | 'max' | string; + + /** + * Pass any transformation not directly supported by the SDK. This transformation + * string is appended to the URL as provided. + */ + raw?: string; + + /** + * Specifies the rotation angle in degrees. Positive values rotate the image + * clockwise; you can also use, for example, `N40` for counterclockwise rotation or + * `auto` to use the orientation specified in the image's EXIF data. For videos, + * only the following values are supported: 0, 90, 180, 270, or 360. See + * [Rotate](https://imagekit.io/docs/effects-and-enhancements#rotate---rt). + */ + rotation?: number | string; + + /** + * Adds a shadow beneath solid objects in an image with a transparent background. + * For AI-based drop shadows, refer to aiDropShadow. Pass `true` for a default + * shadow, or provide a string for a custom shadow. See + * [Shadow](https://imagekit.io/docs/effects-and-enhancements#shadow---e-shadow). + */ + shadow?: true | string; + + /** + * Sharpens the input image, highlighting edges and finer details. Pass `true` for + * default sharpening, or provide a numeric value for custom sharpening. See + * [Sharpen](https://imagekit.io/docs/effects-and-enhancements#sharpen---e-sharpen). + */ + sharpen?: true | number; + + /** + * Specifies the start offset (in seconds) for trimming videos, e.g., `5` or + * `10.5`. Arithmetic expressions are also supported. See + * [Trim videos – Start offset](https://imagekit.io/docs/trim-videos#start-offset---so). + */ + startOffset?: number | string; + + /** + * An array of resolutions for adaptive bitrate streaming, e.g., [`240`, `360`, + * `480`, `720`, `1080`]. See + * [Adaptive Bitrate Streaming](https://imagekit.io/docs/adaptive-bitrate-streaming). + */ + streamingResolutions?: Array; + + /** + * Useful for images with a solid or nearly solid background and a central object. + * This parameter trims the background, leaving only the central object in the + * output image. See + * [Trim edges](https://imagekit.io/docs/effects-and-enhancements#trim-edges---t). + */ + trim?: true | number; + + /** + * Applies Unsharp Masking (USM), an image sharpening technique. Pass `true` for a + * default unsharp mask, or provide a string for a custom unsharp mask. See + * [Unsharp Mask](https://imagekit.io/docs/effects-and-enhancements#unsharp-mask---e-usm). + */ + unsharpMask?: true | string; + + /** + * Specifies the video codec, e.g., `h264`, `vp9`, `av1`, or `none`. See + * [Video codec](https://imagekit.io/docs/video-optimization#video-codec---vc). + */ + videoCodec?: 'h264' | 'vp9' | 'av1' | 'none'; + + /** + * Specifies the width of the output. If a value between 0 and 1 is provided, it is + * treated as a percentage (e.g., `0.4` represents 40% of the original width). You + * can also supply arithmetic expressions (e.g., `iw_div_2`). Width transformation + * – [Images](https://imagekit.io/docs/image-resize-and-crop#width---w) · + * [Videos](https://imagekit.io/docs/video-resize-and-crop#width---w) + */ + width?: number | string; + + /** + * Focus using cropped image coordinates - X coordinate. See + * [Focus using cropped coordinates](https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates). + */ + x?: number | string; + + /** + * Focus using cropped image coordinates - X center coordinate. See + * [Focus using cropped coordinates](https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates). + */ + xCenter?: number | string; + + /** + * Focus using cropped image coordinates - Y coordinate. See + * [Focus using cropped coordinates](https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates). + */ + y?: number | string; + + /** + * Focus using cropped image coordinates - Y center coordinate. See + * [Focus using cropped coordinates](https://imagekit.io/docs/image-resize-and-crop#example---focus-using-cropped-image-coordinates). + */ + yCenter?: number | string; + + /** + * Accepts a numeric value that determines how much to zoom in or out of the + * cropped area. It should be used in conjunction with fo-face or fo-. + * See [Zoom](https://imagekit.io/docs/image-resize-and-crop#zoom---z). + */ + zoom?: number; +} + +/** + * By default, the transformation string is added as a query parameter in the URL, + * e.g., `?tr=w-100,h-100`. If you want to add the transformation string in the + * path of the URL, set this to `path`. Learn more in the + * [Transformations guide](https://imagekit.io/docs/transformations). + */ +export type TransformationPosition = 'path' | 'query'; + +export interface VideoOverlay extends BaseOverlay { + /** + * Specifies the relative path to the video used as an overlay. + */ + input: string; + + type: 'video'; + + /** + * The input path can be included in the layer as either `i-{input}` or + * `ie-{base64_encoded_input}`. By default, the SDK determines the appropriate + * format automatically. To always use base64 encoding (`ie-{base64}`), set this + * parameter to `base64`. To always use plain text (`i-{input}`), set it to + * `plain`. + * + * Regardless of the encoding method: + * + * - Leading and trailing slashes are removed. + * - Remaining slashes within the path are replaced with `@@` when using plain + * text. + */ + encoding?: 'auto' | 'plain' | 'base64'; + + /** + * Array of transformation to be applied to the overlay video. Except + * `streamingResolutions`, all other video transformations are supported. See + * [Video transformations](https://imagekit.io/docs/video-transformation). + */ + transformation?: Array; +} diff --git a/src/responsive.ts b/src/responsive.ts index 3b3c120..73286ba 100644 --- a/src/responsive.ts +++ b/src/responsive.ts @@ -1,67 +1,10 @@ -import type { SrcOptions } from './interfaces' +import type { ResponsiveImageAttributes, GetImageAttributesOptions } from './interfaces' import { buildSrc } from './url' /* Default break‑point pools */ const DEFAULT_DEVICE_BREAKPOINTS = [640, 750, 828, 1080, 1200, 1920, 2048, 3840] as const const DEFAULT_IMAGE_BREAKPOINTS = [16, 32, 48, 64, 96, 128, 256, 384] as const -export interface GetImageAttributesOptions extends SrcOptions { - /** - * The intended display width of the image in pixels, - * used **only when the `sizes` attribute is not provided**. - * - * Triggers a DPR-based strategy (1x and 2x variants) and generates `x` descriptors in `srcSet`. - * - * Ignored if `sizes` is present. - */ - width?: number - - /** - * The value for the HTML `sizes` attribute - * (e.g., `"100vw"` or `"(min-width:768px) 50vw, 100vw"`). - * - * - If it includes one or more `vw` units, breakpoints smaller than the corresponding percentage of the smallest device width are excluded. - * - If it contains no `vw` units, the full breakpoint list is used. - * - * Enables a width-based strategy and generates `w` descriptors in `srcSet`. - */ - sizes?: string - - /** - * Custom list of **device-width breakpoints** in pixels. - * These define common screen widths for responsive image generation. - * - * Defaults to `[640, 750, 828, 1080, 1200, 1920, 2048, 3840]`. - * Sorted automatically. - */ - deviceBreakpoints?: number[] - - /** - * Custom list of **image-specific breakpoints** in pixels. - * Useful for generating small variants (e.g., placeholders or thumbnails). - * - * Merged with `deviceBreakpoints` before calculating `srcSet`. - * Defaults to `[16, 32, 48, 64, 96, 128, 256, 384]`. - * Sorted automatically. - */ - imageBreakpoints?: number[] -} - -/** - * Resulting set of attributes suitable for an HTML `` element. - * Useful for enabling responsive image loading. - */ -export interface ResponsiveImageAttributes { - /** URL for the *largest* candidate (assigned to plain `src`). */ - src: string - /** Candidate set with `w` or `x` descriptors. */ - srcSet?: string - /** `sizes` returned (or synthesised as `100vw`). */ - sizes?: string - /** Width as a number (if `width` was provided). */ - width?: number -} - /** * Generates a responsive image URL, `srcSet`, and `sizes` attributes * based on the input options such as `width`, `sizes`, and breakpoints. diff --git a/src/url.ts b/src/url.ts index 62a12c2..7de8031 100644 --- a/src/url.ts +++ b/src/url.ts @@ -1,5 +1,4 @@ -import type { SrcOptions } from "./interfaces"; -import type { ImageOverlay, SolidColorOverlay, SubtitleOverlay, TextOverlay, Transformation, VideoOverlay } from "./interfaces/Transformation"; +import type { SrcOptions, ImageOverlay, SolidColorOverlay, SubtitleOverlay, TextOverlay, Transformation, VideoOverlay } from "./interfaces"; import transformationUtils, { safeBtoa } from "./utils/transformation"; const TRANSFORMATION_PARAMETER = "tr"; const SIMPLE_OVERLAY_PATH_REGEX = new RegExp('^[a-zA-Z0-9-._/ ]*$') From a6a9a9353401bf490fadce314b77be0e07b2d7c9 Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Fri, 16 Jan 2026 16:44:52 +0530 Subject: [PATCH 3/4] refactor: remove unused type import from responsive module in index.ts --- src/index.ts | 1 - 1 file changed, 1 deletion(-) diff --git a/src/index.ts b/src/index.ts index dbbfb11..9ccff9e 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,5 +1,4 @@ import type { GetImageAttributesOptions, ResponsiveImageAttributes, SrcOptions, Transformation, UploadOptions, UploadResponse } from "./interfaces"; -import type { } from "./responsive"; import { getResponsiveImageAttributes } from "./responsive"; import { ImageKitAbortError, ImageKitInvalidRequestError, ImageKitServerError, ImageKitUploadNetworkError, upload } from "./upload"; import { buildSrc, buildTransformationString } from "./url"; From d6b72494e1c237a1bd7281072e89bc67de730437 Mon Sep 17 00:00:00 2001 From: Manu Chaudhary Date: Fri, 16 Jan 2026 16:58:32 +0530 Subject: [PATCH 4/4] chore: update version to 5.2.0 and enhance changelog and README documentation --- CHANGELOG.md | 18 ++++++++++++++++++ README.md | 17 ++++++++++++++--- package-lock.json | 4 ++-- package.json | 2 +- 4 files changed, 35 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b184c0f..bdf3053 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,23 @@ # Changelog +## Version 5.2.0 + +1. **New transformation parameters added:** + - `layerMode` (`lm`): Control layer blending modes in overlay transformations + - `aiEdit` (`e-edit`): AI-powered image editing transformation + - `colorReplace` (`cr`): Replace specific colors in images + - `distort` (`e-distort`): Apply distortion effects to images + +2. **Type definitions updated:** + - Improved TypeScript types by synchronizing with the official Node.js SDK + - Enhanced type safety for transformation options, upload options, and responses + +3. **Documentation improvements:** + - Added TypeScript versioning policy section to README + - Clarified how type definition improvements may be released in minor/patch versions + +_No runtime breaking changes from 5.1.x._ + ## Version 5.1.0 1. **New helper** `getResponsiveImageAttributes()` diff --git a/README.md b/README.md index 2e5c86e..213d7d4 100644 --- a/README.md +++ b/README.md @@ -20,16 +20,27 @@ You can install the SDK in your project using npm or yarn. npm install @imagekit/javascript ``` +## Documentation + +Refer to the ImageKit [official documentation](https://imagekit.io/docs/integration/javascript) for more details on how to use the SDK. + ## TypeScript support The SDK is written in TypeScript, offering first-class TypeScript support. Enjoy excellent type safety and IntelliSense in your IDE. You can use it in your TypeScript projects without any additional configuration. - To enable type checking in JavaScript projects, add `//@ts-check` at the top of your JavaScript files. This will activate type checking in your IDE. -## Documentation +### TypeScript and the SDK versioning policy -Refer to the ImageKit [official documentation](https://imagekit.io/docs/integration/javascript) for more details on how to use the SDK. +The TypeScript types in this SDK always reflect the latest shape of the ImageKit API. When we make improvements to the type definitions to better reflect the actual runtime behavior, we may release these changes in minor or patch versions. While these changes align types more closely with reality and are not breaking changes at runtime, they might cause new type errors when you upgrade. + +We judge this approach to be better than the alternatives: outdated, inaccurate types, or vastly more frequent major releases that would distract from any truly breaking runtime changes. If you encounter type errors after upgrading, you can resolve them by: + +- Adding appropriate type guards or assertions +- Updating your code to match the corrected types +- Using `// @ts-ignore` temporarily if you need more time to adjust + +Please feel welcome to share your thoughts about the versioning policy in a GitHub issue. ## Changelog diff --git a/package-lock.json b/package-lock.json index ffaffc7..c172246 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@imagekit/javascript", - "version": "5.1.0", + "version": "5.2.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@imagekit/javascript", - "version": "5.1.0", + "version": "5.2.0", "license": "MIT", "devDependencies": { "@babel/cli": "^7.10.5", diff --git a/package.json b/package.json index 986fa4f..87dc486 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@imagekit/javascript", - "version": "5.1.0", + "version": "5.2.0", "description": "ImageKit Javascript SDK", "main": "dist/imagekit.cjs.js", "module": "dist/imagekit.esm.js",