The quality scale

Image quality, 0 to 100

image.quality is a whole number from 0 to 100. The default is 75. A higher number keeps more detail and gives a larger file. The same number is used for every image format, but each encoder reads it in its own way.

Because WebP and PNG switch to lossless at 96, a file at 96 can be several times larger than the same file at 95. Use 96 or above only when you need exact pixels.

The number applies to compress requests. If the result at your setting is larger than the input, the API tries once more at a lower setting before it gives up. See Kept original.

How PNG uses the number

Below 96, a PNG is compressed in two steps. First the colours are reduced to a palette. The quality number sets the range the palette step must stay inside. Then the file is optimised losslessly, at an effort level that also follows the number.

palette minimum     = max(0, round(0.8 × quality − 10))
palette maximum     = min(100, quality + 10)
optimisation level  = round(quality ÷ 100 × 4) + 2

If the palette step cannot reach the minimum, or would make the file larger, it is skipped and the file is only optimised.

PDF presets

pdf.quality is one of five presets. The default is medium. A preset sets how the images inside the PDF are resampled and recompressed. Text and vector drawings are not changed.

Images smaller than 10,000 pixels and JPEGs smaller than 8,192 bytes are left alone. An image is replaced only when the new version is smaller. The file structure is then rewritten and its streams are compressed.

Video tiers

video.quality is a named tier. The default is high. Each tier maps to a constant rate factor (CRF) for the chosen codec. A lower CRF keeps more detail and gives a larger file.

• video.crf (0 to 63) replaces the tier's CRF with your own value.
• The encoder preset is medium. video.slow changes it to slow, which takes longer and gives a smaller file at the same CRF. video.preset sets it directly.
• The audio track is encoded at the video.audio_quality tier, using the bitrates in the next section. The default is high.
• WebM output always uses VP9, whatever video.codec says.

Audio tiers

audio.quality is a named tier. The default is high. Each tier is a bitrate.

audio.bitrate_kbps (16 to 512) replaces the tier's bitrate with your own value. The lossless formats (wav, flac and alac) take no bitrate, so the tier has no effect on them.

Quality when converting

The convert endpoint changes the format and keeps as much quality as it can. It does not read the quality options above. It uses fixed settings:

To change the format and choose the quality in one request, use compress with a format option, for example image.format=avif&image.quality=60.

Choosing a setting

• Images. Start with the default, 75. Go lower, to between 50 and 65, for thumbnails and background pictures. Go higher, to between 85 and 90, when fine detail matters, as in product photos. Check the result by eye at the size it will be shown.
• PDFs. medium suits reading on a screen. tiny and small suit email attachments where the pictures only need to be recognisable. large and original suit documents that will be printed.
• Video. high is close to the source. For H.265 and H.264, web sits between low and balanced and suits video played in a web page.
• Audio. Speech stays clear at tiny or low, more so with audio.channels=mono. Use balanced or high for music.

Every option and its allowed values are listed in Options.