Compressor APIProcessingImages

Images

The Compressor Images API delivers industry-leading image compression with a strong focus on maximum byte savings and uncompromised visual quality. By combining modern image codecs with format-aware compression algorithms, Compressor consistently produces smaller files while preserving sharpness, color accuracy, and perceptual detail.

In real-world scenarios, the API can achieve 90%+ file size reduction — especially when converting legacy formats to modern image codecs — making it ideal for performance-critical websites, media-heavy applications, and large-scale asset pipelines.

Typical Use Cases

  • Website and CDN image optimization
  • Improving Core Web Vitals and SEO performance
  • Reducing bandwidth and storage costs
  • Optimizing user-generated image uploads
  • Preparing images for responsive delivery

Image Compression API

All image processing supports a unified compression parameter that controls how aggressively the image is optimized. Compression settings are passed under the image namespace:

{
  "image": {
    "compression": "high"
  }
}

Compression Modes

  • medium - balanced compression optimized for most use cases. Delivers meaningful file size reduction while preserving excellent visual quality.

  • high (default) - more aggressive optimization, suitable for performance-sensitive applications such as mobile delivery, content feeds, and image-heavy pages.

  • ultra - maximum compression for the highest possible byte savings. Ideal for thumbnails, previews, and scenarios where minimizing file size is critical.

The default compression mode is high. Higher compression modes generally result in smaller output files. Compressor automatically adapts its optimization strategy based on the image format and content to achieve the best possible results.

Supported Input Formats

The Images API accepts virtually all widely used image formats, including: JPEG, PNG, WebP, AVIF, HEIC, GIF, TIFF, BMP, SVG, ICO.

Input format detection is automatic and you do not need to specify the source format explicitly.

Output Formats

Processed images can be returned in the following output formats: JPEG, PNG, GIF, WebP, AVIF.

Format Retention

By default, Compressor preserves the original image format:

  • JPEG → JPEG
  • PNG → PNG
  • WebP → WebP
  • AVIF → AVIF
  • GIF → GIF

This ensures compatibility and predictable output without requiring additional configuration.

Special Format Rules

ICO and SVG inputs always retain their original format after compression. Format conversion is not applied to these formats.

Image Format Conversion

To explicitly convert images to a different output format, specify the desired conversion under the image namespace using an input → output mapping.

Example: convert JPEG input to AVIF output:

{
  "image": {
    "jpeg": "avif"
  }
}

This instructs the API to convert any JPEG input image into AVIF, resulting in significantly smaller files while maintaining high visual quality.

Format conversion can be combined with compression settings and other image operations in a single request, for example:

{
  "image": {
    "compression": "ultra",
    "jpeg": "avif"
  }
}

Image Resizing API

The Images API provides flexible resizing and cropping capabilities designed for responsive layouts, thumbnails, previews, and standardized asset pipelines. Resizing operations are format-aware and preserve image quality while applying the selected compression level.

All resizing options are configured under the image.resize namespace.

{
  "image": {
    "resize": {
      "mode": "auto",
      "width": 1200,
      "height": 800
    }
  }
}

Resize Modes

Compressor supports four resize modes to accommodate different layout and design requirements.

auto

Auto mode is the default resizing approach. It automatically resizes the image while preserving its aspect ratio. At least one of width or height must be provided.

  • If only width is specified, the height is calculated automatically.
  • If only height is specified, the width is calculated automatically.
  • If both are specified, the image is scaled proportionally to fit within the bounding box.

This mode is ideal for most responsive use cases.

fit

In fit mode, the image is resized so that it fully covers the requested dimensions, while preserving its original aspect ratio. Both width and height parameters are required.

The image is scaled proportionally until the entire output frame is filled. Any parts of the image that extend beyond the specified dimensions are cropped out. If the source image is smaller than the target size, it will be upscaled to ensure full coverage.

By default, cropping is performed from the center of the image. You can control which area is preserved by setting the gravity parameter to one of the following values: top-left, top, top-right, right, bottom-right, bottom, bottom-left, left

This mode is ideal for thumbnails, hero images, cards, and any layout where exact dimensions and edge-to-edge coverage are required.

fill

In this mode, both width and height attributes are required. It resizes the image so that it fits within the requested dimensions while preserving its aspect ratio. If the source image does not perfectly match the target aspect ratio, empty space may remain around the image. This space is filled according to the selected background behavior.

By default, this space is filled with a transparent background for formats that support transparency (PNG, WebP, AVIF), or white for formats that do not (such as JPEG).

When empty space is present, the following background options are available:

Solid Color - A solid color can be defined using a hexadecimal RGB or RGBA value (for example #ff3b00 or#ff3b00cc). Alternatively, setting the background to auto will fill the empty space with the dominant color extracted from the image, producing a natural and visually consistent result that blends seamlessly with the content.

{
  "image": {
    "resize": {
      "mode": "fill",
      "width": 640,
      "height": 480,
      "background": "#ff3b00"
    }
  }
}

Background Blur - To enable background blur, set the background parameter to blur. In this mode, any empty space created by the fill strategy is populated using a softly blurred version of the original image. This approach is ideal for banners, previews, and mixed–aspect-ratio layouts where you want to preserve visual continuity without introducing solid color padding.

{
  "image": {
    "resize": {
      "mode": "fill",
      "width": 640,
      "height": 480,
      "background": "blur"
    }
  }
}

Use fill mode when you need predictable output dimensions without cropping, while retaining full control over how any remaining space around the image is handled.

On this page