Image transforms

Extract a section of the image, specifying the width and height of the area to extract.

In addition to specifying the size of the crop area, you can also specify its placement. The placement can be given in px or percent (pc) and defines where the center of the crop area is. The crop area will always be within the original image meaning if the placement is outside of the bounds it may be adjusted.

Instead of a placement you can anchor the crop to an edge or corner with ~position:, using the same positions as resize.

Crop to the most interesting part of the image at the width and height you give. The image is scaled to cover the size, like resize with fit cover, and the crop is moved to where there is the most detail, colour and skin tone instead of the centre.

It looks at edges, colour and skin tones on a small copy of the image, so it is fast and always gives the same result. An image with no stand-out area is cropped from the centre.

Rotate the image clockwise by any number of degrees. Negative angles turn it anticlockwise. Multiples of 90 are exact; other angles make the image larger to fit the corners.

When rotating, unless using angles of 90, 180, or 270 the produced image will have a visible background. By default this blank space is transparent (white for JPEG and BMP, which cannot be transparent). The colour of the background can be customised.

background

Flip the image on the X or Y axis, or both.

Round the corners by a radius in pixels, or use max to cut a circle (an ellipse on a rectangle). Crop to a square first for a round avatar. Edges are anti-aliased.

Add space around the image. Give one number for every side, two for vertical and horizontal, or four for top, right, bottom and left (like CSS). The space uses ~background:, then any earlier background transform, then transparent (white for JPEG). Each side is at most 2000px.

Add a solid border of the given width in pixels around the outside of the image. The colour defaults to black.

Cut away a plain border, such as the white space around a product photo or a scan. The border colour is the top-left pixel's unless you give one with ~color:. The number is the tolerance from 0 to 100 (default 10): how different a pixel can be and still count as border.

Serve sharp images on high density screens without changing your sizes: dpr:2 doubles every pixel size in the chain (resize, crop, smartCrop, pad, border and radius). It can go anywhere in the chain and takes 0.1 to 5.

Apply a Gaussian blur. The amount is the blur radius (sigma) in pixels, from 0 (no blur) to 100. Larger values are treated as 100.

Sharpen edges, useful after making an image smaller. The amount is from 0 to 10; leave it out for a gentle default of 1.

Remove all colour. greyscale works too.

Change the saturation of the image. The amount multiplies it: 0 is greyscale, 1 leaves the image unchanged and 2 doubles it. Values above 10 are treated as 10.

brightness lightens or darkens and contrast increases or reduces the difference between light and dark. Both take -100 to 100, where 0 leaves the image unchanged.

Rotate every colour round the colour wheel by a number of degrees.

Adjust the midtones without clipping the highlights or shadows. Above 1 lightens, below 1 darkens.

Give the image a warm, old photograph look. The amount is from 0 to 100 and defaults to 100.

Give the image the hue of a colour while keeping its light and shade. The colour's alpha sets the strength, so tint:hex(ff000080) is a half strength red tint.

Make the image see-through. The amount is from 0 (invisible) to 100 (unchanged).

Turn the image into square blocks of the given size in pixels, from 1 to 200.

Create a negative of the image.

Draw another image on top, such as a logo, a badge or a watermark. The overlay is an image file in the same app, given by its id: Fileboy never fetches an image from a URL. Transparent parts of a PNG or WebP overlay let the image show through.

overlay:FILE_ID~width:20pc~position:bottom-right~x:24~y:24~opacity:80

• width and height: the overlay's size, in pixels or a percentage of the image (20pc is a fifth of its width). Give one and the overlay keeps its shape; give both and it fits inside that box. Leave both out to draw it at its own size.
• transform:(…): transforms that run on the overlay first, written like any chain: transform:(resize:200x200~fit:cover;radius:max;grayscale). Format, palette, quality, dpr, strip, background and other layers belong in the main chain. Up to 10, and they count towards the limit of 20.

Overlays and text both take these options as well:

• position: the corner, edge or centre the layer is anchored to: center (the default), top, bottom, left, right, top-left, top-right, bottom-left or bottom-right.
• x and y: move the layer in from that edge, in pixels or a percentage of the image (5pc). From the centre, or along the middle of an edge, they move it right and down. Negative values move it the other way, and anything past the edge is cut off.
• opacity: 0 to 100 (default 100).
• rotate: degrees clockwise, applied after the layer is sized.
• tile:true repeats the layer across the whole image, lined up with where one copy would go, for a watermark pattern. gap is the space between copies, in pixels or a percentage of the image's width. A pattern can have up to 2,500 copies.

Write text on top: a caption, a photo credit or a repeated watermark. The text comes first and is URL-encoded inside the transform, so %20 is a space, %3B a ;, %7E a ~, %25 a % and %0A a new line. In the URL itself that encoding is encoded again (%2520); the SDKs do both for you.

• font: sans (the default), sans-bold, sans-italic, mono or mono-bold. These are the Go fonts, which cover Latin, Greek and Cyrillic; other scripts and emoji show as boxes.
• size: pixels (default 32), or a percentage of the image's height (5pc) so it scales with the image.
• color: default black. background fills a box behind the text, with padding pixels around it. Colours with alpha work for both.
• wrap: lines wider than this break at spaces, in pixels or a percentage of the image's width. align lines up the lines: left, center or right.
• Plus position, x, y, opacity, rotate, tile and gap, as for overlays.

Change the file format. auto picks the smallest format the browser says it accepts in its Accept header: AVIF, then WebP, then the original format (BMP and TIFF become PNG). Every current browser sends that header for images, so a plain <img> tag is enough. Each outcome is cached separately and the response sends Vary: Accept, so a CDN in front keeps them apart too.

avif asks for AVIF whatever the browser accepts, except for very large images, which come back as WebP (see below). AVIF is usually the smallest: in our tests, photos came out about 30% smaller than WebP at the same visual quality, and graphics and smooth gradients up to half the size. It keeps transparency exactly. quality means the same in every format, so quality:75 as AVIF looks about as good as quality:75 as WebP.

AVIF is slow to make, so an image over 16 megapixels (4096 × 4096) is sent as WebP instead, for auto and avif alike, and the response's Content-Type says which you got. With lossless in the chain, auto picks WebP over AVIF, because lossless WebP is the smaller. Animated GIF and WebP files cannot be transformed, so they are served as they are, still animated.

format:json answers with the size of the image instead of the image: the width and height after the other transforms, and the original's size, format and file size. Use it to reserve space for an image before it loads, or to check an upload.

{
  "width": 300,
  "height": 200,
  "original": { "width": 1200, "height": 800, "format": "image/jpeg", "bytes": 254311 }
}

palette answers with the main colours of the image instead of the image: the dominant colour, up to 16 colours with their share of the image, vibrant and muted swatches, and a black or white text colour for each that meets WCAG AA. On its own it describes the original and is answered from the palette stored with the file. After other transforms it describes their result, so crop first to get the colours of part of the image. After an overlay or text it includes what they drew, and needs a signed URL whenever the overlay does.

{
  "dominant": { "hex": "#2f5d8a", "rgb": [47, 93, 138], "share": 0.42, "text": "#ffffff", "contrast": 6.88 },
  "colors": [ ... ],
  "swatches": { "vibrant": { ... }, "darkMuted": { ... }, "lightVibrant": null, ... },
  "transparentShare": 0
}

palette:css answers with CSS custom properties and classes instead. ~colors: sets how many colours are listed (0 to 16, default 6) and ~prefix: names the CSS. See Colour palettes for every field.

Make WebP or AVIF output lossless: every pixel is kept exactly, at the cost of a bigger file. It suits screenshots, diagrams and logos. PNG, TIFF and BMP are always lossless, and JPEG cannot be, so it only changes WebP and AVIF. Lossless WebP is usually smaller than lossless AVIF, so format:auto picks WebP for a lossless chain.

Reduce the file size of an image by sacrificing quality. Smaller file sizes will help improve load times on your application especially for slower connections.

The background transform does nothing in and of itself, but rather it affects all other transforms which utilize a background option such as resize or rotate. The background transform will set the default background color for these transforms enabling you to remove possible duplication.

Re-encode the image without changing it, which removes EXIF (including GPS location), ICC profiles and other metadata. Every transform already does this; use strip when you want nothing else changed.