Quickstart & reference

Three steps stand between an image origin and a rendered URL: a key, a request, and — once the requests multiply — the SDK. The reference that follows lists all ten parameters, the one default Refract fixes, and the three settings a browser can only report and never perform.

Quickstart

Connect an origin

Create an API key and connect your image origin. Refract reads originals from where they already live; nothing is uploaded, and nothing is stored beyond the edge cache.

A single thick glass lens element on a dark workbench, a shaft of window light throwing a bright refracted caustic across the wood. — Fig. 3 — A lens element on a bench, the light passing through it and landing changed. The origin is untouched; only what leaves is rendered.

Request a transform

Ask for the first variant by naming it in the URL. Width, format, and quality are parameters on the source address:

https://demo.refract.dev/hero.jpg?w=1200&fm=auto&q=80

Automate with the SDK

When the requests multiply, build the same URL in code rather than by hand. The SDK returns the string a browser would have asked for.

import { refract } from "@refract/js";

const url = refract("hero.jpg", { width: 1200, format: "auto", quality: 80 });

// → https://demo.refract.dev/hero.jpg?w=1200&fm=auto&q=80

Parameter reference

Parameter	Accepted values	Default	Description
w	integer px	—	Output width in pixels.
h	integer px	—	Output height in pixels. With none set, the image keeps its own aspect ratio.
fit	cover, contain, fill, crop	—	Resize mode. cover and crop recut the frame; contain letterboxes; fill stretches.
fm†	jpeg, png, webp, avif, auto	—	Output format. auto negotiates AVIF → WebP → JPEG from the request's Accept header.
q†	1–100	75	Output quality. The one default the reference fixes.
dpr†	1–3	—	Device pixel ratio. Reported by the browser, honoured at the edge.
crop	smart, center, edges	—	Crop strategy when the fit recuts the frame. smart keeps the subject in frame.
rot	90, 180, 270	—	Rotation in degrees.
blur	0–100	—	Gaussian blur radius.
bg	hex colour	—	Background fill for contain.

† Negotiated or applied at the edge, not in the browser. fm=auto resolves AVIF → WebP → JPEG from the request's Accept header; q is applied server-side; and dpr is reported by the client. A browser cannot demonstrate either re-encode — which is why the live figure on the home page sets these three aside, and marks them with this dagger.

2 / 3