Skip to content

Image Optimisation and Transformation API

The Image Optimisation API is a comprehensive tool for transforming, optimising and resizing images for a variety of use cases. With this API, you can perform advanced image operations including resizing, effects processing, color adjustments, geometric transformations, and content overlay to improve image quality and reduce file sizes.

Key Features

Size and Cropping

  • Resizing images to specified dimensions with multiple fit modes (clip, scale, crop, fill, facearea)
  • Advanced cropping with center, face detection, attention area, or entropy-based focus
  • Device-pixel ratio (DPR) support for high-resolution displays
  • Automatic width breakpoint generation for responsive variants when client hints are enabled
  • Smart face detection and face-area cropping

Format and Quality Control

  • Format conversion between JPEG, PNG, WebP, AVIF, JXL, GIF, and SVG
  • Intelligent quality optimization with custom quality settings
  • Lossless compression options
  • Chroma subsampling control (4:2:0, 4:2:2, 4:4:4)
  • Color space management

Visual Effects and Adjustments

  • Blur Effects: Gaussian blur with intensity control (0.1-10.0)
  • Sharpening: Unsharp mask and simple sharpening with configurable parameters
  • Color Adjustments: Brightness, contrast, saturation, and gamma correction (-100 to +100 range)
  • Tone Mapping: Hue shifting (0-359°), vibrance, highlights, and shadows adjustment
  • Style Effects: Sepia, grayscale, monochrome, and duotone filters

Geometric Transformations

  • Image rotation (0-360°)
  • Horizontal and vertical flipping
  • Padding with configurable per-side values
  • Border addition with customizable width, color, and corner radius

Content Overlay

  • Text overlay with font, size, color, alignment, and positioning control
  • Watermark placement with opacity and position control
  • Background color and fill options

Masking and Shapes

  • Ellipse masking
  • Corner radius masking for rounded corners
  • Custom mask background colors

Automatic Optimization

  • Auto format selection for optimal browser compatibility
  • Auto optimization for file size reduction
  • Client hints support for responsive delivery with width and DPR-specific variant negotiation

Variant Negotiation and Headers

  • Generates Variants-06 and Variant-Key-06 headers that enumerate available width and DPR combinations
  • Chooses variant content-types (e.g., WebP, AVIF) based on browser capabilities and automatic optimisation policies
  • Safely propagates derived width and DPR values through all filters without mutating original requests

Advanced Use Cases

  • E-commerce: Product image standardization with consistent sizing, quality, and watermarking
  • Content Management: Automatic format conversion and optimization for different devices
  • Social Media: Image processing with effects, overlays, and branding
  • Performance Optimization: Intelligent compression and format selection for faster loading
  • Responsive Design: Device-aware image delivery with DPR and client hints support
  • Brand Management: Consistent styling with color adjustments and watermarks

API Parameter Categories

Size Parameters

  • w, h - Width and height dimensions
  • fit - Scaling behavior (clip, scale, crop, fill, facearea)
  • crop - Cropping focus (centre, faces, attention, entropy, etc.)
  • dpr - Device pixel ratio

Format Parameters

  • fm - Output format (jpeg, png, webp, avif, jxl, gif, svg)
  • q - Quality setting (1-100 or quality preset)
  • lossless - Enable lossless compression
  • chromasub - Chroma subsampling mode
  • cs - Color space

Effect Parameters

  • blur - Gaussian blur intensity (0.1-10.0)
  • usm - Unsharp mask intensity (0.5-5.0)
  • usmrad - Unsharp mask radius (1.0-10.0)
  • sharp - Simple sharpening (1.0-100.0)

Color Parameters

  • brightness - Brightness adjustment (-100 to +100)
  • contrast - Contrast adjustment (-100 to +100)
  • saturation - Saturation adjustment (-100 to +100)
  • gamma - Gamma correction (0.1-5.0)

Tone Parameters

  • hue - Hue shift in degrees (0-359)
  • vib - Vibrance adjustment (-100 to +100)
  • high - Highlights adjustment (-100 to 0)
  • shad - Shadows adjustment (0 to +100)

Style Parameters

  • sepia - Sepia effect intensity (0-100)
  • grayscale - Convert to grayscale (true/false)
  • monochrome - Monochrome effect with specified color
  • duotone - Duotone effect with "color1,color2" format

Geometry Parameters

  • flip - Image flipping (h, v, hv)
  • rot - Rotation in degrees (0-360)
  • pad - Uniform padding, or pad_top, pad_right, pad_bottom, pad_left for individual sides
  • border - Border width with optional border_color and border_radius

Overlay Parameters

  • txt - Text overlays with size, font, colour, alignment or absolute offsets, width/fit/clip controls, outlines, tracking, leading, and optional drop shadows (txt_shad)
  • wm_url - Watermark image URL with base resolution (wm_base), position/padding/offsets, opacity, proportional scaling (wm_scale) or explicit sizing (wm_width/wm_height with wm_fit), tiling, rotation, and minimum dimension guards

Auto Optimization

  • auto - Automatic optimization modes (optimize, format, or both)
  • ch - Client hints support (width, dpr, savedata)

Variant-Aware Delivery

When ch=width and/or ch=dpr is enabled, the optimiser evaluates the original asset and the requesting device to derive optimal breakpoints. Those derived values are passed through each filter as cloned API parameters, ensuring downstream steps such as resizing and encoding operate on consistent dimensions. Responses include updated Variants-06, Variant-Key-06, and Vary headers that describe the negotiated width and DPR combinations alongside the selected content-types. If no breakpoints are needed (for example, very small assets), the original dimensions are preserved and the legacy header format is maintained.

Presets and Override Order

Named presets supplied via the t query parameter can now be stacked. Multiple t parameters—or comma-separated names—are processed in order, with later presets overriding earlier values. Header overrides (peakhour-optimiser-options) are applied next, and explicit query parameters take precedence over both presets and headers. This mirrors the behaviour of the runtime pipeline, where filters respect caller-specified values while still allowing automatic optimisations to return refined copies of the options.

Example Usage

Advanced Image Processing

https://yoursite.com/image.jpg?w=800&h=600&fit=crop&crop=faces&blur=1.5&brightness=10&contrast=20&sepia=25&border=5&border_color=white&auto=optimize,format

Responsive Delivery with Effects

https://yoursite.com/image.jpg?w=400&dpr=2&fm=webp&q=85&usm=2.0&saturation=15&auto=format

Text and Watermark Overlay

https://yoursite.com/image.jpg?txt=Sample%20Text&txt_size=48&txt_color=white&txt_align=center,middle&wm_url=/logo.png&wm_pos=northeast&wm_opacity=0.7

With Peakhour's comprehensive Image API, you can create sophisticated image processing pipelines that automatically optimize images for performance while applying professional-grade visual enhancements.