API compression settings
The levels, formats, resize options and metadata switch the Iminify API takes, what each one does to an image, and requests for common jobs.
Four settings decide what happens to an image: the level, the format, the size (width, height or scale) and keep_metadata. An upload, a recompress and a page scan all take the same fields, and all of them are optional: leave everything out and you get Smart compression in the image's own format, at its own size, with its metadata stripped.
They're the same choices as the settings panel on the website, and they run through the same encoders, so an image compressed here comes out exactly as it would there.
Levels
level |
What it does |
|---|---|
smart |
The default. Finds the lowest quality that still looks like your upload, measured on the image, not guessed. |
ultra |
The same search with lower targets. Files get smaller and fine texture softens a little. |
lossless |
Changes no pixel. The file shrinks only as far as a better encoding of the same pixels allows. |
none |
Compresses nothing. Only the format, the resize and the metadata choice are applied. |
Smart and Ultra don't take a quality number from you, because the same number means something different in every encoder. For JPG, WebP and AVIF output they encode the image at several qualities and keep the smallest that still clears the level's target, measured against your upload: 40 dB PSNR for Smart and 34 dB for Ultra, then 70 and 50 on the SSIMULACRA 2 scale. For what those scores look like and what each costs in kilobytes, see SSIMULACRA 2 scores in practice. These are targets, not guarantees. The search runs on images up to 36 megapixels (the perceptual check up to 8); larger ones are encoded at the level's fixed quality ceiling. A PNG is reduced to a smaller palette and a GIF compressed at a fixed setting for the level, neither against a target.
Lossless repacks a JPEG, PNG or GIF without changing a pixel, except that a PNG tagged with a wide-gamut colour profile is converted to sRGB. A lossy WebP has no repack step, so Lossless re-encodes it at a very high quality.
When nothing comes out smaller than the upload and you asked for no other change, the image ends as already-optimized and the upload itself is handed back as the optimized copy. You never get a bigger file from compression alone.
Formats
Iminify reads PNG, JPG, JPEG, WEBP, GIF, HEIC, HEIF, TIFF, TIF. It writes WebP, AVIF, PNG and JPG.
format |
What you get |
|---|---|
| left out | The upload's own format. A HEIC or TIFF can't stay one, because Iminify doesn't write either, so it's treated as auto. |
webp |
WebP. Every current browser shows it. An animated GIF stays animated. |
avif |
AVIF. Usually the smallest for photographs, and the slowest to encode. |
png |
PNG. Keeps transparency; Smart and Ultra reduce it to a palette. |
jpg |
JPG, encoded with jpegli. jpeg is read as jpg. |
auto |
Up to 8 megapixels, the image is encoded in every format that can hold it without losing transparency or animation, and the smallest file wins. Above that it goes straight to webp. |
Converting an animated GIF to PNG, JPG or AVIF keeps only its first frame; WebP keeps every frame. The converted format is optimized.format on the finished image.
Not sure between the two modern formats? AVIF against WebP on ten images at one quality score has the numbers, and the cases where WebP still wins; auto makes that call per image.
Resizing
| Fields | Result |
|---|---|
width |
That width; the height follows the aspect ratio. |
height |
That height; the width follows. |
width and height |
Exactly that size. If the proportions differ from the image's, it's stretched to fit. |
scale |
That percentage of each side, from 1 to 100. It can't be combined with width or height. |
Sides go up to 65535 pixels, and the resized image can't be larger than 64 megapixels. The sizes are measured the way the image displays, so a phone photo stored on its side is resized as you see it, upright.
Sending the width a page actually shows usually saves more than any level; How many KB should a website image be? measures it at four widths.
Metadata
By default the optimized copy has its EXIF metadata stripped: camera model, date, GPS location. Send keep_metadata=true to carry it across, into WebP and AVIF too. Either way the orientation is applied to the pixels first, so a stripped photo never comes back sideways, and a Display P3 or CMYK colour profile is converted to sRGB rather than dropped, so the colours stay put. The original you uploaded keeps its metadata in storage whatever you choose.
Common jobs
| Job | Fields |
|---|---|
| Web-ready photos | format=webp, width=1600 |
| The smallest file whatever the format | level=ultra, format=auto |
| Smaller PNGs without touching a pixel | level=lossless |
| iPhone photos to JPG, keeping the location | format=jpg, keep_metadata=true |
| Thumbnails at a quarter size, no extra compression | level=none, scale=25 |
In a multipart upload each field is a form field (-F "format=webp" with curl); everywhere else it's a key in the JSON body. A multipart form sends true and false as text, which is fine: keep_metadata takes true, false, 1, 0, yes and no.
Further reading
The measurements behind these settings, from the Iminify blog:
- SSIMULACRA 2 scores in practice: what the perceptual scores behind Smart and Ultra look like, and what they cost.
- JPEG 80 is not WebP 80: why a quality number means something different in every encoder.
- How many KB should a website image be?: the file sizes real images land at, at four common widths.
- What AVIF quality setting should you use?: for encoding AVIF yourself, after libavif 1.4 changed what the numbers mean.
- AVIF vs WebP file size: ten images at one quality score, and where WebP still wins.