URL API

Deterministic, human-readable URL structure optimized for SEO and CDN cache efficiency.

AuraImage uses a deterministic, human-readable URL structure optimized for SEO and CDN cache efficiency.

URL Structure

https://auraimage.ai/[slug]/[filename]?[params]

Segment	Description	Example
`slug`	Your unique public project identifier	`narek`
`filename`	Descriptive filename (improves image SEO)	`scenic-yerevan-sunset.jpg`
`params`	Transformation query string	`w=800&q=75&fmt=auto`

Example

https://auraimage.ai/narek/scenic-yerevan-sunset.jpg?w=800&q=75&fmt=auto

Transformation Parameters

Sizing

Param	Type	Description	Example
`w`	integer	Width in pixels. Height scales proportionally unless `h` is also set.	`w=800`
`h`	integer	Height in pixels.	`h=600`
`fit`	string	How to fit the image into the given dimensions.	`fit=cover`

fit values:

Value	Behavior
`cover`	Crop to fill the exact dimensions (default)
`contain`	Letterbox — no crop, full image visible
`face`	AI-powered smart crop centered on detected faces
`auto`	Saliency-based smart crop (faces, objects, subjects)

Quality & Format

Param	Type	Description	Example
`q`	1–100	Compression quality. Default: `80`.	`q=75`
`fmt`	string	Output format. Default: `auto`.	`fmt=jxl`

fmt values:

Value	Behavior
`auto`	Recommended. Detects `Accept` header and serves JXL → AVIF → WebP → JPEG in priority order.
`jxl`	Force JPEG XL (Chrome 145+, Safari 19+)
`avif`	Force AVIF
`webp`	Force WebP
`jpeg`	Force JPEG
`png`	Force PNG (lossless)

LCP / Loading Helpers

Param	Type	Description	Example
`blur`	boolean	Returns the BlurHash string alongside the image response for client-side placeholder.	`blur=true`
`lqip`	boolean	Generates a low-quality image preview (w=50, q=20).	`lqip=true`

Content Negotiation (Auto Format)

When fmt=auto is set (or omitted), the Edge Proxy reads the Accept header and applies this priority:

JPEG XL  →  AVIF  →  WebP  →  JPEG

The Vary: Accept response header ensures Cloudflare caches the correct variant per browser family, preventing cache poisoning.

SEO Filenames

Descriptive filenames improve image rankings in Google Images. AuraImage stores images under the filename you provide:

# Good — descriptive, SEO-friendly
https://auraimage.ai/narek/golden-gate-bridge-sunset.jpg

# Avoid — opaque IDs hurt image SEO
https://auraimage.ai/narek/img-00432.jpg

Filenames are URL-safe slugs. Use hyphens as word separators.

Immutable Slugs

Your project slug is permanent. If you change it, every image URL you have published will break. Choose carefully during aura init.

Reserved slugs: api, admin, test, static, registry, cdn, health.

Caching Behavior

Transformed images are cached globally at Cloudflare's edge on first request.
Cache Tags are applied per project slug, allowing instant purge of a single project without affecting others.
The first request to a new transformation URL may have a slightly higher TTFB while the edge processes and caches the result. Subsequent requests are served from cache.

On this page