# image-optimizer

> Make a website's pictures load fast: turn a logo or a photo into the lightest version that still looks the same — any website, any stack — and keep a perfect Lighthouse score. Technically: a traced, minified SVG (VTracer + SVGO) for flat art, or AVIF + WebP for photos, each measured against the original (bytes, PSNR, SSIM), plus the exact `<img>` / `<picture>` markup (width, height, decoding, fetchpriority) that keeps unsized-images, LCP discovery and image-delivery audits green. Browser tool (nothing uploaded), HTTP API and MCP server share one core.

Key facts for agents:

- Audit my page: https://imageoptimizer.co/audit/ (also `GET /api/v1/audit?url=<page>`) — every image a public page serves with format, bytes, markup findings (unsized, lazy LCP, no srcset, legacy format, flat art as raster), Slow 4G cost, share of the 2.5 s good-LCP budget and a labelled estimate of what it would become; Convert per image for the real numbers. Where an image offers several sizes (srcset, picture) the candidate a phone downloads is audited (`phonePick`); CSS backgrounds set in the page itself are included (`kind: "css"`), external stylesheets and script-injected images are not. Server-side fetch of the page and up to 20 images (4.5 MB each); nothing stored, URL not logged (AD_010).
- Browser tool: https://imageoptimizer.co/convert/ — decoding, tracing and encoding run in a Web Worker on the device; no upload. Job pages with the same tool: /png-to-svg/ (real vector paths from a logo), /favicon-generator/ (favicon.svg, favicon.ico 16/32/48, Apple touch, PWA + maskable icons, manifest, head tags), /image-to-avif/ (AVIF + WebP + fallback with picture markup).
- Fairness limits (AD_009, per client IP per 5 minutes, answered 429 with a JSON or JSON-RPC body and retry-after 300): 300 requests to /api/*, 30 MCP tool calls, 300 MCP requests; plus a stage-wide 20 requests/s. `GET /api/v1/health` and `GET /mcp` state the current numbers.
- HTTP API (same origin, no auth, inputs ≤ 4.5 MB): `POST /api/v1/vectorize` (image bytes in, `image/svg+xml` out; `?format=json` for the report), `POST /api/v1/optimize` (the whole decision: analysis, SVG, AVIF, WebP, markup; `?format=svg|avif|webp` for one binary; `?widths=auto` for 640/1024/1600/source variants + `srcset` markup), `POST /api/v1/favicons` (favicon.svg when faithful, favicon.ico 16/32/48, apple-touch-icon.png, icon-192/512.png, icon-512-maskable.png, site.webmanifest, head.html; `?format=zip`), `GET|POST /api/v1/audit` (`?url=` or `{url}`: the page audit above), `GET /api/v1/health`, `GET /api/v1/openapi.json`. JSON bodies take `{url}` (public https, ≤ 4.5 MB) in place of `{image: base64}`.
- Field tests: 28 famous brand logos → 23 ship as SVG (median ≈ 760 B Brotli vs 8.4 KB AVIF; gradients, the Wikipedia globe and a serif wordmark stay raster); 1920-px hero photos → AVIF 3.5–5× smaller than the JPEG export, 640-px variant 15–30 KB. Pages (noindex): https://imageoptimizer.co/research/famous-logos/ , /research/hero-images/ , demo /research/hero/ .
- MCP server (stateless Streamable HTTP, keyless): https://imageoptimizer.co/mcp — tools `image_audit` (page URL → its images, findings, labelled estimates; start here for a page), `image_analyze`, `image_vectorize`, `image_optimize`, `image_favicons`, `image_api_info`; inputs `{url}` (public https, ≤ 4.5 MB) or `{base64}`; files come back as resource blobs (≤ 4 MB) and every result carries `speed` (per-request ms on Lighthouse's Slow 4G and desktop profiles). Connect: `claude mcp add --transport http image-optimizer https://imageoptimizer.co/mcp`. Skill: /skills/image-optimizer/SKILL.md.
- Errors are `{"error":{"code","message"}}`; unknown routes answer 400 (never 404); 413 above 4.5 MB; 422 when the body is not an image.
- Commercial use: the browser tool is free for any site (permissive licences); the hosted API/MCP is a free, keyless research service with a shared rate limit and no SLA. A metered plan with keys is planned, not available.
- Decision rule (AD_003): trace when the 16 most common colours cover ≥ 90 % of opaque pixels and there are ≤ 400 distinct 5-bit colours; keep the SVG when PSNR ≥ 22 dB, SSIM ≥ 0.93 and its Brotli size ≤ the AVIF size; inline SVGs under 1.5 KB.
- Defaults: VTracer `logo` preset = colour clustering, polygon paths (30–35 % smaller and more faithful than splines at source size); `mono` = binary trace on the alpha mask recoloured to the source's dominant colour; `smooth` = splines + 1 px simplify for display larger than the source; SVGO precision 2; AVIF q45 effort 4; WebP q75.
- Engines are permissive-licensed (MIT / Apache-2.0); VTracer wasm is built from a pinned tag and recorded in PROVENANCE.md. GPL tracers are benchmarked, not shipped.

## Docs

- [OpenAPI contract](https://imageoptimizer.co/api/v1/openapi.json): every route, parameter, default and error code
- [Agent skill](https://imageoptimizer.co/skills/image-optimizer/SKILL.md): when and how to call the MCP tools
- [Famous-logo field test](https://imageoptimizer.co/research/famous-logos/): 28 brand logos, measured
- [Hero-image field test](https://imageoptimizer.co/research/hero-images/) and the measured [demo page](https://imageoptimizer.co/research/hero/)
- [Vendored engine provenance](https://imageoptimizer.co/vendor/vtracer/PROVENANCE.md): pinned tag, build recipe
- [Changelog](https://imageoptimizer.co/changelog/): what changed for people who use the service, newest first, in plain language; Atom feed at /changelog.xml

## API

- [OpenAPI 3.1](https://imageoptimizer.co/api/v1/openapi.json): the contract, generated from the handler's route table