Interface RequestInitCfPropertiesImage
anim?: boolean;
background?: string;
blur?: number;
border?:
| { color: string; width: number }
| {
bottom: number;
color: string;
left: number;
right: number;
top: number;
};
brightness?: number;
compression?: "fast";
contrast?: number;
dpr?: number;
draw?: RequestInitCfPropertiesImageDraw[];
fit?: "cover"
| "scale-down"
| "contain"
| "crop"
| "pad"
| "squeeze";
flip?: "h" | "v" | "hv";
format?:
| "svg"
| "json"
| "png"
| "jpeg"
| "webp"
| "avif"
| "baseline-jpeg"
| "png-force";
gamma?: number;
gravity?: | "auto"
| "center"
| "bottom"
| "top"
| "face"
| "left"
| "right"
| "entropy"
| BasicImageTransformationsGravityCoordinates;
height?: number;
metadata?: "none"
| "keep"
| "copyright";
"origin-auth"?: "share-publicly";
quality?: number | "low" | "high" | "medium-low" | "medium-high";
rotate?: 0 | 180 | 90 | 270 | 360;
saturation?: number;
segment?: "foreground";
sharpen?: number;
trim?:
| "border"
| {
border?: | boolean
| { color?: string; keep?: number; tolerance?: number };
bottom?: number;
height?: number;
left?: number;
right?: number;
top?: number;
width?: number;
};
width?: number;
}
Hierarchy (View Summary)
- BasicImageTransformations
- RequestInitCfPropertiesImage
Properties
Optionalanim
Optionalbackground
Background color to add underneath the image. Applies only to images with transparency (such as PNG). Accepts any CSS color (#RRGGBB, rgba(…), hsl(…), etc.)
Optionalblur
Radius of a blur filter (approximate gaussian). Maximum supported radius is 250.
Optionalborder
| { color: string; width: number }
| {
bottom: number;
color: string;
left: number;
right: number;
top: number;
}
Adds a border around the image. The border is added after resizing. Border width takes dpr into account, and can be specified either using a single width property, or individually for each side.
Optionalbrightness
Increase brightness by a factor. A value of 1.0 equals no change, a value of 0.5 equals half brightness, and a value of 2.0 equals twice as bright. 0 is ignored.
Optionalcompression
Slightly reduces latency on a cache miss by selecting a quickest-to-compress file format, at a cost of increased file size and lower image quality. It will usually override the format option and choose JPEG over WebP or AVIF. We do not recommend using this option, except in unusual circumstances like resizing uncacheable dynamically-generated images.
Optionalcontrast
Increase contrast by a factor. A value of 1.0 equals no change, a value of 0.5 equals low contrast, and a value of 2.0 equals high contrast. 0 is ignored.
Optionaldpr
Device Pixel Ratio. Default 1. Multiplier for width/height that makes it
easier to specify higher-DPI sizes in .
Optionaldraw
Overlays are drawn in the order they appear in the array (last array entry is the topmost layer).
Optionalfit
Resizing mode as a string. It affects interpretation of width and height options:
- scale-down: Similar to contain, but the image is never enlarged. If the image is larger than given width or height, it will be resized. Otherwise its original size will be kept.
- contain: Resizes to maximum size that fits within the given width and height. If only a single dimension is given (e.g. only width), the image will be shrunk or enlarged to exactly match that dimension. Aspect ratio is always preserved.
- cover: Resizes (shrinks or enlarges) to fill the entire area of width and height. If the image has an aspect ratio different from the ratio of width and height, it will be cropped to fit.
- crop: The image will be shrunk and cropped to fit within the area specified by width and height. The image will not be enlarged. For images smaller than the given dimensions it's the same as scale-down. For images larger than the given dimensions, it's the same as cover. See also trim.
- pad: Resizes to the maximum size that fits within the given width and height, and then fills the remaining area with a background color (white by default). Use of this mode is not recommended, as the same effect can be more efficiently achieved with the contain mode and the CSS object-fit: contain property.
- squeeze: Stretches and deforms to the width and height given, even if it breaks aspect ratio
Optionalflip
Flips the images horizontally, vertically, or both. Flipping is applied before rotation, so if you apply flip=h,rotate=90 then the image will be flipped horizontally, then rotated by 90 degrees.
Optionalformat
| "svg"
| "json"
| "png"
| "jpeg"
| "webp"
| "avif"
| "baseline-jpeg"
| "png-force"
Output format to generate. It can be:
- avif: generate images in AVIF format.
- webp: generate images in Google WebP format. Set quality to 100 to get the WebP-lossless format.
- json: instead of generating an image, outputs information about the image, in JSON format. The JSON object will contain image size (before and after resizing), source image’s MIME type, file size, etc.
- jpeg: generate images in JPEG format.
- png: generate images in PNG format.
Optionalgamma
Increase exposure by a factor. A value of 1.0 equals no change, a value of 0.5 darkens the image, and a value of 2.0 lightens the image. 0 is ignored.
Optionalgravity
| "auto"
| "center"
| "bottom"
| "top"
| "face"
| "left"
| "right"
| "entropy"
| BasicImageTransformationsGravityCoordinates
When cropping with fit: "cover", this defines the side or point that should be left uncropped. The value is either a string "left", "right", "top", "bottom", "auto", or "center" (the default), or an object {x, y} containing focal point coordinates in the original image expressed as fractions ranging from 0.0 (top or left) to 1.0 (bottom or right), 0.5 being the center. {fit: "cover", gravity: "top"} will crop bottom or left and right sides as necessary, but won’t crop anything from the top. {fit: "cover", gravity: {x:0.5, y:0.2}} will crop each side to preserve as much as possible around a point at 20% of the height of the source image.
Optionalheight
Maximum height in image pixels. The value must be an integer.
Optionalmetadata
What EXIF data should be preserved in the output image. Note that EXIF rotation and embedded color profiles are always applied ("baked in" into the image), and aren't affected by this option. Note that if the Polish feature is enabled, all metadata may have been removed already and this option may have no effect.
- keep: Preserve most of EXIF metadata, including GPS location if there's any.
- copyright: Only keep the copyright tag, and discard everything else. This is the default behavior for JPEG files.
- none: Discard all invisible EXIF metadata. Currently WebP and PNG output formats always discard metadata.
Optionalorigin-
Fetching image from authenticated origin. Setting this property will pass authentication headers (Authorization, Cookie, etc.) through to the origin.
Optionalquality
Quality setting from 1-100 (useful values are in 60-90 range). Lower values make images look worse, but load faster. The default is 85. It applies only to JPEG and WebP images. It doesn’t have any effect on PNG.
Optionalrotate
Number of degrees (90, 180, 270) to rotate the image by. width and height options refer to axes after rotation.
Optionalsaturation
Increase contrast by a factor. A value of 1.0 equals no change, a value of 0.5 equals low contrast, and a value of 2.0 equals high contrast. 0 is ignored.
Optionalsegment
Image segmentation using artificial intelligence models. Sets pixels not within selected segment area to transparent e.g "foreground" sets every background pixel as transparent.
Optionalsharpen
Strength of sharpening filter to apply to the image. Floating-point number between 0 (no sharpening, default) and 10 (maximum). 1.0 is a recommended value for downscaled images.
Optionaltrim
| "border"
| {
border?: | boolean
| { color?: string; keep?: number; tolerance?: number };
bottom?: number;
height?: number;
left?: number;
right?: number;
top?: number;
width?: number;
}
Allows you to trim your image. Takes dpr into account and is performed before resizing or rotation.
It can be used as:
- left, top, right, bottom - it will specify the number of pixels to cut off each side
- width, height - the width/height you'd like to end up with - can be used in combination with the properties above
- border - this will automatically trim the surroundings of an image based on
it's color. It consists of three properties:
- color: rgb or hex representation of the color you wish to trim (todo: verify the rgba bit)
- tolerance: difference from color to treat as color
- keep: the number of pixels of border to keep
Optionalwidth
Maximum width in image pixels. The value must be an integer.
Whether to preserve animation frames from input files. Default is true. Setting it to false reduces animations to still images. This setting is recommended when enlarging images or processing arbitrary user content, because large GIF animations can weigh tens or even hundreds of megabytes. It is also useful to set anim:false when using format:"json" to get the response quicker without the number of frames.