URL API

Every image is served from a deterministic, human-readable URL. Append query params to resize, crop, and re-format on the fly — the edge transforms once and caches forever.

URL structure

https://cdn.auraimage.ai/[projectName]/[filename]?[params]

Segment	Description	Example
`projectName`	Your project identifier — same as `NEXT_PUBLIC_AURA_PROJECT_NAME`.	`my-app`
`filename`	The `key` returned by upload (or whatever you stored).	`abc123xyz0-hero.jpg`
`params`	Transformation query string.	`w=800&q=75&fmt=auto`

https://cdn.auraimage.ai/my-app/abc123xyz0-hero.jpg?w=800&q=75&fmt=auto

Transformation parameters

Sizing

Param	Type	Default	Notes
`w`	integer	—	Width in pixels. Capped at `8192`. Height scales proportionally unless `h` is also set.
`h`	integer	—	Height in pixels. Capped at `8192`.
`fit`	string	`cover`	How to fit the image into the requested box. Only meaningful when `w` or `h` is set.

fit values:

Value	Behavior
`cover`	Crop to fill the exact box.
`contain`	Letterbox — full image visible, no crop.
`face`	Cloudflare-native face detection. Crops the most prominent face into the box.
`auto`	Cloudflare-native saliency detection. Crops to the most visually important region.

When fit=face or fit=auto succeeds, the response carries X-Aura-Smart-Crop: ok. When no face / salient region is detected, the result falls back to a centered cover crop (the header is omitted).

Quality & format

Param	Type	Default	Notes
`q`	1–100	`80`	Compression quality. Ignored for lossless masters served pass-through.
`fmt`	string	`auto`	Output format.

fmt values:

Value	Behavior
`auto`	Recommended. Picks the best format the client accepts.
`avif`	Force AVIF.
`webp`	Force WebP.
`jpeg`	Force JPEG.

Loading helpers

Param	Type	Description
`blur=true`	flag	Returns the BlurHash string as JSON instead of an image — `{ "blurhash": "..." }`. The `<AuraImage />` component uses this internally.
`lqip=true`	flag	Returns a low-quality image preview (small, heavily compressed) for placeholder rendering.

Content negotiation

When fmt=auto (or fmt is omitted), the edge reads the Accept header and serves in priority order:

AVIF  →  WebP  →  JPEG

The response carries Vary: Accept so the cache stores one variant per accept-class — no cross-browser cache poisoning.

SEO filenames

Descriptive filenames improve image rankings in Google Images. The key returned by signUpload preserves the filename you posted (prefixed with a 10-char collision-resistant ID):

# Good — descriptive
https://cdn.auraimage.ai/my-app/abc123xyz0-golden-gate-bridge-sunset.jpg

# Avoid — opaque
https://cdn.auraimage.ai/my-app/abc123xyz0-img-00432.jpg

Pass a meaningful filename form field at upload time. Use hyphens as separators.

Project names are immutable

A project name is permanent. Renaming would break every published URL, so the dashboard does not allow it. Pick carefully during aura init or MCP install.

Reserved names (cannot be used as a project name): api, admin, cdn, health, registry, static, test, v1.

Caching behavior

Visibility	`Cache-Control`	Edge cache
Public	`public, max-age=31536000, immutable`	Yes — first request transforms, every subsequent request hits the edge.
Private (`?token=`)	`private, max-age=300`	No — every request bypasses the shared edge cache and hits origin.

Cache tags are set on every public response so you can purge surgically:

Tag	Applies to
`project-<projectName>`	Every public image in the project.
`fit-face`	Public images served with `fit=face`.
`fit-auto`	Public images served with `fit=auto`.

Purge a single project from the dashboard without affecting any other project, and re-render smart-cropped variants without invalidating exact-size crops.

Response headers

Every successful image response carries:

Header	Values	Meaning
`X-Aura-Cache`	`HIT` \| `MISS`	Whether the edge cache served this response.
`X-Aura-Smart-Crop`	`ok`	Set only when `fit=face` / `fit=auto` produced a crop. Absent on fallback.
`Server-Timing`	see below	Per-stage timings, set on both hits and misses.
`Vary`	`Accept`	Required for correct format negotiation caching.

Server-Timing

A standard Server-Timing header lets you measure delivery in DevTools or RUM without any custom instrumentation.

On a cache hit:

Server-Timing: cache;desc="HIT";dur=<ms>

On a cache miss:

Server-Timing: cache;desc="MISS";dur=<ms>, r2;dur=<ms>, process;desc="transformed";dur=<ms>

Pass-through misses (no transformation needed) report process;desc="passthrough";dur=0.

Stage	What it measures
`cache`	Edge cache lookup.
`r2`	Origin object fetch from R2.
`process`	Transformation (resize, format conversion, smart crop). `passthrough` when the master is served as-is.

Open Chrome DevTools → Network → click any image response → Timing tab to see these stages plotted alongside browser timings.

On this page