DEV Community: Sahadat Husain

Compress images from Python with the Blinkimg API and requests

Sahadat Husain — Fri, 06 Nov 2026 14:00:00 +0000

To compress an image from Python with the Blinkimg API you make four HTTP calls with requests: ask for an upload slot, PUT the bytes, create a job, then read the result link. The client below is 40 lines with no SDK. In my run it turned a 576.8 KB JPEG into a 93.9 KB AVIF with targetBytes: 100000.

What does the API flow look like?

The API has three endpoints you need, under https://api.blinkimg.com/v1:

POST /v1/uploads with filename and contentLength. It answers with an uploadId and a signed url. You PUT the file to that url.
POST /v1/jobs with the uploadId and an options object: format, quality or targetBytes, resize, stripMetadata.
GET /v1/jobs/{id} until status leaves queued and processing, then GET /v1/jobs/{id}/result for a signed link to the file.

Every call carries Authorization: Bearer <key>. You create the key from your account; the API docs list the endpoints and the OpenAPI description.

The whole client

import os, sys, time, uuid
from pathlib import Path
import requests

API = os.environ.get("BLINKIMG_API", "https://api.blinkimg.com/v1")
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['BLINKIMG_KEY']}"


class BlinkimgError(Exception):
    pass


def call(method, path, **kw):
    r = session.request(method, f"{API}{path}", timeout=30, **kw)
    if r.status_code >= 400:
        err = r.json().get("error", {})
        raise BlinkimgError(f"{r.status_code} {err.get('code')}: {err.get('message')}")
    return r.json()


def compress(src: Path, dest_dir: Path, **options) -> dict:
    data = src.read_bytes()
    # 1. an upload slot, then the bytes straight to storage (no auth header there)
    upload = call("POST", "/uploads",
                  json={"filename": src.name, "contentLength": len(data)})
    requests.put(upload["url"], data=data, timeout=60).raise_for_status()
    # 2. the job; the Idempotency-Key makes a retried POST return the same job
    job = call("POST", "/jobs",
               json={"uploadId": upload["uploadId"], "options": options},
               headers={"Idempotency-Key": str(uuid.uuid4())})
    # 3. poll until the job leaves queued/processing
    while job["status"] in ("queued", "processing"):
        time.sleep(0.5)
        job = call("GET", f"/jobs/{job['id']}")
    if job["status"] != "succeeded":
        raise BlinkimgError(f"job {job['status']}: {job.get('error')}")
    link = call("GET", f"/jobs/{job['id']}/result")
    out = dest_dir / link["filename"]
    out.write_bytes(requests.get(link["url"], timeout=60).content)
    return {"file": out.name, **job["result"]}


if __name__ == "__main__":
    fmt, cap = sys.argv[1], int(sys.argv[2])
    out_dir = Path("out"); out_dir.mkdir(exist_ok=True)
    for name in sys.argv[3:]:
        r = compress(Path(name), out_dir, format=fmt, targetBytes=cap)
        print(f"{name:15} {r['inputBytes']:>9,} -> {r['outputBytes']:>7,} B "
              f"{r['outputFormat']:5} {r['width']}x{r['height']} "
              f"saved {r['savedPercent']}%  {r['file']}")

Three choices in it are deliberate.

One Session. The requests docs say a session reuses the underlying TCP connection to the same host (requests: Session objects). The polling loop makes several calls per file, so that saves a handshake each time.
A timeout on every call. By default requests do not time out unless you set one (requests: Timeouts). A script that runs overnight should never hang on one socket.
An Idempotency-Key on the job. The API accepts this header on POST /v1/jobs. If you add a retry around that call and keep the same key, a repeated POST returns the first job instead of creating (and charging for) a second one.

What did it print?

export BLINKIMG_KEY=bk_...
python blinkimg_compress.py avif 100000 photo.jpg photo.png screenshot.png
python blinkimg_compress.py jpeg 50000 photo.jpg

photo.jpg         576,828 ->  93,922 B avif  1920x1280 saved 83.7%  photo.avif
photo.png       4,096,344 ->  93,922 B avif  1920x1280 saved 97.7%  photo.avif
screenshot.png  1,121,126 ->  99,028 B avif  2880x1800 saved 91.2%  screenshot.avif
photo.jpg         576,828 ->  48,734 B jpeg  1920x1280 saved 91.6%  photo.jpg

Input	Bytes in	Job options	Bytes out
photo.jpg, 1920 × 1280	576.8 KB	avif, targetBytes 100000	93.9 KB
photo.png, same photo	4,096.3 KB	avif, targetBytes 100000	93.9 KB
screenshot.png, 2880 × 1800	1,121.1 KB	avif, targetBytes 100000	99.0 KB
photo.jpg	576.8 KB	jpeg, targetBytes 50000	48.7 KB

Every output landed under its cap. The JPEG and the PNG of the same photo gave AVIFs of the same size, 93,922 bytes: the encoder sees the same pixels. And the 50 KB JPEG run matches the 48.7 KB the site publishes for that photo; how the site measures explains where its numbers come from.

Note: The upload url points at object storage, not at the API. That is why the client PUTs with plain requests.put and not with the session: the session carries your Bearer key, and the key has no business going to the storage host. Send only the bytes there.

What does an error look like?

Every API error has the same body: {"error": {"code", "message", "requestId"}}. The call() helper turns it into one exception. With a wrong key (the message text came from my local stand-in; the code is the API's):

__main__.BlinkimgError: 401 UNAUTHORIZED: bad key

The codes you will meet most in a batch script are UNAUTHORIZED, FILE_TOO_LARGE, INSUFFICIENT_CREDITS and RATE_LIMITED. A 429 also carries a Retry-After header; sleep that many seconds and try again. Keyed requests are shaped at 120 writes a minute.

What does it cost?

Compressing an image costs 1 credit; converting it to another format costs 2. Every account gets 500 free credits a month. The four runs above were three conversions and one compress, so 7 credits on the real service.

How I measured

Machine: Apple M1 Pro (8 cores), macOS, 2026-10-17.
Python 3.9.6, requests 2.32.5 in a fresh venv.
Files: photo.jpg, photo.png and screenshot.png from the site's reference set (apps/web/assets/reference/).
The API calls ran against a local stand-in of /v1 that I wrote from the API's published request and response contract (packages/shared/src/api/uploads.ts and jobs.ts), with the Blinkimg engine (processImage, the code the workers run) doing every encode. The byte counts are the engine's; the error body shape and codes come from the API's own schema.

What I did not test

I did not call the production api.blinkimg.com with a live key for this article, so I report no network timings. I did not test batches, /zip or retries under a real 429.

I build Blinkimg, an image compressor and converter with a developer API. I wrote this article with help from an AI assistant (Claude), which ran the code on my machine; every number in it comes from those runs.

When can a PNG become a JPEG? Check opacity with sharp stats

Sahadat Husain — Thu, 05 Nov 2026 14:00:00 +0000

A PNG can become a JPEG when every pixel is fully opaque. In Node, (await sharp(file).stats()).isOpaque answers that in one call. The flag is true when the image has no alpha channel, or when the alpha channel is 255 everywhere. On my test files, opaque PNGs shrank from 4,096.3 KB to 293.6 KB as JPEG.

The catch: hasAlpha is the wrong question. A file can carry an alpha channel and never use it.

Why is hasAlpha not enough?

metadata().hasAlpha only says the channel exists. Design tools and screen capture apps often write RGBA files where every alpha value is 255. Those files look exactly like an RGB image, but a hasAlpha check keeps them as PNG forever.

The sharp docs describe isOpaque as true "if the image has no alpha channel or if every pixel is fully opaque" (sharp stats()). That reads the pixels, so it catches the unused channel.

The check, in 25 lines

import sharp from 'sharp';
import { statSync } from 'node:fs';

async function opacity(file) {
  const image = sharp(file);
  const { hasAlpha, channels } = await image.metadata();
  const stats = await image.stats();
  if (!hasAlpha) return { hasAlpha, isOpaque: stats.isOpaque, minAlpha: 255, seeThrough: 0 };
  const alpha = stats.channels[channels - 1];
  // Count the pixels that are not fully opaque.
  const raw = await sharp(file).extractChannel(channels - 1).raw().toBuffer();
  let seeThrough = 0;
  for (const a of raw) if (a < 255) seeThrough++;
  return { hasAlpha, isOpaque: stats.isOpaque, minAlpha: alpha.min, seeThrough };
}

for (const file of process.argv.slice(2)) {
  const o = await opacity(file);
  const jpeg = await sharp(file).flatten({ background: '#ffffff' })
    .jpeg({ quality: 80, mozjpeg: true }).toBuffer();
  console.log(file.padEnd(20), JSON.stringify(o),
    'png', statSync(file).size, 'jpeg', jpeg.length);
}

stats().channels holds one entry per channel, so the last one is alpha. Its min tells you the most transparent pixel in the file. The pixel count is optional; you only need it if you want a tolerance (more on that below).

What did it print on real files?

I ran it on six files: a logo with real transparency, a 1920 × 1280 photo saved as PNG, the same photo with an all-255 alpha channel added, that copy with one corner pixel set to alpha 254, a 2880 × 1800 desktop screenshot, and a 768 × 1376 phone screenshot that is RGBA.

transparent.png      {"hasAlpha":true,"isOpaque":false,"minAlpha":0,"seeThrough":130391} png 7931 jpeg 6224
photo.png            {"hasAlpha":false,"isOpaque":true,"minAlpha":255,"seeThrough":0} png 4096344 jpeg 293649
photo-rgba.png       {"hasAlpha":true,"isOpaque":true,"minAlpha":255,"seeThrough":0} png 4349210 jpeg 293649
photo-one-pixel.png  {"hasAlpha":true,"isOpaque":false,"minAlpha":254,"seeThrough":1} png 4349221 jpeg 293649
screenshot.png       {"hasAlpha":false,"isOpaque":true,"minAlpha":255,"seeThrough":0} png 1121126 jpeg 169526
screen2.png          {"hasAlpha":true,"isOpaque":true,"minAlpha":255,"seeThrough":0} png 2683707 jpeg 119015

File	hasAlpha	isOpaque	PNG	JPEG q80
transparent.png (512 × 512)	true	false	7.9 KB	6.2 KB
photo.png	false	true	4,096.3 KB	293.6 KB
photo-rgba.png	true	true	4,349.2 KB	293.6 KB
photo-one-pixel.png	true	false	4,349.2 KB	293.6 KB
screenshot.png	false	true	1,121.1 KB	169.5 KB
screen2.png	true	true	2,683.7 KB	119.0 KB

Two rows matter. screen2.png has an alpha channel and a hasAlpha check would keep it as a 2,683.7 KB PNG. isOpaque says it is safe, and the JPEG is 119.0 KB. Then photo-one-pixel.png: one pixel out of 2,457,600 sits at alpha 254, and isOpaque flips to false.

Should one pixel at 254 keep a file as PNG?

That depends on your product. isOpaque is strict on purpose: it never guesses. A pixel at 254 is invisible on any background, so you may want a tolerance. The minAlpha and seeThrough fields give you one:

const safeAsJpeg = (o) => o.isOpaque || (o.minAlpha >= 250 && o.seeThrough < 100);

Pick the numbers for your own files. A logo with soft anti-aliased edges has thousands of pixels between 1 and 254, so a tolerance like this one still keeps it as PNG.

What goes wrong if you convert without the check?

The transparent pixels turn black. I converted transparent.png to JPEG with no flatten() call and read the top-left pixel back:

source corner RGBA [ 42, 157, 143, 0 ]
jpeg corner RGB    [ 0, 0, 0 ]

Note: sharp's flatten() merges alpha onto a background and its default background is black, {r: 0, g: 0, b: 0} (sharp flatten()). Writing JPEG from an RGBA input lands on the same black. Always pass a background you chose, even for files isOpaque approved, so a tolerance never paints a black speck.

How much does the check cost?

One stats() pass decodes the image once. Median of 5 runs:

File	stats()
transparent.png (512 × 512)	39.5 ms
screen2.png (768 × 1376)	66.1 ms
photo-rgba.png (1920 × 1280)	82.9 ms

That is small next to a JPEG or AVIF encode of the same file. If you also count see-through pixels, the extractChannel pass decodes again; skip it when isOpaque is already true.

Where this fits in an upload pipeline

Run the check right after you sniff the format and before you pick an output. Opaque PNG photos and screenshots go to JPEG, WebP or AVIF. Files with real transparency stay PNG, or go to WebP or AVIF, which both keep alpha. The same rule decides when our PNG to JPG converter is the right tool and when a transparent logo should stay a PNG.

How I measured

Machine: Apple M1 Pro (8 cores), macOS, 2026-10-17.
Node v24.22.0, sharp 0.35.4, libvips 8.18.6, mozjpeg as bundled with sharp.
Files: photo.png, screenshot.png and transparent.png from the site's reference set (apps/web/assets/reference/), screen2.png from the engine fixtures. photo-rgba.png is photo.png through ensureAlpha(1); photo-one-pixel.png is that file with byte 3 set to 254.
JPEG: flatten({ background: '#ffffff' }).jpeg({ quality: 80, mozjpeg: true }).
Timings: performance.now() around stats(), median of 5 runs.

What I did not test

16-bit PNGs, palette PNGs that mark transparency with a tRNS chunk, and APNG. The tolerance numbers are an example, not a recommendation.

Tiny image placeholders with sharp: bytes for 8 to 32 px LQIPs

Sahadat Husain — Wed, 04 Nov 2026 14:00:00 +0000

A blurred placeholder only needs to be 16 pixels wide, and as WebP it costs about 100 bytes. With sharp, a 16 × 11 WebP of a 1920 × 1280 photo came out at 108 bytes, or 167 characters as a data URI you can inline in your HTML. At 32 px it is 248 bytes. Format matters more than width at this size: the same 16 px placeholder is 330 bytes as JPEG and 600 bytes as PNG.

How do you make one?

Resize to a tiny width, encode, and base64 the buffer:

import sharp from 'sharp';

const src = 'jpg-sample-photo-original.jpg';
console.log('width  format  bytes  base64 chars  data URI chars');
for (const w of [8, 16, 24, 32]) {
  for (const [fmt, opts] of [['webp', { quality: 50 }], ['jpeg', { quality: 50 }], ['png', { compressionLevel: 9 }], ['avif', { quality: 50 }]]) {
    const buf = await sharp(src).resize(w).toFormat(fmt, opts).toBuffer();
    const b64 = buf.toString('base64');
    const uri = `data:image/${fmt};base64,${b64}`;
    console.log(String(w).padEnd(6), fmt.padEnd(7), String(buf.length).padEnd(6), String(b64.length).padEnd(13), uri.length);
  }
}

resize(w) keeps the aspect ratio, so the four sizes came out at 8 × 5, 16 × 11, 24 × 16 and 32 × 21.

How many bytes does each size cost?

What the script printed:

width  format  bytes  base64 chars  data URI chars
8      webp    78     104           127
8      jpeg    292    392           415
8      png     211    284           306
8      avif    300    400           423
16     webp    108    144           167
16     jpeg    330    440           463
16     png     600    800           822
16     avif    344    460           483
24     webp    188    252           275
24     jpeg    375    500           523
24     png     1162   1552          1574
24     avif    360    480           503
32     webp    248    332           355
32     jpeg    457    612           635
32     png     1928   2572          2594
32     avif    446    596           619

The same numbers as a data URI, which is what lands in your HTML:

Width	WebP	JPEG	AVIF	PNG
8 px	127	415	423	306
16 px	167	463	483	822
24 px	275	523	503	1,574
32 px	355	635	619	2,594

Why does WebP win at this size?

Container overhead. A JPEG carries quantization and Huffman tables before the first pixel; at 8 px that header is much of the 292 bytes. AVIF wraps its data in an ISO box structure that costs a few hundred bytes too. A lossy WebP's RIFF header is 20 bytes or so, and the rest is picture.

PNG goes the other way. It is lossless, so every one of the 32 × 21 pixels is stored exactly, and the photo's noise makes that expensive: 1,928 bytes at 32 px.

Note: base64 grows bytes by a third, and the data:image/webp;base64, prefix adds 23 characters. Compare placeholders by the data URI length if you inline them, not by the file size. A 600-byte PNG is 822 characters in your HTML.

How small can you go before it stops helping?

The placeholders, stretched to 360 × 240 with a blur the way a page shows them:

At 8 px you get the colour and a light patch in the middle, and nothing more. At 16 px the iguana's shape and the branch appear. At 24 and 32 px the shape sharpens a little, for 80 and 140 more bytes than 16 px. For most layouts 16 px is the point where you stop paying for detail nobody waits to see.

What about a single colour?

A flat colour is cheaper still: no bytes beyond your CSS. But pick it carefully. sharp's stats().dominant returned { r: 8, g: 8, b: 8 } for this photo, near black, because the dark background has the most pixels. The iguana is orange.

Two better choices from the same file:

const { channels } = await sharp(src).stats();
console.log(channels.map((c) => Math.round(c.mean)));      // [ 67, 54, 26 ]

const { data } = await sharp(src).resize(1, 1).raw().toBuffer({ resolveWithObject: true });
console.log([...data]);                                     // [ 81, 59, 28 ]

The channel mean and a 1 × 1 resize both give a dark olive brown, which matches the photo's overall tone. Use one of them as a background-color when a 167-character URI is still too much, for example in a long grid of cards.

How do you use it on the page?

Inline the URI as a background on the image box, and let the real image cover it:

<img
  src="iguana-1200.webp"
  width="1920" height="1280"
  loading="lazy"
  alt="An iguana on a branch"
  style="background: url(data:image/webp;base64,UklGRmQAAABXRUJQVlA4IFgAAADwAQCdASoQAAsAAsBMJaACdAEDHZBTWgAA/vkj8Bo1wNbZdUdcxmtM2/Tv4dDTBQ52v/GCf9yAu+CEHeT5yhIgSkX+3CJh5tSaDAboDe9Kb0zaqjfn+VAA) center / cover;">

That is the real 16 px placeholder from the run. The browser scales a tiny bitmap smoothly, which gives you most of the blur for free. Add filter: blur() on a wrapper if you want it softer, not on the <img> itself, or the real image blurs too.

Keep width and height on the image. The placeholder fills a box; the attributes are what reserve it before anything loads. For the rest of an image's journey to the page, the image optimization guide covers formats, sizing and lazy loading.

How I measured

Apple Silicon Mac (M1 Pro), 2026-10-17, Node 24.22.0, sharp 0.35.4 with libvips 8.18.6.
Source: jpg-sample-photo-original.jpg from the Blinkimg site, 1920 × 1280, 576,828 bytes, a real camera photo.
WebP, JPEG and AVIF at quality 50; PNG at compressionLevel: 9. Defaults otherwise.
The figure scales each placeholder to 360 × 240 with resize(..., { fit: 'fill' }).blur(6) in sharp; a browser's scaling will look a little different.

What I did not test

I did not compare BlurHash or ThumbHash strings, which need a client-side decoder. One photo with a dark background is not every photo.

An AVIF quality ladder in sharp: q30 to q80, bytes and time

Sahadat Husain — Tue, 03 Nov 2026 14:00:00 +0000

In sharp, AVIF bytes grow fast with quality: a 1920 × 1280 photo of 576.8 KB came out at 54.4 KB at q30, 119.0 KB at q50 (sharp's default) and 332.7 KB at q80. That is 6.1 times the bytes from the bottom of the ladder to the top. Encode time stayed between 0.6 and 1.2 seconds on an M1 Pro at the default effort.

What does each quality setting cost?

The script, run from a folder with sharp installed:

import sharp from 'sharp';
import { readFile } from 'node:fs/promises';

const input = await readFile('jpg-sample-photo-original.jpg');
const median = (a) => [...a].sort((x, y) => x - y)[Math.floor(a.length / 2)];

await sharp(input).avif({ quality: 50 }).toBuffer(); // warm-up
console.log('quality  bytes    KB      ms(median of 5)');
for (const q of [30, 40, 50, 60, 70, 80]) {
  const times = []; let bytes = 0;
  for (let i = 0; i < 5; i++) {
    const t = performance.now();
    const out = await sharp(input).avif({ quality: q }).toBuffer();
    times.push(performance.now() - t); bytes = out.length;
  }
  console.log(`q${q}`.padEnd(9), String(bytes).padEnd(8), (bytes / 1000).toFixed(1).padEnd(7), median(times).toFixed(0));
}

What it printed:

quality  bytes    KB      ms(median of 5)
q30       54361    54.4    980
q40       80292    80.3    624
q50       118975   119.0   711
q60       172876   172.9   779
q70       245756   245.8   971
q80       332733   332.7   1215

Quality	Bytes	KB	vs the JPEG	Encode, median of 5
q30	54,361	54.4	9.4%	980 ms
q40	80,292	80.3	13.9%	624 ms
q50	118,975	119.0	20.6%	711 ms
q60	172,876	172.9	30.0%	779 ms
q70	245,756	245.8	42.6%	971 ms
q80	332,733	332.7	57.7%	1,215 ms

Why do the bytes curve upward?

Each step of 10 adds more than the one before: 25.9 KB, then 38.7, 53.9, 72.9 and 87.0 KB. The top step, q70 to q80, costs more bytes than all of q30 holds.

The encoder spends those bytes on detail you see less and less. At low quality it drops fine texture and noise first. At high quality it keeps them, and noise is expensive to store.

What do the steps look like?

The same 360 × 360 crop of the iguana's back, decoded from three of the encodes and enlarged 1.33 times with nearest-neighbour so pixels stay visible:

At q30 the small scales smear together and the spines lose their edges. At q50 the scale pattern is back. Side by side, q50 and q80 are hard to tell apart, and q80 costs 2.8 times the bytes.

Note: AVIF quality numbers do not line up with JPEG quality numbers. q50 in AVIF is not "half" of anything, and a JPEG q80 habit carried over to AVIF buys a much larger file than you need. Pick an AVIF setting by looking at your own photos, or by a metric target, never by the number you used for JPEG.

Why was q30 slower than q40?

I expected time to rise with quality. It mostly did, from 624 ms at q40 to 1,215 ms at q80. But q30 took 980 ms, slower than q40, 50 and 60. It did so in a first run too (1,045 ms against 698 ms at q40), so it is not a one-off.

I have no confirmed cause. A guess: at very low quality the encoder tries more ways to fit the budget. Treat it as a reason to time your own settings, not as a rule.

What I can say: sharp's output docs give quality a default of 50 and effort a default of 4, on a scale of 0 to 9. Effort is the knob for time; quality is the knob for bytes. I held effort at 4 for this whole ladder.

Which quality should you ship?

It depends on what the image does on the page.

Hero and product photos at q50 to q60. Here that is 119.0 to 172.9 KB, against 576.8 KB for the JPEG.
Thumbnails and cards at q40. Small display sizes hide the smoothing; 80.3 KB here at full size, far less once resized.
q70 and up for photography sites where the detail is the product, and only after you compare.

For a reference point from a different encoder: Blinkimg's engine, which picks a quality from the content, wrote this same JPEG as a 123.9 KB AVIF. That sits just above sharp's q50. If you would rather not pick a number, the JPG to AVIF converter makes that call per image.

And if you are deciding whether AVIF is worth it at all, what AVIF is and when it loses covers the cases where WebP or JPEG come out smaller.

How I measured

Apple Silicon Mac (M1 Pro), 2026-10-17, Node 24.22.0, sharp 0.35.4, libvips 8.18.6, libaom 3.15.0.
Source: jpg-sample-photo-original.jpg from the Blinkimg site, 1920 × 1280, 576,828 bytes, a real camera photo.
Times: median of 5 encodes after one warm-up. Other jobs were using the CPU, so compare the times with each other, not with your server.
The 123.9 KB figure comes from Blinkimg's measured engine output (measured.ts, compressJpg.asAvif).

What I did not test

One photo is not every photo; a screenshot or a noisy night shot will curve differently. I did not score quality with SSIM or Butteraugli, and I did not vary effort.

The sizes attribute: how the browser picks a srcset candidate

Sahadat Husain — Mon, 02 Nov 2026 14:00:00 +0000

The browser picks a srcset candidate by dividing each width descriptor by the slot width from sizes, then taking a candidate whose density covers the screen's device pixel ratio. Leave sizes out and the slot is the full viewport width. On a 1280 px laptop with a 720 px column, that one omission took the download from 58.4 KB to 170.3 KB in my test.

What does the browser compute?

Three numbers per image:

The slot width. The browser walks the sizes list and takes the first media condition that matches. No match falls to the last entry. No sizes at all means 100vw, which MDN's img reference states as the default.
Each candidate's density. A 1600w candidate in a 720 px slot has a density of 1600 / 720 = 2.22.
The density it needs. That is the device pixel ratio: 1 on most laptops, 2 or 3 on phones.

The browser then picks a candidate with enough density. The spec leaves the final choice to the browser. MDN says the user agent selects any of the available sources at its discretion, so a browser may pick a smaller file on a slow connection or reuse a larger one it has cached. The rule below is the common case, not a promise.

Can you reproduce it in code?

Yes. Here is the pick for one sizes value, plus the real bytes of each candidate, made with sharp from a 1920 × 1280 JPEG:

import sharp from 'sharp';
const src = 'jpg-sample-photo-original.jpg';
const widths = [480, 800, 1200, 1600, 1920];
const bytes = {};
for (const w of widths) bytes[w] = (await sharp(src).resize(w).webp({ quality: 75 }).toBuffer()).length;
console.log('candidate bytes', bytes);

// sizes="(min-width: 1024px) 720px, (min-width: 640px) 50vw, 100vw"
const slot = (vw) => (vw >= 1024 ? 720 : vw >= 640 ? vw * 0.5 : vw);
// Pick the smallest candidate whose density (w / slot) covers the device pixel ratio.
const pick = (slotPx, dpr) => widths.find((w) => w / slotPx >= dpr) ?? widths.at(-1);

for (const [vw, dpr] of [[375, 2], [375, 3], [414, 3], [768, 2], [1280, 1], [1440, 2], [1920, 1]]) {
  const s = slot(vw), p = pick(s, dpr), p100 = pick(vw, dpr);
  console.log(vw, dpr, s, s * dpr, p, bytes[p], '|', p100, bytes[p100]);
}

The output:

candidate bytes { '480': 22818, '800': 58440, '1200': 112234, '1600': 170268, '1920': 218908 }
viewport  dpr  slot  needed  picked  bytes   | no sizes (100vw): picked  bytes
375       2    375   750     800     58440   | 800    58440
375       3    375   1125    1200    112234  | 1200   112234
414       3    414   1242    1600    170268  | 1600   170268
768       2    384   768     800     58440   | 1600   170268
1280      1    720   720     800     58440   | 1600   170268
1440      2    720   1440    1600    170268  | 1920   218908
1920      1    720   720     800     58440   | 1920   218908

Where does a missing sizes cost you?

On phones, nowhere. The image fills the screen, so 100vw is the truth, and both columns match.

On anything wider, the image sits in a column, and 100vw overstates the slot. These are the rows that changed:

Viewport	DPR	With `sizes`	Without	Extra bytes
768 px	2	58.4 KB	170.3 KB	111.8 KB
1280 px	1	58.4 KB	170.3 KB	111.8 KB
1440 px	2	170.3 KB	218.9 KB	48.6 KB
1920 px	1	58.4 KB	218.9 KB	160.5 KB

The 1920 px desktop is the worst. Its slot is 720 px, but without sizes the browser thinks it is 1920 px and fetches the largest file: 3.7 times the bytes it needed.

Note: sizes describes the layout, not the file. It must match your CSS at each breakpoint. If your column is 720 px but sizes says 50vw, a 1920 px screen computes a 960 px slot and fetches 1200w. Nothing errors. You just pay for it.

Why did the 414 px phone fetch 1600w?

A 414 px phone at 3x needs 1242 device pixels. The 1200w candidate falls 42 short, so the next one up wins: 1600w, 170.3 KB. That is a gap in the ladder, not in sizes.

The fix is a candidate near the common needs. The three phones in the table need 750, 1125 and 1242 device pixels. A 1280w step would catch the 414 px phone with 38 pixels to spare. Check the needs from your own analytics, not a stock list.

How do you write sizes for a real layout?

Read the slot from your CSS at each breakpoint, widest first:

<img
  src="photo-800.webp"
  srcset="photo-480.webp 480w, photo-800.webp 800w, photo-1200.webp 1200w,
          photo-1600.webp 1600w, photo-1920.webp 1920w"
  sizes="(min-width: 1024px) 720px, (min-width: 640px) 50vw, 100vw"
  width="1920" height="1280"
  alt="An iguana on a branch">

Three habits help:

Use px for fixed columns and vw for fluid ones. calc() works too: calc(100vw - 32px) for a full-bleed image with 16 px gutters.
Order matters. The browser takes the first match, so put the widest condition first.
Keep width and height. They reserve the box before the file arrives; sizes does not.

sizes="auto" is newer. It lets the browser use the laid-out width of a lazy-loaded image. MDN lists auto as a valid value; check support on caniuse before you rely on it, and keep an explicit fallback after it.

How do you check what was picked?

In Chrome DevTools, select the <img> and read currentSrc in the console:

$0.currentSrc

Resize the window and reload; a browser that already holds a larger candidate may keep it. To see the bytes on a live page, the page image analyzer lists each image's weight.

How I measured

Apple Silicon Mac (M1 Pro), 2026-10-17, Node 24.22.0, sharp 0.35.4 with libvips 8.18.6.
Source: jpg-sample-photo-original.jpg from the Blinkimg site, 1920 × 1280, 576,828 bytes. Candidates are WebP q75 at five widths.
The pick function is my model of the common rule, not browser code.

What I did not test

I did not record which candidate Chrome, Safari or Firefox fetched at each size. Cache reuse and data-saver settings can change the pick.

Why image encodes belong in a queue worker, with BullMQ

Sahadat Husain — Sun, 01 Nov 2026 14:00:00 +0000

Image encodes belong in a separate worker process because they take over threads your API needs for other work. I ran 16 AVIF encodes inside a Fastify API. A health check stayed fast, but a sign-in request that hashes a password waited 11,028.0 ms in the slowest case. With the same encodes handed to a BullMQ worker, the slowest sign-in took 53.9 ms. The upload request itself answered in 12 ms instead of 8,985 ms.

Isn't sharp already async?

Yes, and that is the trap. sharp does not block the event loop. My /health route answered with a median of 1.5 ms during all 16 encodes. If you only watch event-loop lag, everything looks fine.

The cost lands somewhere else. sharp's tasks wait for a thread from libuv, and the sharp utility docs describe that queue. libuv's pool also runs Node's fs calls, dns.lookup(), zlib and async crypto such as crypto.pbkdf2(). The Node.js docs put its default size at 4 and warn that one slow user of the pool slows every other API that shares it.

A password check is one of those APIs. So is reading a file or resolving a hostname.

What did I run?

One Fastify API with four routes. /inline encodes in the request. /queued adds a BullMQ job and answers 202. /login runs pbkdf2 with 100,000 iterations, like a sign-in. /health returns a constant.

import Fastify from 'fastify';
import sharp from 'sharp';
import { Queue } from 'bullmq';
import { readFile } from 'node:fs/promises';
import { pbkdf2 } from 'node:crypto';
import { promisify } from 'node:util';

const connection = { host: '127.0.0.1', port: Number(process.env.REDIS_PORT) };
const queue = new Queue('encode', { connection });
const photo = await readFile('photo.jpg');
const app = Fastify();

app.get('/health', async () => ({ ok: true }));

// A sign-in check: pbkdf2 runs on the libuv thread pool, the same pool sharp uses
app.get('/login', async () => {
  await promisify(pbkdf2)('password', 'salt', 100_000, 32, 'sha256');
  return { ok: true };
});

// A: encode inside the request
app.post('/inline', async () => {
  const out = await sharp(photo).avif({ quality: 50 }).toBuffer();
  return { bytes: out.length };
});

// B: hand the encode to a worker, answer at once
app.post('/queued', async (req, reply) => {
  const job = await queue.add('avif', { path: 'photo.jpg', quality: 50 }, { removeOnComplete: 1000 });
  return reply.code(202).send({ jobId: job.id });
});

await app.listen({ port: 4317 });

The worker is its own Node process:

import { Worker } from 'bullmq';
import sharp from 'sharp';

const connection = { host: '127.0.0.1', port: Number(process.env.REDIS_PORT) };
sharp.concurrency(1); // one libvips thread per job; the worker's concurrency sets the parallelism

new Worker('encode', async (job) => {
  const out = await sharp(job.data.path).avif({ quality: job.data.quality }).toBuffer();
  return { bytes: out.length };
}, { connection, concurrency: 2 });

The benchmark fires 16 POSTs at once and probes /login or /health every 20 ms until they finish. Each scenario ran 5 times. The photo is a 1920 × 1280 JPEG of 576,828 bytes; one AVIF q50 encode of it is 118,975 bytes.

What happened to the sign-in?

One of the five runs, as it printed:

idle login   | probe: median 18.2 ms, p95 52.1 ms, worst 52.1 ms, 20 probes
inline login | POST answered: median 10036 ms, slowest 14105 ms | probe: median 21.6 ms, p95 13572.8 ms, worst 13572.8 ms, 11 probes
queued login | POST answered: median 31 ms, slowest 36 ms | probe: median 68.9 ms, p95 68.9 ms, worst 68.9 ms, 1 probes

Across the 5 runs:

Measure	Idle	16 encodes inline	16 encodes queued
Sign-in, median of the run medians	16.3 ms	18.8 ms	n/a
Sign-in, median of the run worsts	52.1 ms	11,028.0 ms	53.9 ms
Upload POST, median of the run medians	n/a	8,985 ms	12 ms
`/health`, median of the run worsts	34.2 ms	53.7 ms	36.5 ms

The worst case is the one that matters. A sign-in that arrives just after a burst of uploads waits for the pool to drain. Eleven seconds is longer than many login forms and proxies wait.

Note: Raising UV_THREADPOOL_SIZE does not fix this. It moves the line: more threads for the encodes, and the CPU is still busy. And Node's docs say setting it from inside the process "is not guaranteed to work", because the pool is created at startup.

Why did the queued uploads answer in 12 ms?

/queued does one Redis write and returns a job id. The client polls, or you push the result over SSE or a webhook. The encode still takes its time, but no request holds a socket open for it.

The cost moves to the worker. With concurrency: 2 and one libvips thread per job, the worker drained 16 queued encodes in a median of 23.7 s over 4 runs. Inline, the API used every core and finished the last one in 9.5 to 16.2 s. You trade raw finish time for an API that stays responsive, and you scale the worker on its own.

Is BullMQ's concurrency enough for CPU work?

Not alone. The BullMQ concurrency guide says the concurrency option helps asynchronous work, and points CPU-intensive jobs to sandboxed processors. It also recommends several workers as the main way to scale.

sharp is a special case. Its encode runs in native threads, not on the JavaScript thread, so concurrency does give parallel encodes inside one worker. What you must decide is the product of the two: worker concurrency × sharp.concurrency() threads, plus the extra threads libaom starts for AVIF, which sharp's docs say its setting does not control. Keep that product near your core count.

What does the rest of the setup need?

Timeouts per job. sharp().timeout({ seconds }) stops one bad file from holding a worker.
Retries with backoff for transient storage errors, not for files that fail to decode.
Results in object storage, keyed by job id, so any API instance can serve the status.
A dead-letter check. A job that fails three times needs a human, not a fourth try.

That is the shape Blinkimg runs: the image compressor posts a job, a worker encodes, and the page reads the result by id.

How I measured

Apple Silicon Mac (M1 Pro, 8 cores), 2026-10-17. Other processes were running; the load average was high, so treat the times as relative.
Node 24.22.0, Fastify 5.12.5, BullMQ 5.80.9, sharp 0.35.4 with libvips 8.18.6, Redis from redis-memory-server 0.17.1.
Each scenario ran 5 times; the table gives medians across runs. The drain time excludes the first run, which also drained the backlog the queued benchmarks left.
Photo: jpg-sample-photo-original.jpg, 1920 × 1280, 576,828 bytes.

What I did not test

I did not test a Linux server, a sandboxed BullMQ processor, or more than one worker process. I did not try fs or dns.lookup() as the probe; pbkdf2 stands in for them.

An image upload endpoint in Fastify: five checks before decode

Sahadat Husain — Sat, 31 Oct 2026 14:00:00 +0000

An image upload route should refuse bad files before it decodes a single pixel. Five checks do it in Fastify: cap the bytes, allow one file, sniff the magic bytes, read the header's dimensions, and only then decode with a pixel cap and a time cap. On my machine the route refused a 400-megapixel PNG bomb in 1.7 ms. The same route took 130.4 ms to decode and re-encode a normal 1920 × 1280 photo.

Why check before decode?

Decoding is where an image costs you. A compressed file says nothing about its decoded size. I made a 20000 × 20000 PNG of one flat colour with sharp. It is 1,211,460 bytes on disk. Decoded as RGB, it is 400 million pixels, 1.2 GB of raw samples.

Every check below runs on bytes you already hold, or on the file header. None of them allocates the pixel buffer.

What does the endpoint look like?

The whole route, runnable with fastify, @fastify/multipart and sharp:

import Fastify from 'fastify';
import multipart from '@fastify/multipart';
import sharp from 'sharp';

const MAX_BYTES = 30_000_000;   // check 1: bytes on the wire
const MAX_PIXELS = 100_000_000; // check 4: pixels the header declares

const app = Fastify();
await app.register(multipart, {
  limits: { fileSize: MAX_BYTES, files: 1, fields: 0 }, // check 2: one file, nothing else
});

function sniff(buf) {
  if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) return 'jpeg';
  if (buf.length >= 8 && buf.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) return 'png';
  if (buf.length >= 12 && buf.toString('latin1', 0, 4) === 'RIFF' && buf.toString('latin1', 8, 12) === 'WEBP') return 'webp';
  if (buf.length >= 12 && buf.toString('latin1', 4, 8) === 'ftyp') {
    const brand = buf.toString('latin1', 8, 12);
    if (brand === 'avif' || brand === 'avis') return 'avif';
    if (['heic', 'heix', 'mif1', 'msf1'].includes(brand)) return 'heic';
  }
  return null;
}

app.post('/upload', async (req, reply) => {
  const file = await req.file();
  if (!file) return reply.code(400).send({ error: 'no_file' });
  const buf = await file.toBuffer(); // throws 413 past fileSize

  const format = sniff(buf); // check 3: magic bytes, not the name or Content-Type
  if (!format) return reply.code(415).send({ error: 'unsupported_format', claimed: file.mimetype });

  const meta = await sharp(buf, { limitInputPixels: false }).metadata(); // check 4: header only
  const pixels = (meta.width ?? 0) * (meta.height ?? 0);
  if (pixels > MAX_PIXELS) {
    return reply.code(422).send({ error: 'too_many_pixels', width: meta.width, height: meta.height });
  }

  // check 5: the decode itself, with a pixel cap and a time cap as the backstop
  const out = await sharp(buf, { limitInputPixels: MAX_PIXELS })
    .timeout({ seconds: 10 })
    .resize({ width: 1600, withoutEnlargement: true })
    .webp({ quality: 75 })
    .toBuffer();
  return { format, claimed: file.mimetype, width: meta.width, height: meta.height, in: buf.length, out: out.length };
});

app.setErrorHandler((err, req, reply) => {
  reply.code(err.statusCode ?? 500).send({ error: err.code ?? 'error', message: err.message });
});

await app.listen({ port: 3999 });

What did each test file get back?

I sent six files, each with a .jpg name and type=image/jpeg, the way a careless or hostile client would:

for f in photo.jpg graphic.jpg notes.jpg wide.png bomb.png big.jpg; do
  curl -s -F "file=@$f;type=image/jpeg" http://127.0.0.1:3999/upload; echo
done

{"format":"jpeg","claimed":"image/jpeg","width":1920,"height":1280,"in":576828,"out":170268}
{"format":"png","claimed":"image/jpeg","width":640,"height":480,"in":7395,"out":1202}
{"error":"unsupported_format","claimed":"image/jpeg"}
{"error":"too_many_pixels","width":12500,"height":12000}
{"error":"too_many_pixels","width":20000,"height":20000}
{"error":"FST_REQ_FILE_TOO_LARGE","message":"request file too large"}

File	What it is	Status	Median time
photo.jpg	1920 × 1280 JPEG, 576,828 B	200	130.4 ms
graphic.jpg	a 640 × 480 PNG with a `.jpg` name	200	11.6 ms
notes.jpg	40 bytes of text	415	0.8 ms
wide.png	12500 × 12000 flat PNG, 462,998 B	422	1.3 ms
bomb.png	20000 × 20000 flat PNG, 1,211,460 B	422	1.7 ms
big.jpg	31,000,000 random bytes	413	15.6 ms

The PNG named .jpg went through, and that is correct. The sniffer said png, so the route treats it as a PNG. The claimed field shows what the client said; you log it, you never route on it.

Why read the header with limitInputPixels: false?

This surprised me. My first version called sharp(buf).metadata() with no options. The bomb came back as a 500 with Input image exceeds pixel limit. sharp applies its default limitInputPixels, 268,402,689 pixels, even to a metadata read, and the constructor docs list that default.

That default saved me from the bomb, but in the wrong place. The client got a 500, not a clear 422, and the error looked like a crash in the logs. Worse, the 150-megapixel wide.png sits under the default. Without my own check, it would have been decoded.

So the header read turns the default off and the route applies its own cap. metadata() reads the header only, so turning the limit off there allocates nothing large. The decode in check 5 then sets limitInputPixels again, as a second line in case a header lies.

Note: limitInputPixels counts width × height from the header. It does not cap bytes, and it does not cap time. A small, deeply nested or slow-to-decode file still needs the timeout() in check 5. The output docs define it as a timeout for processing, in seconds, off by default.

What does skipping check 4 cost?

I decoded wide.png without the cap: resize to 1600 px wide, WebP q75. Over 5 runs the median was 320 ms and the median peak resident memory was 227,164,160 bytes, about 227.2 MB, for one request. The 422 cost 1.3 ms.

A flat PNG is the kind case: libvips streams it and the output is tiny. A photo at that size takes longer. Ten such uploads at once would hold gigabytes on a small server.

Where does the byte cap belong?

@fastify/multipart stops reading at limits.fileSize and toBuffer() throws. In my run the error carried statusCode 413 and code FST_REQ_FILE_TOO_LARGE, which the error handler passes through. The plugin's README documents fileSize, files and fields as the limits.

Put the cap in your reverse proxy too. The plugin protects the process; the proxy protects the socket.

What would I add for production?

Run the decode off the API process, in a queue worker. A 130 ms encode is fine once; a hundred at once is not.
Rate limit per key and per IP before any of this runs.
Stream to object storage instead of toBuffer() when files are large, and sniff the first chunk.

For the bigger picture on very large images, I wrote up what a 400-megapixel JPEG does to a small server.

How I measured

Apple Silicon Mac (M1 Pro), 2026-10-17.
Node 24.22.0, Fastify 5.12.5, @fastify/multipart 10.1.4, sharp 0.35.4 with libvips 8.18.6.
Each time is the median of 5 curl runs (%{time_total}) against the local server.
photo.jpg is the site's 1920 × 1280 sample (jpg-sample-photo-original.jpg), graphic.jpg is the engine's graphic.png fixture renamed. The PNGs and the random file were made by script.
Memory: /usr/bin/time -l, maximum resident set size, median of 5.

What I did not test

I did not test a real malformed file that hangs a decoder, so the 10-second timeout never fired. I did not test HEIC or AVIF headers through check 4.

Compress images from your AI editor with an MCP server

Sahadat Husain — Fri, 30 Oct 2026 14:00:00 +0000

You can compress and convert images from Claude Code, Cursor, VS Code or Codex by adding a remote MCP server to the editor. Then you ask in plain words, and the agent calls a tool. I asked for "this photo as an AVIF under 200 KB, 1600 px wide". One convert_image call took a 9,804,300-byte JPEG to a 196,540-byte AVIF. This article shows the setup, what goes over the wire, and the mistakes that stop a connection.

What does an image MCP server do for you?

An MCP server gives your AI assistant tools it can call. A remote image server runs the encode on its own machines. Your editor sends JSON-RPC; the server fetches or receives the file, encodes it and hands back a download link.

The server here is the one I build: Blinkimg's, at https://api.blinkimg.com/mcp. It speaks Streamable HTTP, the transport in the MCP spec where every client message is a POST to one endpoint. It registers six tools:

Tool	What it does	Credits
`upload_image`	Returns a one-time upload link (15 minutes) and a ready `curl` command for a local file	Free
`compress_image`	Makes an image smaller from an `image_url` or an `upload_id`	1; 2 when `target_format` changes the format
`convert_image`	Converts to JPEG, PNG, WebP or AVIF; HEIC, JPEG, PNG, WebP and AVIF go in	2
`get_job`	Reads a job: status, sizes, download link	Free
`analyze_page`	Scans a public page for image weight	Free; 25 scans a day on Free
`get_quota`	Reads your plan, credits left and limits	Free

Every account gets 500 free credits a month. The MCP server page lists the setup for each client.

How do you add it to Claude Code?

One command. Leave the header out and Claude Code signs you in with OAuth in the browser:

claude mcp add --transport http blinkimg https://api.blinkimg.com/mcp

To use an API key instead, keep it in an environment variable and put a .mcp.json in the project root:

{
  "mcpServers": {
    "blinkimg": {
      "type": "http",
      "url": "https://api.blinkimg.com/mcp",
      "headers": {
        "Authorization": "Bearer ${BLINKIMG_API_KEY}"
      }
    }
  }
}

Cursor reads the same shape from ~/.cursor/mcp.json, with ${env:BLINKIMG_API_KEY} for the variable. The Claude Code MCP docs and the Cursor MCP docs cover the scopes.

Note: A configured Authorization header turns off the OAuth sign-in in Claude Code. If the editor never offers to sign you in, look for a header you forgot. And if Claude Code reports a missing environment variable, BLINKIMG_API_KEY was not set when the editor started. Set it, then restart the editor.

What actually goes over the wire?

Before you trust a tool in your editor, it helps to see the protocol by hand. Here is a tools/list request with no key:

curl -s -i -X POST https://api.blinkimg.com/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The accept header lists both types because the spec requires it. The server answered (headers trimmed):

HTTP/2 401
content-type: application/json; charset=utf-8
www-authenticate: Bearer realm="blinkimg", resource_metadata="https://api.blinkimg.com/.well-known/oauth-protected-resource/mcp", scope="mcp"

{"error":{"code":"UNAUTHORIZED","message":"The MCP endpoint takes an API key. Send Authorization: Bearer bk_... (or X-API-Key: bk_...). How to get one: https://blinkimg.com/auth.md","requestId":"5411e245-b480-4d8f-993a-bc7bb28b8f31"}}

The resource_metadata address is how an OAuth-capable client finds where to sign in:

curl -s https://api.blinkimg.com/.well-known/oauth-protected-resource/mcp

{"resource":"https://api.blinkimg.com/mcp","authorization_servers":["https://api.blinkimg.com"],"scopes_supported":["mcp"],"bearer_methods_supported":["header"],"resource_name":"Blinkimg","resource_documentation":"https://blinkimg.com/mcp"}

That pair, a 401 with WWW-Authenticate and a metadata document, is all a client needs to start the sign-in. When Claude Code shows "Needs authentication" in claude mcp list, this is the exchange it saw.

What does one tool call return?

I asked the agent to convert the site's 4964 × 2782 sample photo to AVIF, under 200 KB and no wider than 1600 px. The agent made one call:

{
  "name": "convert_image",
  "arguments": {
    "image_url": "https://blinkimg.com/images/index/image-compressor-sample-camera-photo.jpeg",
    "target_format": "avif",
    "target_bytes": 200000,
    "max_width": 1600
  }
}

The result, with the signed URLs cut:

{
  "status": "succeeded",
  "format": "avif",
  "input_format": "jpeg",
  "input_bytes": 9804300,
  "output_bytes": 196540,
  "saved_percent": 98,
  "width": 1600,
  "height": 897,
  "returned_original": false,
  "download_command": "curl -sS --fail -o 'image-compressor-sample-camera-photo.avif' '...'",
  "next": "Download the result from download_url before ..."
}

	Bytes	KB	Size
Source JPEG	9,804,300	9,804.3	4964 × 2782
AVIF result	196,540	196.5	1600 × 897

Three things in that result matter for an agent. output_bytes stays under target_bytes: the cap is a ceiling, and the engine lowers quality, then dimensions, until the file fits. download_command is a ready curl -o line, so an agent in a terminal saves the file without parsing anything. And next tells the agent the deadline in words: the link lasts an hour, the file a day.

The same cap on the site's reference photo, a 1920 × 1280 JPEG of 576.8 KB, lands at 99.7 KB when target_bytes is 100,000.

How do local files get in?

A hosted server cannot read your disk. So upload_image returns a one-time upload link and a curl command. An agent that can run commands (Claude Code, Cursor, Codex) runs the command, the file goes straight to storage, and compress_image takes the upload_id. A chat app without a shell cannot do this step; give it a public image address instead.

A prompt like "Convert every PNG in ./public to AVIF under 100 KB" turns into one upload_image and one convert_image per file.

Which mistakes stop the connection?

Most failures are config, not the server:

Gemini CLI: use httpUrl, not url. In Gemini CLI, url means the older SSE transport.
VS Code: in .vscode/mcp.json the top-level key is servers, not mcpServers, with "type": "http".
Cline: add "type": "streamableHttp", or it falls back to legacy SSE.
Codex: bearer_token_env_var takes the variable's name, BLINKIMG_API_KEY, not the key itself.
An app opened from the Mac Dock: it does not see variables you export in ~/.zshrc, so the key is empty and you get a 401.

One limit you may meet in a batch: one key runs 2 image_url downloads at once. A third call waits up to 20 seconds, then asks you to retry. A tool waits up to 25 seconds for the engine; a slower job comes back as a job_id for get_job.

If you would rather call the same engine from your own code, the developer API takes the same options over plain HTTP.

How I measured

Machine: Apple Silicon Mac (M1 Pro), 2026-10-17.
The 401 and the metadata document: curl against the live server, output pasted with Cloudflare and date headers removed.
The tool call: Claude Code's MCP client calling convert_image on the live server with my account. 2 credits spent.
Source: image-compressor-sample-camera-photo.jpeg, 4964 × 2782, 9,804,300 bytes (the content-length the site served).
The 99.7 KB figure comes from the site's measured engine output (measured.ts, sizeTargets.to100kb).
Tool list, credits and limits: read from the server's tool definitions and get_quota on the same day.

What I did not test

I ran one photo through one client. I did not test the OAuth sign-in flow in Cursor, VS Code, Gemini CLI or Codex; their config shapes come from each client's docs.

Serve AVIF or WebP by Accept header, and the Vary header trap

Sahadat Husain — Thu, 29 Oct 2026 14:00:00 +0000

Read the request's Accept header, pick AVIF, then WebP, then JPEG, and always send Vary: Accept with the response. Without Vary, a shared cache stores the first variant it sees and hands it to everyone. In my test, a client that sent Accept: */* got image/avif from the cache.

What do browsers send in Accept for images?

MDN keeps a list of default Accept values. For <img> requests it gives:

Browser	Accept for images
Chrome and Edge 121+	`image/avif,image/webp,image/apng,image/,/*;q=0.8`
Firefox 158+	`image/avif,image/jxl,image/webp,image/png,image/svg+xml,image/;q=0.8,/*;q=0.5`
Safari since macOS Big Sur	`image/webp,image/png,image/svg+xml,image/;q=0.8,video/;q=0.8,/;q=0.5`

Notice Safari. caniuse lists full AVIF support from Safari 16.4, yet the Accept value MDN lists for Safari names WebP and not AVIF. A server that negotiates by Accept sends Safari WebP. That is correct behaviour, just not the smallest file.

What does the server look like?

A plain node:http server with sharp. It encodes three variants of one 1920 px photo at start-up and picks one per request. It only picks a format the client names explicitly; image/* and */* say nothing about AVIF.

import http from 'node:http';
import sharp from 'sharp';

const base = sharp('camera.jpeg').resize({ width: 1920 });
const variants = {
  avif: { type: 'image/avif', body: await base.clone().avif({ quality: 50 }).toBuffer() },
  webp: { type: 'image/webp', body: await base.clone().webp({ quality: 80 }).toBuffer() },
  jpeg: { type: 'image/jpeg', body: await base.clone().jpeg({ quality: 80, mozjpeg: true }).toBuffer() },
};

export function pick(accept = '') {
  const types = accept.split(',').map((part) => {
    const [type, ...params] = part.trim().split(';');
    const q = params.find((p) => p.trim().startsWith('q='));
    return { type: type.trim(), q: q ? Number(q.split('=')[1]) : 1 };
  });
  const ok = (t) => types.some((x) => x.type === t && x.q > 0);
  if (ok('image/avif')) return 'avif';
  if (ok('image/webp')) return 'webp';
  return 'jpeg';
}

const VARY = process.env.VARY !== 'off';
http.createServer((req, res) => {
  const v = variants[pick(req.headers.accept)];
  const headers = {
    'Content-Type': v.type,
    'Content-Length': v.body.length,
    'Cache-Control': 'public, max-age=31536000',
  };
  if (VARY) headers.Vary = 'Accept';
  res.writeHead(200, headers).end(v.body);
}).listen(process.env.PORT ?? 8080, () => {
  for (const [k, v] of Object.entries(variants)) console.log(k, v.body.length, 'bytes');
});

avif 66799 bytes
webp 106876 bytes
jpeg 153394 bytes

Then curl with each browser's value:

for a in "image/avif,image/webp,image/apng,image/*,*/*;q=0.8" \
         "image/avif,image/jxl,image/webp,image/png,image/svg+xml,image/*;q=0.8,*/*;q=0.5" \
         "image/webp,image/png,image/svg+xml,image/*;q=0.8,video/*;q=0.8,*/*;q=0.5" \
         "*/*"; do
  echo "== $a"
  curl -s -o /dev/null -D - -H "Accept: $a" http://localhost:8080/photo | grep -iE "content-type|content-length|vary"
done

== image/avif,image/webp,image/apng,image/*,*/*;q=0.8
Content-Type: image/avif
Content-Length: 66799
Vary: Accept
== image/avif,image/jxl,image/webp,image/png,image/svg+xml,image/*;q=0.8,*/*;q=0.5
Content-Type: image/avif
Content-Length: 66799
Vary: Accept
== image/webp,image/png,image/svg+xml,image/*;q=0.8,video/*;q=0.8,*/*;q=0.5
Content-Type: image/webp
Content-Length: 106876
Vary: Accept
== */*
Content-Type: image/jpeg
Content-Length: 153394
Vary: Accept

Client	Gets	Bytes	vs JPEG
Chrome, Firefox	AVIF	66,799	-56%
Safari	WebP	106,876	-30%
`/`	JPEG	153,394

What goes wrong without Vary?

A shared cache (a CDN, a reverse proxy) keys responses by URL. RFC 9111, section 4.1 says that when a stored response carries Vary, the cache may reuse it only for requests whose named headers match. No Vary, no check.

I wrote a toy cache that follows that rule and sent four clients through it, in order:

const store = new Map();
async function get(url, accept) {
  for (const [key, entry] of store) {
    if (!key.startsWith(url)) continue;
    if (entry.vary.every((h) => entry.req[h] === accept)) return { ...entry, hit: true };
  }
  const res = await fetch(url, { headers: { accept } });
  const vary = (res.headers.get('vary') ?? '').toLowerCase().split(',').map((s) => s.trim()).filter(Boolean);
  const entry = { type: res.headers.get('content-type'), bytes: (await res.arrayBuffer()).byteLength,
    vary: vary.map(() => 'accept'), req: { accept } };
  store.set(`${url} ${store.size}`, entry);
  return { ...entry, hit: false };
}

--- origin without Vary
chrome      MISS image/avif  66799 bytes
firefox     HIT  image/avif  66799 bytes
safari      HIT  image/avif  66799 bytes
old client  HIT  image/avif  66799 bytes
cache entries: 1
--- origin with Vary: Accept
chrome      MISS image/avif  66799 bytes
firefox     MISS image/avif  66799 bytes
safari      MISS image/webp  106876 bytes
old client  MISS image/jpeg  153394 bytes
cache entries: 4

Without Vary, Chrome warmed the cache with AVIF, and the */* client got AVIF too. In production that client is an old app, a crawler or an email proxy, and it shows a broken image.

Note: Vary: Accept fixes correctness and hurts your hit rate. Caches compare the raw header string, and every browser sends a different one. Chrome and Firefox both want AVIF, yet the cache stored it twice.

How do you keep the hit rate?

Normalise Accept before the cache looks it up, at the edge, to the one token your origin decides on:

const normalize = (a) => (/image\/avif/.test(a) ? 'image/avif' : /image\/webp/.test(a) ? 'image/webp' : 'image/jpeg');

chrome      MISS image/avif  66799 bytes
firefox     HIT  image/avif  66799 bytes
safari      MISS image/webp  106876 bytes
old client  MISS image/jpeg  153394 bytes
cache entries: 3

Three entries for three variants. Firefox now hits Chrome's AVIF. Where you put this depends on your CDN: a request rule, an edge function, or a custom cache key. This regex ignores q=0, so keep the origin's pick() as the source of truth.

Should you negotiate at all?

Negotiation keeps one URL, so it suits an image CDN or an API. If you control the HTML, <picture> with type="image/avif" lets Safari 16.4+ pick AVIF on its own and needs no Vary. For the byte gap between the three formats on more photos, see AVIF vs WebP vs JPEG.

How I measured

Machine: Apple M1 Pro, macOS, 2026-10-17.
Node v24.22.0, sharp 0.35.4, libvips 8.18.6, curl as shipped with macOS.
Source: image-compressor-sample-camera-photo.jpeg from the Blinkimg site (4964 × 2782), resized to 1920 px wide. AVIF quality 50, WebP quality 80, JPEG quality 80 with mozjpeg.
The cache is a short script, not a real CDN. It compares the exact header value, with no normalising of its own.
Accept values are copied from MDN's list on 2026-10-17, not captured from live browsers.

What I did not test

A real CDN's cache behaviour, Accept-CH or Client Hints, and JPEG XL. I did not capture Accept headers from live browsers.

Accepting HEIC uploads in Node: what sharp can and cannot decode

Sahadat Husain — Wed, 28 Oct 2026 14:00:00 +0000

Prebuilt sharp cannot decode iPhone HEIC photos. It reads the header, so metadata() succeeds, and then toBuffer() fails with an error that does not mention HEVC. Route HEVC files to a WASM decoder such as heic-decode, run it in a worker thread, and hand the raw pixels back to sharp.

What does sharp actually support?

The sharp install docs list what the prebuilt binaries support: JPEG, PNG, Ultra HDR, WebP, AVIF, TIFF, GIF and SVG input. HEIC is not on the list. The output docs say HEVC-compressed HEIF needs a globally installed libvips built with libheif, libde265 and x265.

The confusing part is that AVIF and HEIC share a container (HEIF). sharp parses the container either way, so it can tell you a lot about a file it cannot decode.

What happens when you try?

I tried two HEIC files: a 2268 × 4032 iPhone photo (1,956,001 bytes) and an 800 × 600 test photo (199,693 bytes).

import sharp from 'sharp';
import { readFile } from 'node:fs/promises';

for (const f of ['iphone.heic', 'photo.heic']) {
  const buf = await readFile(f);
  const major = buf.toString('latin1', 8, 12); // ftyp major brand
  const m = await sharp(buf).metadata();
  console.log(f, buf.length, 'bytes | brand', major, '| metadata:', m.format, m.compression, `${m.width}x${m.height}`);
  try {
    await sharp(buf).jpeg().toBuffer();
    console.log('  decode OK');
  } catch (e) {
    console.log('  decode FAILED:', e.message.split('\n')[0]);
  }
}

iphone.heic 1956001 bytes | brand heic | metadata: heif hevc 2268x4032
  decode FAILED: source: bad seek to 1956033
photo.heic 199693 bytes | brand heic | metadata: heif hevc 800x600
  decode FAILED: source: bad seek to 199725

metadata() gives you the format, the codec and the size. The decode fails with "bad seek", which reads like a truncated upload. If you log that and move on, your users see "corrupt file" for a perfectly good photo.

Note: Do not branch on format === 'heif'. An AVIF file reports format: 'heif' too, with compression: 'av1', and sharp decodes it fine. Branch on compression === 'hevc'.

How do you decode the HEVC ones?

heic-decode wraps libheif compiled to WebAssembly (via libheif-js), so it needs no system libraries. Its README documents decode.all(), which lists the images in a file before decoding any pixels. That lets you check the size first.

import sharp from 'sharp';
import decode from 'heic-decode';

export async function toSharp(buf) {
  const meta = await sharp(buf).metadata(); // reads the container: works for HEVC too
  if (meta.format === 'heif' && meta.compression === 'hevc') {
    const [first] = await decode.all({ buffer: buf });
    if (first.width * first.height > 50_000_000) throw new Error('too many pixels');
    const { width, height, data } = await first.decode(); // RGBA, 8 bits per channel
    return sharp(Buffer.from(data.buffer, data.byteOffset, data.byteLength), {
      raw: { width, height, channels: 4 },
    });
  }
  return sharp(buf); // JPEG, PNG, WebP, AVIF: sharp decodes these itself
}

const out = await (await toSharp(buf)).resize({ width: 1080 }).jpeg({ quality: 80, mozjpeg: true }).toBuffer();

HEIC 1956001 bytes -> JPEG 296230 bytes, 1080x1920, median of 5: 650 ms
of which resize + encode alone: 195 ms (median of 5); decoded raster 36578304 bytes, 4 channels

It works. The 2 MB HEIC became a 296,230-byte JPEG at 1080 × 1920. But note the decoded raster: 36,578,304 bytes of RGBA for one photo. Ten concurrent uploads hold about 366 MB of pixels before sharp even starts.

Why is the decode a problem for a server?

The WASM decode is synchronous. While it runs, Node cannot serve anything else. I measured the longest event-loop stall during a decode with monitorEventLoopDelay:

import { monitorEventLoopDelay } from 'node:perf_hooks';

const h = monitorEventLoopDelay({ resolution: 10 });
h.enable();
const [first] = await decode.all({ buffer: buf });
await first.decode();
h.disable();
console.log('longest stall', (h.max / 1e6).toFixed(0), 'ms');

decode 483 ms, longest event-loop stall 463 ms (medians of 5)

For 463 ms, every other request on that process waits. A timer cannot rescue you either, because the timer callback cannot run until the decode returns.

How do you keep the event loop free?

Move the decode into a worker_threads worker. The main thread stays free, and worker.terminate() can stop a decode that runs too long.

// decode-worker.mjs
import { parentPort, workerData } from 'node:worker_threads';
import decode from 'heic-decode';

const [first] = await decode.all({ buffer: new Uint8Array(workerData) });
const { width, height, data } = await first.decode();
const bytes = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
parentPort.postMessage({ width, height, data: bytes }, [bytes.buffer]);

// main thread
import { Worker } from 'node:worker_threads';

function decodeInWorker(buf, timeoutMs = 10_000) {
  return new Promise((resolve, reject) => {
    const copy = new Uint8Array(buf).buffer; // a transferable copy
    const worker = new Worker(new URL('./decode-worker.mjs', import.meta.url), {
      workerData: copy,
      transferList: [copy],
    });
    const timer = setTimeout(() => { worker.terminate(); reject(new Error('HEIC decode timed out')); }, timeoutMs);
    worker.once('message', (m) => { clearTimeout(timer); worker.terminate(); resolve(m); });
    worker.once('error', (e) => { clearTimeout(timer); reject(e); });
  });
}

decoded 2268 x 4032
worker decode 574 ms, longest event-loop stall 12 ms (medians of 5)

The decode takes about 90 ms longer, which covers starting the thread and copying the buffers both ways. The stall drops from 463 ms to 12 ms.

Step, 2268 × 4032 HEIC	Median of 5
Whole job on the main thread (decode, resize, mozjpeg)	650 ms
heic-decode alone	483 ms
Longest event-loop stall, main thread	463 ms
sharp resize to 1080 px and encode	195 ms
Decode in a worker thread	574 ms
Longest event-loop stall, worker	12 ms

Checklist for a HEIC upload endpoint

Sniff the bytes, not the extension. The ftyp brand at offset 8 says heic; sharp's compression says hevc or av1.
Send HEVC to the WASM decoder; send everything else to sharp.
Check width × height from decode.all() before you call decode().
Decode in a worker with a hard timeout.
Cap concurrency. This 9.1 MP photo alone decodes to about 37 MB of raw pixels.

If you would rather not run any of this, the Blinkimg image API accepts HEIC as an input and returns a web format. My post What is HEIC? explains the format itself.

How I measured

Machine: Apple M1 Pro, macOS, 2026-10-17.
Node v24.22.0, sharp 0.35.4 (prebuilt, libvips 8.18.6, libheif 1.23.2 in the bundle), heic-decode 2.1.0 with libheif-js 1.19.8.
Files: heic-test.heic (an iPhone 12 Pro photo, 2268 × 4032, 1,956,001 bytes) and photo.heic (800 × 600, 199,693 bytes), both from the Blinkimg engine's test fixtures.
Times are medians of 5 runs. Event-loop stall is monitorEventLoopDelay at 10 ms resolution, its max per run.

What I did not test

Colour: the iPhone file carries a 536-byte Display P3 profile, and the raw pixels from heic-decode arrive without it, so this pipeline treats them as sRGB. I also did not test multi-image HEIC, Live Photos, or a libvips built with libde265.

Progressive vs baseline JPEG with mozjpeg: the byte difference

Sahadat Husain — Tue, 27 Oct 2026 14:00:00 +0000

With mozjpeg, progressive JPEG is 0.2% to 1.2% smaller than baseline for photos 320 px and wider, and 2.3% larger for a 160 px thumbnail. The big saving is mozjpeg itself: 17% at 1920 px. One trap: in sharp, mozjpeg: true writes a progressive file even when you pass progressive: false.

What are the two layouts?

A baseline JPEG stores the image in one pass, top to bottom. A progressive JPEG stores it in several scans, coarse to fine, so the whole frame appears early and sharpens. The pixels and the quality are the same. Only the order of the data, and how well it compresses, change.

The sharp output docs list progressive with a default of false. They describe mozjpeg: true as a shortcut for four settings: trellis quantisation, overshoot deringing, optimised scans and quantisation table 3.

What does sharp write for each option?

I resized one camera photo (4964 × 2782) to six widths, encoded each at quality 80, and read back isProgressive from the output.

import sharp from 'sharp';

const src = 'camera.jpeg';
const modes = {
  'baseline': { progressive: false },
  'progressive': { progressive: true },
  'mozjpeg, baseline': { mozjpeg: true, progressive: false },
  'mozjpeg (default)': { mozjpeg: true },
};
console.log(['width'.padEnd(6), ...Object.keys(modes).map((m) => m.padStart(19))].join(''));
for (const width of [160, 320, 640, 1280, 1920, 4964]) {
  const resized = await sharp(src).resize({ width }).raw().toBuffer({ resolveWithObject: true });
  const row = [String(width).padEnd(6)];
  for (const opts of Object.values(modes)) {
    const out = await sharp(resized.data, { raw: resized.info }).jpeg({ quality: 80, ...opts }).toBuffer();
    const m = await sharp(out).metadata();
    row.push(`${out.length}${m.isProgressive ? ' P' : ' B'}`.padStart(19));
  }
  console.log(row.join(''));
}

width            baseline        progressive  mozjpeg, baseline  mozjpeg (default)
160                3754 B             3959 P             3445 P             3445 P
320               10870 B            10937 P             9589 P             9589 P
640               31824 B            31608 P            27154 P            27154 P
1280              95335 B            95114 P            79671 P            79671 P
1920             185336 B           184585 P           153394 P           153394 P
4964             850624 B           852196 P           668029 P           668029 P

Look at the third column. I asked for mozjpeg: true, progressive: false and got a progressive file, byte for byte the same as plain mozjpeg: true. The optimised-scans setting appears to force progressive mode, and it wins over your flag.

Note: If you need a true baseline file with mozjpeg's other tools, spell the options out and set optimiseScans: false. progressive: false next to mozjpeg: true does nothing.

So what is the real byte difference?

To isolate the scan layout, I kept mozjpeg's tools and switched only the layout:

const moz = { trellisQuantisation: true, overshootDeringing: true, quantisationTable: 3, optimiseScans: false };
const modes = {
  'moz baseline': { ...moz, progressive: false },
  'moz progressive': { ...moz, progressive: true },
  'moz + optimiseScans': { mozjpeg: true },
};
// same loop as above

width           moz baseline       moz progressive   moz + optimiseScans
160                   3369 B                3652 P                3445 P
320                   9611 B                9850 P                9589 P
640                  27289 B               27719 P               27154 P
1280                 80676 B               81629 P               79671 P
1920                155054 B              157288 P              153394 P
4964                675911 B              683920 P              668029 P

Width	Moz baseline	`mozjpeg: true`	Difference
160 px	3,369	3,445	+2.3%
320 px	9,611	9,589	-0.2%
640 px	27,289	27,154	-0.5%
1280 px	80,676	79,671	-1.2%
1920 px	155,054	153,394	-1.1%
4964 px	675,911	668,029	-1.2%

Three things stand out:

A progressive layout with the default scan script is larger than baseline at every width here: 157,288 against 155,054 bytes at 1920 px.
The optimised scans are what make progressive win, by about 1% from 1280 px up.
At 160 px, baseline wins by 76 bytes. A tiny thumbnail has too little data for extra scans to pay off.

What does mozjpeg cost in time?

The 1920 px encode, median of 5 runs, from a raw buffer:

baseline       12.3 ms (median of 5)
progressive    23.1 ms (median of 5)
moz baseline   60.8 ms (median of 5)
mozjpeg: true  103.9 ms (median of 5)

mozjpeg: true is about 8 times slower than a plain baseline encode, for a file 17% smaller (153,394 against 185,336 bytes). That is a good trade for images you encode once and serve many times. It is a poor one inside a request that encodes on every hit.

Which should you pick?

Stored images, 320 px and up: mozjpeg: true. You get progressive rendering and the smallest file.
Thumbnails under about 200 px: spell out the mozjpeg tools with optimiseScans: false, progressive: false. My 160 px test saved 2.3%.
Encodes on the hot path: plain baseline. It is the fastest, and the bytes differ by under 1% from plain progressive.

The JPEG settings on Blinkimg's JPG compressor are measured the same way, and how we measure explains the method behind its published numbers.

How I measured

Machine: Apple M1 Pro, macOS, 2026-10-17.
Node v24.22.0, sharp 0.35.4, libvips 8.18.6, mozjpeg as bundled with sharp.
Source: image-compressor-sample-camera-photo.jpeg from the Blinkimg site, 4964 × 2782. Each width is a sharp resize to raw pixels, then the encode, so every option sees identical input.
All encodes at quality 80, default chroma subsampling (4:2:0). Byte counts are exact and repeat across runs. Times are the median of 5.

What I did not test

Decode time and how fast the first progressive scan paints in a browser. Other quality levels and other photos.

WebP lossless vs near-lossless vs lossy for UI screenshots

Sahadat Husain — Mon, 26 Oct 2026 14:00:00 +0000

Use near-lossless WebP when UI text must look exact, and lossy q90 when bytes matter more. On my test screenshot, nearLossless at level 40 was 17% smaller than lossless WebP, and no channel of any pixel moved by more than 4 out of 255. Lossy q90 was 81% smaller than lossless, but it moved some pixels by 77 and softened the text on a green button.

What are the three WebP modes?

WebP has two different codecs inside one format.

Lossy works in YUV with colour stored at reduced resolution, like a default JPEG. libvips calls its better option smart_subsample, "high quality chroma subsampling".
Lossless is a separate mode that stores exact RGBA values.
Near-lossless is the lossless codec with a preprocessing step first. Google's cwebp docs describe -near_lossless as a level from 0 (maximum preprocessing) to 100 (none, the default), and note that it turns on lossless mode.

In sharp, webp({ nearLossless: true }) switches the mode, and quality sets the level. The libvips webpsave docs suggest Q of 80, 60, 40 or 20 for increasing amounts of preprocessing. The sharp output docs give the defaults: quality 80, effort 4.

How do they compare on a real screenshot?

My test image is a Retina screenshot of Blinkimg's own pricing page, 2880 × 1800, halved to 1440 × 900. It has dark headings, a faint grid in the background, green badges and a green "Get started" button with white text. I encoded it seven ways and timed each one five times.

import sharp from 'sharp';

const src = 'screenshot-1x.png'; // 1440 x 900
const box = { left: 740, top: 624, width: 260, height: 64 }; // the green button
const ref = await sharp(src).removeAlpha().raw().toBuffer();
const refBox = await sharp(src).extract(box).removeAlpha().raw().toBuffer();
const stats = (a, b) => {
  let sq = 0, max = 0;
  for (let i = 0; i < a.length; i++) { const d = Math.abs(a[i] - b[i]); sq += d * d; if (d > max) max = d; }
  return { psnr: sq === 0 ? Infinity : 10 * Math.log10(255 ** 2 / (sq / a.length)), max };
};
const runs = {
  'png (level 9)': (s) => s.png({ compressionLevel: 9 }),
  'webp lossless': (s) => s.webp({ lossless: true }),
  'webp near-lossless 80': (s) => s.webp({ nearLossless: true, quality: 80 }),
  'webp near-lossless 60': (s) => s.webp({ nearLossless: true, quality: 60 }),
  'webp near-lossless 40': (s) => s.webp({ nearLossless: true, quality: 40 }),
  'webp lossy q90': (s) => s.webp({ quality: 90 }),
  'webp lossy q90 smart': (s) => s.webp({ quality: 90, smartSubsample: true }),
  'webp lossy q80': (s) => s.webp({ quality: 80 }),
};
const input = await sharp(src).toBuffer();
for (const [name, fn] of Object.entries(runs)) {
  const times = [];
  let out;
  for (let i = 0; i < 5; i++) {
    const t = performance.now();
    out = await fn(sharp(input)).toBuffer();
    times.push(performance.now() - t);
  }
  times.sort((a, b) => a - b);
  const all = stats(ref, await sharp(out).removeAlpha().raw().toBuffer());
  const ban = stats(refBox, await sharp(out).extract(box).removeAlpha().raw().toBuffer());
  console.log(name.padEnd(22), String(out.length).padStart(7), 'bytes', `${times[2].toFixed(0)} ms`.padStart(7),
    ' PSNR', all.psnr === Infinity ? 'exact' : all.psnr.toFixed(2),
    ' button', ban.psnr === Infinity ? 'exact' : ban.psnr.toFixed(2), ' max err', all.max);
}

png (level 9)           392945 bytes  240 ms  PSNR exact  button exact  max err 0
webp lossless           323152 bytes  525 ms  PSNR exact  button exact  max err 0
webp near-lossless 80   300790 bytes  744 ms  PSNR 60.05  button 56.64  max err 1
webp near-lossless 60   280278 bytes  772 ms  PSNR 55.50  button 51.86  max err 2
webp near-lossless 40   267204 bytes  756 ms  PSNR 51.36  button 48.54  max err 4
webp lossy q90           61598 bytes   71 ms  PSNR 43.52  button 34.63  max err 77
webp lossy q90 smart     63018 bytes  129 ms  PSNR 43.72  button 34.17  max err 84
webp lossy q80           45898 bytes   65 ms  PSNR 42.25  button 33.99  max err 68

Mode	Bytes	vs PNG	Max error	Button PSNR	Median time
PNG, level 9	392,945		0	exact	240 ms
WebP lossless	323,152	-18%	0	exact	525 ms
Near-lossless 80	300,790	-23%	1	56.64 dB	744 ms
Near-lossless 60	280,278	-29%	2	51.86 dB	772 ms
Near-lossless 40	267,204	-32%	4	48.54 dB	756 ms
Lossy q90	61,598	-84%	77	34.63 dB	71 ms
Lossy q90, smartSubsample	63,018	-84%	84	34.17 dB	129 ms
Lossy q80	45,898	-88%	68	33.99 dB	65 ms

Why is there such a gap between the modes?

The lossless modes must keep every pixel of the faint background grid and every anti-aliased edge, so they stay large: lossless WebP saved only 18% over PNG here. Near-lossless 40 took another 17% off lossless, and never moved a channel by more than 4. On a flat UI that is invisible: an edge pixel shifts to its neighbour's shade.

Lossy WebP plays a different game. It cut 81% off lossless at q90, but some pixels moved by 77. Those are the text edges on the green button, where reduced-resolution colour mixes white into green. The button PSNR shows it: 48.54 dB for near-lossless 40, 34.63 dB for lossy q90. smartSubsample did not help on this image (34.17 dB, and 1,420 bytes larger).

Note: quality means two different things in sharp's WebP encoder. In lossy mode it is the usual quality. With nearLossless: true it is the preprocessing level, and lower means more change. With lossless: true alone, libwebp treats it as compression effort, per Pillow's notes on the same libwebp setting. Do not reuse one "quality" variable across modes.

What does it cost in time?

Lossless and near-lossless are slow. At default effort, they took 525 to 772 ms for one 1440 × 900 frame on an M1 Pro. Lossy took 65 to 129 ms, several times faster. Timings move between runs, so read them as orders of magnitude, not exact figures.

That matters in a request path. If you convert screenshots on upload, put the encode in a background job, or cache the result by content hash so you pay once.

Which mode should you ship?

Docs and tutorials where text must stay crisp: near-lossless 60 or 40. You save 13% to 17% over lossless and nobody can see the change.
Pixel-exact needs (visual regression baselines, design handoff): plain lossless. It still beat PNG level 9 by 18%.
Page weight first (a marketing page, a blog hero): lossy q90. It is about a fifth of the lossless size, but zoom into your coloured buttons before you ship it.

To try one file without code, the Blinkimg PNG to WebP converter takes a screenshot and returns a WebP, and What is WebP? covers browser support and the format's limits.

How I measured

Machine: Apple M1 Pro, macOS, 2026-10-17.
Node v24.22.0, sharp 0.35.4, libvips 8.18.6, libwebp 1.6.0.
Source: apps/web/assets/reference/screenshot.png in the Blinkimg repo, a 2880 × 1800 Retina screenshot of Blinkimg's own pricing page, halved to 1440 × 900 with sharp's default resize.
Times are the median of 5 encodes from an in-memory PNG buffer, including decode. Bytes are identical across runs.
PSNR is over RGB against the source; the button box is 260 × 64 at (740, 624).

What I did not test

Effort levels other than the default, alpha channels, and AVIF lossless. I did not check decode time in browsers.