An image API you drive with a URL

EVERY image is a URL

Point Refract at an image origin you already have. It fetches the original on demand, transforms it on the fly, and hands it back down the wire — and it will spend this entire page telling you exactly what it did, the way a package tells you exactly what is in it.

A single white plastic garden chair standing off-centre on a cracked concrete forecourt in front of a plain wall. — A perfectly ordinary photograph. That is the point — it is a sample input, not a mood.

Here is the whole thing, said plainly, before the tables start. You keep your images wherever they already live. You point Refract at that origin once. From then on, a transform is a request, and a request is a URL — width, format, quality, a crop, a rotation, appended to a path you already had. There is no upload step, because there is nothing to upload: the original was always yours and it stays yours.

The originals are fetched on demand and cached at the edge, and they are never stored permanently — which is the one sentence in this paragraph a developer actually came here to read, so we have set it apart and we are happy to say it twice. Refract holds a transformed variant for a while so the second visitor is fast; it does not become a filing cabinet for your source images, and it was never asked to be one.

Ask for fm=auto and Refract reads the Accept header your browser already sent, then hands back AVIF, or WebP, or JPEG, in that order of preference — whichever the request said it could take. The average result is 62% smaller than the source JPEG. We are not going to animate that number shrinking for you on this page; a browser cannot re-encode an image, so the demo below cannot honestly show it, and a number we cannot show honestly is a number we would rather leave in the table where the brief put it.

There are 41 edge locations. A cached response comes back in a median of 21 ms, and 98.6% of requests are cache hits. When it is genuinely a cold transform — the first time anyone has asked for that exact combination — it takes 89 ms at the median and 340 ms at the 99th percentile, and we are printing that last figure rather than hiding it, because a latency a page hides is a latency everybody assumes is worse.

p.s. — yes, this is a lot of words for an API. so is the back of a carton.

Three things, and it does all three

A stack of plain blank cardboard sheets lying slightly askew on a bare workbench.

Transform

Ten chainable URL parameters — width, height, fit, format, quality, and the rest. Smart crop keeps the subject in the frame instead of guillotining it down the middle.

A folded blank paper bag resting flat on a plain formica table, its creases catching the light.

Optimize

fm=auto negotiates AVIF, then WebP, then JPEG from the request's Accept header. Average payload comes back 62% smaller than the source JPEG.

A plain grey utility cabinet standing against a blank pebbledash wall on an ordinary pavement.

Deliver

41 edge locations. Cached response 21 ms at the median, 98.6% cache hit ratio, and a cold transform of 89 ms median rising to 340 ms at the 99th.

The marked-up proof

Nobody in the history of the world ever changed a photograph by filling in a form. They put the print on the table and wrote on it. So there is no panel here: the controls are scrawled in the margin around the photograph, each one tied by a drawn line to the part of the picture it governs. Move any of them and the After plate repaints and the URL along the foot rewrites itself. The Before print never moves — that is the entire point of a before.

A single orange traffic cone standing off-centre to the right on wet grey tarmac. — Before

The same traffic cone photograph, live, with your transforms applied.

After

w width, px — drag the right edge or type

px

h height, px — drag the bottom edge or type

px

fit

cover contain fill crop

not set

crop

smart center edges

not set

rot

90 180 270

not set

blur gaussian, 0–100

bg fill for contain, hex

not set

* The boring bit

Three of these ten do not happen in your browser, and we are not going to stand here and mime them for you — not on a page whose whole pitch is that it tells you what is in the box. fm=auto negotiates AVIF → WebP → JPEG off the Accept header your request already sent. q is applied when the image is re-encoded, and a browser cannot re-encode anything, so there is no animation here of a payload getting smaller: we would rather lose the demo than invent the number. dpr is the honest one — your browser knows its own device pixel ratio, we asked it, and what is printed up there is what it said, clamped to the 1–3 the reference documents. That is the entire boring bit. Thank you for reading the boring bit. Almost nobody does.

62%

Avg payload reduction

21 ms

Median cached response

98.6%

Cache hit ratio

99.95%

Uptime SLA

Print your first URL

Create a key, point us at your origin, and append a parameter. The docs take about four minutes and every number in them came off the brief.

Start building