scaleImage(bytes, width, height, [options]) Last updated: 10. Jul 2026

API only function

Scales an image byte array to a target size and returns the scaled image as bytes. Supports several scaling modes and lets you preserve or convert between JPEG, PNG, WebP and AVIF output formats. The optional parameters (mode, quality, format) can be supplied positionally or as a single options object — see the examples below.

Note: scaleImage runs server-side and is controlled entirely by your own code. It is NOT subject to Images.SizePolicy in site.json — only URL-based scaling (/photo.jpg/WxHxM/...) is enforced against the allowed-sizes policy. See the 'Image output formats (WebP / AVIF)' section on the Image scaling page. scaleImage is not subject to the image size policy; to enable and register the sizes that ARE enforced (URL-based scaling), see the KB article Restrict and register image sizes.

Parameters

Name	Type	Description
bytes	byte[]	Input image bytes (PNG, JPEG, GIF, BMP, or any format supported by the image scaler).
width	number	Target width in pixels. Must be positive.
height	number	Target height in pixels. Must be positive.
options (optional)	object	Specify any of the following options parameters:
• mode	string or number	Scaling mode. Accepts either the enum name as a string or the numeric value: • "ScaleToFit" (0) — proportional, never grows the image. Default. • "ScaleToFill" (1) — fills target, may crop edges to keep aspect ratio. • "Resize" (2) — exact target size, may distort aspect ratio. • "SkipResize" (-1) — returns the original image unchanged. • "ScaleAndFill" (3) — fit + white padding to exact target size. • "ScaleAndFillBlack" (4) — fit + black padding to exact target size. • "ConvertToJpegNoResize" (5) — re-encode without resizing. Same modes used by the /scale-URL on embedded files. Default is "ScaleToFit" (0).
• quality	number	Output quality 0-100. Applies to lossy formats (JPEG, WebP, AVIF). Ignored when the output is PNG. Default 85.
• format	string	Output format: • "auto" — preserve PNG when the input starts with the PNG signature, otherwise output JPEG. Falls back to Images.DefaultFormat from site.json when that is set. Default. • "png" — force PNG output (preserves transparency). Encoded with GDI+. • "jpeg" / "jpg" — force JPEG output. Encoded with GDI+ (fastest). • "webp" — force WebP output (Magick.NET). Better compression than JPEG with universal browser support today. • "avif" — force AVIF output (Magick.NET). Best compression; supported by modern browsers. Recommended for the highest performance score. An explicit format always wins over Images.DefaultFormat. quality also applies to WebP/AVIF.

Returns

The scaled image as a byte array.

Notes:
• Throws when the input bytes are empty, are not a valid image, or when width/height are non-positive.
• "auto" format keeps PNG transparency for PNG sources and outputs JPEG for everything else.
• Mode names match the ImageScaleMode enum used elsewhere in the platform.

Example

Code example (JS)

JS is normal JavaScript either running in the browser or on the Docly™ server.

// Image bytes — e.g. retrieved with getEmbeddedFile()
let imageBytes = docly.getEmbeddedFile(filePath, embedId);

// Simplest form — defaults: ScaleToFit, quality 85, auto format
let thumb = docly.scaleImage(imageBytes, 200, 200);

// Force PNG output to preserve transparency
let smallLogo = docly.scaleImage(imageBytes, 64, 64, { format: "png" });

// Combine several options
let avatar = docly.scaleImage(imageBytes, 100, 100, {
    mode: "ScaleToFill",
    quality: 75,
    format: "jpeg"
});

// Modern formats: WebP (positional args) and AVIF (options object)
let webp = docly.scaleImage(imageBytes, 1200, 800, 0, 80, "webp");
let avif = docly.scaleImage(imageBytes, 800, 600, { quality: 60, format: "avif" });