Mediaflow CDN

Edge URLs & Transformations

The public CDN URL format, how stable and versioned URLs are cached, and every transform parameter you can append to resize, crop and convert images on the fly.

Public edge URL

The URL returned by the management API is what you embed in pages, newsletters, or apps. All clients fetch through the edge.

{edge-base}/1/{usageId}/{resourceId}/{params...}/{filename}[?query params]

1 - the API version prefix; part of the URL.
usageId - customer-scoped token (allocated automatically on first resource creation).
resourceId - returned by POST /1/cdn/resources.
params... - zero or more transform parameter segments (see Transform parameters); also accepted as query parameters. Path segments must be lowercase.
filename - required as the last path segment.

Only GET is served; HEAD and other methods return 405.

Stable vs versioned URL

Every resource comes with two URLs:

Field	Shape	Cache-Control	Use when
`url`	`…/{resourceId}/hero.jpg`	`public, max-age=3600, s-maxage=86400`	Default. The URL is embedded once and must update in place when the source is replaced. Browsers revalidate hourly (a `304` when nothing changed), shared caches daily.
`versionedUrl`	`…/{resourceId}/v{version}/hero.jpg`	`public, max-age=31536000, s-maxage=86400, immutable` while `v{version}` matches the current version	Opt-in. Your platform re-fetches resource data from the API on every build or sync and re-deploys the new URL itself, so browsers can skip revalidation entirely.

A versionedUrl whose version no longer matches (an old embed after a PUT, or a brand-new version that has not finished processing yet) still works: it serves the current bytes with the stable-URL header, never immutable. Old embeds never break. Transform parameters go before the v{version} segment or in the query string as usual.

Transform parameters

Both short (one-letter) and long names are supported, as path segments or query parameters. Query parameters take precedence over path parameters, which take precedence over the resource defaults. Path segments and their values must be lowercase; query keys are case-insensitive.

Name	Short	Type	Range	Default	Path example	Query example
width	w	int	0–10000	0 (unconstrained)	`w500`	`?w=500`
height	h	int	0–10000	0 (unconstrained)	`h300`	`?h=300`
quality	q	int	0–100	80 (`0` = default; ignored for PNG)	`q80`	`?q=80`
format	f	enum	webp, avif, jpeg (`jpg` accepted), png, auto	auto	`fwebp`	`?f=webp`
fit	fit	enum	cover, contain, scale-down	cover	`fitcover`	`?fit=cover`
dpr	dpr	float	0–5	1 (`0` = 1)	`dpr2`	`?dpr=2`
zoom	z	percent	100–1000 (values below 100 mean no zoom)	100	`z258`	`?z=258`
focus point	fp	two floats 0–100	`0–100,0–100`	none (resource `focusX`/`focusY` defaults if set)	`fp50,75`	`?fp=50,75`
region	rg	x,y,w,h percent	0–100 each; `w`,`h` > 0; must stay inside the image	none	`rg50,20,39,35`	`?rg=50,20,39,35`
background	bg	6-char hex	-	none	`bgff0000`	`?bg=ff0000`

Output size is w/h × dpr, clamped to 10000 px on each side. EXIF orientation is applied and metadata is stripped on every transformed output.

Cropping: focus + zoom (fp/z) vs explicit region (rg)

Two ways to crop, in precedence order:

rg (region) - an explicit source rectangle as x,y,w,h percentages (top-left origin). It carries position and extent, so it reproduces any editor crop, including off-aspect ones. When present, rg wins and fp/z are ignored. Output is the region resized to w/h (fit falls back to contain so the selection is never re-cropped). Requires w/h > 0; rejected with 400 if the region is empty or extends past 100 on either axis.
fp + z - fp positions a crop window on a focus point; z (zoom percent, >100) shrinks that window to zoom into the source before resize. Centre + target aspect (w/h) + z together determine the rectangle. Example: fp70,37/w512/h207/z258 zooms ~2.58× centred near the top-right. z without fp zooms into the centre of the image.

z zooms the source region - it does not scale the output. Output size is always w/h (times dpr). When fp, z or rg is set together with both w and h, fit falls back to contain (if it was cover or unset) so the crop is fitted into the target box rather than re-cropped; an explicit scale-down is kept.

Fit modes

Mode	Behavior
cover	Resize to cover the target area; crop excess. Default. With only one of `w`/`h` set it behaves like `contain`.
contain	Fit inside the target area. Pads to the exact box with the `bg` colour only when `bg` is set and both `w` and `h` are given; otherwise the output is the fitted image, without padding.
scale-down	Like `contain` but never upscales and never pads.

Format negotiation

When format is auto (or unspecified) the edge picks AVIF if the request's Accept header allows it, else WebP, else the format of the stored rendition (WebP for images), and caches each negotiated format as its own variant. Negotiation runs on transformed requests only: the resource defaults, path segments and query parameters are merged first, and if the result contains no transform the stored rendition is served unchanged.

GIF sources: the transform pipeline does not produce GIF, so the last step of negotiation falls back to PNG instead of the source format. PNG is lossless, so that response is larger than the AVIF or WebP rendition of the same image.

Response headers

Header	Value	Meaning
Cache-Control	`public, max-age=3600, s-maxage=86400`	Stable URL: browsers hold an hour, shared caches a day, then revalidate
Cache-Control	`public, max-age=31536000, s-maxage=86400, immutable`	`versionedUrl` on an exact version match
Cache-Control	`no-store`	Every error response
ETag	`"v{version}-{hash}"` / `"v{version}-identity"` / `"v{version}-static"`	Transformed output / stored rendition served unchanged / non-image file. Changes whenever the version or the parameters change
Vary	`Accept`	Set on transformed responses with negotiated format. It is not guaranteed to reach the client, but format variants are always cached separately, so do not depend on the header being present
Content-Type	`image/webp`, `image/avif`, `image/jpeg`, …	Resolved output format
X-Cache	`HIT`, `MISS`, `DEDUP`	Cache state of the transformed variant; only on transformed `200` responses
Retry-After	`30`	On `503` responses
Last-Modified, Accept-Ranges	-	Untransformed and non-image files only; these also support `Range` (`206`) and `If-Modified-Since`

Supports If-None-Match for 304 Not Modified on every response.

Edge status codes

Code	When
200	Served
206	`Range` request on an untransformed or non-image file
304	`If-None-Match` (or `If-Modified-Since` on untransformed files) matched
400	Invalid or too-long id, missing filename, invalid parameter value
404	Unknown resource, deleted, or in `error` status
405	Any method other than `GET`
415	The stored file is not an image although its type says so
503 + `Retry-After: 30`	Resource still processing, or the file is temporarily unavailable (retry)

Edge URL examples

Fetching variants from the edge:

# No parameters - resource defaults apply; the stored WebP rendition if the resource has no defaults
GET https://eu1.cdn.mediaflow.com/1/qkrtzn/x8k2m4n6p0q3r5s7t9v1wa/hero.jpg

# Resize via query parameters
GET https://eu1.cdn.mediaflow.com/1/qkrtzn/x8k2m4n6p0q3r5s7t9v1wa/hero.jpg?w=800&h=600

# Resize via path parameters
GET https://eu1.cdn.mediaflow.com/1/qkrtzn/x8k2m4n6p0q3r5s7t9v1wa/w800/h600/hero.jpg

# Format negotiation (Accept: image/avif preferred)
GET https://eu1.cdn.mediaflow.com/1/qkrtzn/x8k2m4n6p0q3r5s7t9v1wa/w800/hero.jpg
Accept: image/avif,image/webp,*/*

# Contain with background padding
GET https://eu1.cdn.mediaflow.com/1/qkrtzn/x8k2m4n6p0q3r5s7t9v1wa/hero.jpg?w=500&h=500&fit=contain&bg=ffffff&f=webp

# Focus-point crop
GET https://eu1.cdn.mediaflow.com/1/qkrtzn/x8k2m4n6p0q3r5s7t9v1wa/w300/h300/fp50,75/hero.jpg

# Focus-point crop with source zoom (~2.58x into the source around the focus point)
GET https://eu1.cdn.mediaflow.com/1/qkrtzn/x8k2m4n6p0q3r5s7t9v1wa/w512/h207/fp70,37/z258/hero.jpg

# Explicit region crop (reproduces an editor crop; overrides fp/z)
GET https://eu1.cdn.mediaflow.com/1/qkrtzn/x8k2m4n6p0q3r5s7t9v1wa/w500/rg50,20,39,35/hero.jpg

# High DPI
GET https://eu1.cdn.mediaflow.com/1/qkrtzn/x8k2m4n6p0q3r5s7t9v1wa/w200/dpr2/hero.jpg

# Versioned URL with transforms (immutable while v1 is current)
GET https://eu1.cdn.mediaflow.com/1/qkrtzn/x8k2m4n6p0q3r5s7t9v1wa/w800/v1/hero.jpg

Mediaflow can change the edge host. Always read the edge URL from the API response - don't construct it client-side.