Skip to main content

Image Transformations

Use transformations to resize, crop, convert, or adjust an image. Supply the parameters below when you:

  • Request an on-demand variant through the Fetch Asset API
  • Define a variant profile
  • Preprocess an upload
  • Configure eager variant generation

Use the same parameter names in request URLs, variant profiles, and upload preprocessing configuration. For older configurations and URLs, see Migrating from abbreviated parameters.

Parameter Reference​

ParameterNameDescriptionAllowed InputDefault
heightHeightThe target height of the imageInteger > 0null (Preserves aspect ratio)
widthWidthThe target width of the imageInteger > 0null (Preserves aspect ratio)
fitFit ModeControls how the image fits into the bounding box defined by height and widthfit, fill, stretch, cropfit
gravityGravityWhen cropping occurs, determines which part of the image is retainedcenter, entropy, attentioncenter
formatFormatThe output format of the imageFormatOriginal format
rotateRotateRotates the image clockwise. auto uses EXIF data0, 90, 180, 270, auto0
flipFlipFlips the image along an axisv (vertical), h (horizontal), nonenone
filterFilterApplies a visual effectnone, black_white, grayscale, sepianone
blurBlurApplies a Gaussian blur (value is sigma)0 - 1500
qualityQualityCompression level for lossy formats1 - 100Format dependent (e.g., 80)
padPaddingAdds padding pixels to the image boundariesInteger > 00
pad-colorPad BackgroundThe padding background colorHex Code (e.g., #FF0000 or #FF0000FF)Transparent / White (Format dependent)
stripStrip MetadataComma-separated list of metadata fields to removeexif, iptc, xmp (e.g., exif,xmp)None
color-spaceColor SpaceTransforms the image color spaceorigin, grayscale, srgb, p3origin
pixel-channelsPixel ChannelsChannel selection and order for raw pixel outputAny permutation of RGB or RGBA, or gray (case-insensitive)RGB
pixel-layoutPixel LayoutSample arrangement for raw pixel outputinterleaved, planarinterleaved

Format​

FormatNameFile ExtensionContent Type
pngPNG.pngimage/png
jpgJPEG.jpegimage/jpeg
webpWEBP.webpimage/webp
avifAVIF.avifimage/avif
jxlJPEG XL.jxlimage/jxl
heicHEIC.heicimage/heic
gifGIF.gifimage/gif
pixelsRaw Pixels.binapplication/octet-stream

pixels supports output only. Upload an encoded image and request a pixel variant, or convert the upload to pixels through preprocessing. See Raw Pixels.

Image Resizing​

The height, width, and fit parameters determine the output dimensions and whether Konifer scales, crops, or distorts the source image.

The resizing examples use this 1365×1024-pixel cow photo. Download it to try the same transformations with your own Konifer instance. The examples on this page are saved outputs from the Konifer API.

Cow in a mountain pasture with autumn trees behind it

Source · 1365×1024 pixels. Download the cow photo

fit (Default)​

Requirements: height or width (or both).

Konifer scales the image to fit within the requested dimensions while preserving its aspect ratio.

  • With only width, Konifer calculates the height from the source aspect ratio.
  • With only height, Konifer calculates the width from the source aspect ratio.
  • With both, the output fits inside the requested bounding box. Neither dimension exceeds its requested value, and no cropping occurs.

fill​

Requirements: Both height and width are required.

Konifer scales the image until it covers the requested dimensions, preserving its aspect ratio, then crops any overflow. The output matches the requested width and height.

Use gravity to choose which part of the scaled image remains. The default, center, removes an equal amount from opposite sides when possible.

stretch​

Requirements: Both height and width are required.

Konifer scales the image to the requested width and height without preserving its aspect ratio.

warning

The output may appear squashed or stretched when the requested aspect ratio differs from the source.

crop​

Requirements: Both height and width are required.

Konifer removes pixels from the source to produce the requested width and height. Unlike fill, crop does not scale the image before cropping. Use gravity to choose which part of the source remains.

All four requests below use width=320&height=320&format=webp. Compare how much of the pasture remains and whether the cow keeps its proportions. The outlined frames mark the same 320×320 target box; the empty space around the fit result belongs to this page, not the returned image. Select a caption to inspect the output at its native size.

Whole cow photo scaled to fit a square target
fit=fit · 320×240 pixels · Whole scene
Cow photo scaled and cropped to fill a square

fit=fill · 320×320 pixels · Scaled, then cropped

Whole cow photo stretched vertically into a square

fit=stretch · 320×320 pixels · Changed proportions

Close crop of the cow's horns and autumn trees

fit=crop · 320×320 pixels · Cropped at source scale

For example, after uploading the photo at /documentation/cow, request the filled square with:

GET /assets/documentation/cow/-/content?format=webp&width=320&height=320&fit=fill

Gravity Options (gravity)​

Both fill and crop support these gravity values:

  • center (default): Keeps the geometric center of the image.
  • entropy: Keeps the area with the most detail, measured through contrast and edges. It often works well for landscapes, products, and textured objects.
  • attention: Keeps the area that the saliency model identifies as visually important, including faces and human features. It often works well for profile pictures and social content.

These portrait crops use the same bird photo and width=240&height=320&fit=fill&format=webp. Only gravity changes:

Centered portrait crop showing the whole bird
gravity=center · Geometric center
Entropy crop with branches and part of the bird's head outside the right edge
gravity=entropy · Detailed region
Attention crop retaining the bird and its head

gravity=attention · Salient region

The entropy crop clips the bird's head in this example. Automatic gravity uses visual heuristics; it does not guarantee that a whole subject remains in frame. Compare results with representative uploads before choosing a default.

Image Formats & Quality​

Konifer can return variants in these formats:

  • JPEG
  • PNG
  • WEBP (single and multi-page)
  • AVIF
  • JPEG XL
  • HEIC
  • GIF (single and multi-page)

For raw image buffers, Konifer also supports Pixels (format=pixels).

Quality (quality)​

The quality parameter controls compression for lossy formats. Lower values reduce file size and discard more image detail. Higher values preserve more detail and require more storage and network bandwidth.

FormatDefault QualityNotes
JPEG80Good balance for photos.
WEBP80Generally 30% smaller than JPEG at equivalent quality.
AVIF50Superior compression, but computationally expensive to encode.
PNGN/APNG is lossless. The quality parameter is ignored.
JPEG XL90High-efficiency modern standard.
HEIC50Standard for iOS captures.
GIF100Images are generally small due to a limited color palette.
PixelsN/ARaw samples have no compression; Konifer ignores quality.

Defaults are based on the Sharp library recommendations.

tip

Higher quality settings can increase encoding time. AVIF encoding is especially sensitive to this setting.

Both versions of this cheetah photo use width=640&format=webp. Compare the fur around the eyes: quality=10 loses fine detail in exchange for a smaller file. Open each output at its native 640×427 size to inspect the difference. These file sizes apply to this photo and these settings.

Cheetah with smoothed fur detail from low quality compression
quality=10 · 11,888 bytes
Cheetah with fine fur detail preserved at quality 80
quality=80 · 49,434 bytes

Raw Pixel Output​

format=pixels returns packed, row-major, unsigned 8-bit samples (uint8, 0–255), without an image header or metadata. The response has content type application/octet-stream and the download extension .bin. Animated sources produce the first frame. Apply resizing, rotation, filters, and padding before exporting the buffer.

Pixel Channels (pixel-channels)​

Specify any permutation of RGB or RGBA, or gray. Input is case-insensitive; Konifer reports channels in lowercase in response attributes. Color channels must contain R, G, and B once each, with an optional single A. Examples include RGB (default), BGR, RGBA, BGRA, and ARGB. Invalid values, such as RRB or RG, return 400 Bad Request.

Color channels require an output color space of srgb or p3. Use color-space=srgb or color-space=p3 if the original color space is unsuitable. With color-space=origin, a grayscale, CMYK, or other unsupported source color space returns 400 Bad Request.

An A channel preserves source alpha or contains 255 if the source has no alpha. Color output without A drops alpha. gray returns one grayscale channel and composites transparency against white. For gray, omit color-space or use color-space=origin or color-space=grayscale; an explicit color-space=srgb or color-space=p3 returns 400 Bad Request.

Pixel Layout (pixel-layout)​

ValueArrangement for RGBDefault
interleavedAll channels per pixel: R1 G1 B1 R2 G2 B2 …Yes
planarA complete plane per channel: R1 R2 … G1 G2 … B1 B2 …No

Both layouts follow row order within the image. Channel and plane order follow pixel-channels. For gray, Konifer normalizes the layout to interleaved, including requests for planar.

Pixel options apply when the resolved output format is pixels. They do not select that format on their own and have no effect on encoded output such as PNG. Select pixels through format=pixels or a profile that defines it; Accept: application/octet-stream does not select pixel output.

Read the output dimensions and pixel attributes (channels, layout, dataType) from the content response's K-Attr-* headers, or from attributes in the client's fetchContent() result. link also returns these attributes in JSON. The byte count is width × height × channel count. The current output data type is fixed at uint8; there is no data-type transformation parameter.

Use these same parameter names in variant profiles and preprocessing configuration. See Raw Pixels for configuration and Fetching raw pixels for HTTP and client examples.

Color Space​

The color-space parameter controls the output color space and its available color gamut.

  • origin (default): Retains the embedded ICC profile, when present, without converting the color space.
  • grayscale: Converts the image to a single-channel (or 2-channel if alpha exists) grayscale image. This is more space-efficient than the grayscale filter; however, color-adding transformations (such as pad-color) will also be flattened to grayscale.
  • srgb: Converts the image to sRGB using its embedded ICC profile. Konifer removes the profile from the output because most displays assume sRGB by default.
  • p3: Converts the image to the Display P3 profile, the standard for modern iOS-based cameras and wide-gamut displays.
note

Converting an sRGB or grayscale source to P3 does not create colors absent from the source. The conversion may increase file size without changing its appearance.

Geometry & Effects​

Rotate (rotate)​

Use rotate to rotate the image clockwise in 90-degree increments.

These small outputs use the same bird photo with width=160&height=160&format=webp. Each image fits inside the same square frame. Follow the bird and its branch as the photo turns clockwise; 90° and 270° produce portrait images.

Upright bird on a branch, with no rotation
rotate=0 · Original
Bird photo turned a quarter turn clockwise, with the bird's head pointing right
rotate=90 · 90° clockwise
Bird photo turned upside down by a half turn
rotate=180 · Half turn
Bird photo turned three quarters clockwise, with the bird's head pointing left
rotate=270 · 270° clockwise

If auto is supplied, Konifer reads the EXIF Orientation metadata from the original variant and rotates the image accordingly. The resulting transformed variant has the EXIF Orientation tag stripped to prevent double-rotation by displays.

Flip (flip)​

Use flip to mirror the image along an axis:

  • v: Vertical flip (top-to-bottom).
  • h: Horizontal flip (left-to-right).

These examples use the same bird photo with width=240&format=webp. With flip=h, the bird faces the opposite direction. With flip=v, the top and bottom exchange places while the bird stays on the same side of the image.

Original upright bird facing right on a rising branch
flip=none · Original
Bird mirrored left to right, now facing left
flip=h · Left to right
Bird mirrored top to bottom, hanging upside down
flip=v · Top to bottom

Filter (filter)​

Use filter to apply one of these effects:

  • none (default): No filter applied.
  • black_white: Applies a binary threshold so each pixel becomes pure black or pure white.
  • grayscale: Removes color while preserving shades of gray.
  • sepia: Applies a warm, brownish tone matrix (identical to the CSS sepia(100%) filter).

Each example below uses the same flamingo photo with width=480&format=webp. Compare the solid black and white regions from black_white with the tonal detail retained by grayscale.

Pink flamingos standing in dark water, with no filter
filter=none · Original colors
Flamingos and water reduced to solid black and white regions

filter=black_white · Binary threshold

Flamingos and water rendered in shades of gray

filter=grayscale · Shades of gray

Flamingos and water rendered in warm brown tones
filter=sepia · Warm brown tones
note

The grayscale filter is different from the grayscale color space (color-space). Images with this filter applied will still be 3-channel (or 4-channel if the image contains alpha). Other transformations, such as padding, will still retain color.

For example: ?filter=grayscale&pad=10&pad-color=%23FF2900 produces a grayscale image with a red border. Encode # as %23 in a URL.

Blur (blur)​

Use blur to apply a Gaussian blur. Higher values soften more detail. Konifer applies blur after resizing, so compare values at the dimensions you plan to deliver.

Range: 0 (no blur) to 150 (heavy blur).

These outputs use the same squirrel photo with width=480&format=webp. Only blur changes:

Sharp squirrel on a branch without blur
blur=0 · No blur
Blurred squirrel with its body and branch still recognizable
blur=10 · Softened detail
Squirrel photo blurred into broad areas of green and brown
blur=50 · Broad color shapes

Borders & Padding​

Use pad to extend each edge of the image canvas by a number of pixels.

Amount (pad)​

Set the number of pixels added to each edge.

Padding Color (pad-color)​

Set the padded area's color with a CSS-style hex value in pad-color.

  • If pad-color is omitted: Padding is transparent for PNG, WebP, AVIF, JPEG XL, and HEIC. It is white for JPEG and GIF
  • Hex Format: Supports both RGB (Opaque) and RGBA (Transparent) formats.

Examples​

  • Solid Red: pad-color=%23FF0000 (URL encoded #FF0000)
  • Translucent Red (50% Opacity): pad-color=%23FF000080 (URL encoded #FF000080)

Both requests below resize the squirrel to 320×213 pixels, then add pad=16 on every edge. The final canvas measures 352×245 pixels. With WebP, omitting pad-color leaves the added area transparent; the checkerboard is this page's background.

Squirrel photo with transparent padding visible against a checkerboard
pad=16 · Transparent padding
Squirrel photo surrounded by an orange red border

pad=16&pad-color=%23FF2900 · Solid color

GET /assets/documentation/squirrel/-/content?format=webp&width=320&pad=16&pad-color=%23FF2900

Metadata​

Strip Metadata​

Use strip to remove EXIF, XMP, or IPTC metadata from the output.

tip

Add strip to a variant profile, eager variant, or preprocessing rule when every matching asset needs the same metadata policy. Stripping metadata during preprocessing removes it from the original variant and every variant derived from it.

Migrating from abbreviated parameters​

The current API uses descriptive transformation names. If you upgrade from a version that uses abbreviations, replace these keys in request URLs, variant-profiles, and transform.preprocessing:

Previous nameCurrent name
wwidth
hheight
qquality
ggravity
rrotate
fflip
cscolor-space
pad-cpad-color

This is a breaking change: use the current names to request transformations. Konifer does not support the previous names as aliases. Keep the parameter values, including flip=h and flip=v.

For example, change this request:

GET /assets/photos/123/-/content?w=256&h=256&fit=fill&r=auto&format=webp&q=80

To:

GET /assets/photos/123/-/content?width=256&height=256&fit=fill&rotate=auto&format=webp&quality=80

Names such as fit, format, filter, blur, pad, strip, profile, pixel-channels, and pixel-layout keep their existing spelling. The URL signature parameter remains s.

Regenerate URL signatures after renaming parameters. Sign the updated path and query string, with parameters sorted by their new keys.

Prefix each label query parameter with label:, including names that overlap transformation parameters. For example, use label:width=wide to filter by an asset label named width. Keep the label's key as width in upload and update JSON. See label query parameters.