Documentation

From first request to automated in three steps.

Refract is driven entirely by URL parameters. Point it at an image origin, append parameters, and the render is fetched, transformed, and cached at the edge on demand.

Quickstart

A neat stack of blank photographic prints resting on a pale table in soft daylight
1

Create an API key and connect your origin.

Generate a key and point Refract at an existing image origin. Originals are fetched on demand and cached at the edge — never re-uploaded, never stored permanently.

2

Request your first transform.

Append parameters to the source URL. Every render is a plain GET.

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

3

Automate with the SDK.

Build the same URLs in code.

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

Ten parameters, chainable in any order. Three are negotiated server-side from the request and never need to be set by hand.

Parameter Accepted values Description
w
integer px
Target width of the render.
h
integer px
Target height of the render.
fit
cover · contain · fill · crop
How the source is fitted to the requested width and height.
fm Negotiated
jpeg · png · webp · avif · auto
Output format. auto negotiates AVIF → WebP → JPEG from the request's Accept header.
q Negotiated
1–100, default 75
Compression quality.
dpr Negotiated
1–3
Device pixel ratio applied to the requested dimensions.
crop
smart · center · edges
Crop strategy. smart keeps the subject in frame.
rot
90 · 180 · 270
Rotation in degrees.
blur
0–100
Gaussian blur radius.
bg
hex color
Background fill, applied when fit=contain.

Caching & limits

Rate limit
50 requests per second, per key — the same across all tiers.
Edge cache
Transformed variants are cached at the edge for 30 days. Instant purge by URL or by tag.
Cold transform
p50 89 ms, p99 340 ms across 41 edge locations; cached responses return in a median 21 ms at a 98.6% hit ratio.