Auraimage Url API

AuraImage URL API

Guidelines for constructing AuraImage CDN URLs, generating responsive <picture> elements, and selecting the right transformation options.

When to Apply

Reference these rules when:

• Writing or reviewing any <img>, <picture>, or CSS url() that serves images
• Implementing responsive image layouts
• Choosing image formats or quality settings
• Building image-heavy pages (galleries, product listings, hero sections)

URL Format

https://cdn.auraimage.ai/{project}/{transform}/{name}[.{ext}]

• project — your project slug (from the AuraImage dashboard)
• transform — one optional path segment of comma-separated options (e.g. w=800,q=75), placed immediately after the project name
• name — the image's extension-less name (e.g. photo, blog/hero), returned by upload
• .{ext} — optional trailing extension that pins the response format; omit it to auto-negotiate (recommended)

Example: https://cdn.auraimage.ai/my-project/w=800,q=75/photo

Transform Options

Options live in the single path segment right after the project, comma-separated: /{project}/w=800,fit=face,q=75/{name}.

The grammar is strict: an unknown key, duplicate key, malformed pair, or out-of-range value (e.g. q=200, fit=stretch) returns 400 naming the offender — nothing is silently ignored. w/h snap up to the nearest step on a fixed ladder (see rules/url-construction.md).

Format & Query Parameters

• Format lives in the extension, not a parameter. There is no fmt. Omit the extension to auto-negotiate (AVIF → WebP → JPEG); append .jpg/.jpeg, .png, .webp, or .avif to pin a format.
• Only two query parameters are honored: v (cache-buster) and token (serve token for private images). Legacy transform query params (?w=, ?h=, ?fit=, ?q=, ?fmt=, ?lqip=, ?blur=) now return 400 — they moved into the path segment. Unrelated params (utm_*, fbclid, …) are ignored.

Rule Categories

1. Always Set a Width (CRITICAL)

• url-width-required — Every AuraImage URL must include a w= option in the transform segment. Serving at original resolution defeats CDN caching and LCP.

2. Responsive Images (HIGH)

• responsive-picture-element — Serve a responsive srcset for any content image wider than 200 px. A plain extension-less <img srcSet sizes> already auto-negotiates AVIF/WebP; reach for <picture> with per-format <source>s only to pin formats or art-direct.
• responsive-srcset-breakpoints — Use at minimum three widths: 400, 800, 1200. Add 2x variants (800, 1600, 2400) for hero images.

3. Format Selection (HIGH)

• format-auto-negotiate — Omit the extension in production; the CDN returns the best format the browser supports (AVIF → WebP → JPEG).
• format-explicit-extension — Only add an explicit extension when you need a specific format for a non-browser consumer (e.g. an <og:image> tag must be JPEG/PNG, so use .jpg).

4. Fit Modes (MEDIUM)

• fit-cover-default — Use fit=cover for thumbnails and cards where the container has a fixed aspect ratio.
• fit-contain-letterbox — Use fit=contain for logos and product images where cropping is unacceptable.
• fit-face-portraits — Use fit=face for user avatars and portrait photos to keep faces centered.
• fit-auto-saliency — Use fit=auto for editorial images where the subject is unpredictable.

5. Quality Presets (MEDIUM)

• quality-photo — Use q=75 for photographs. Visually lossless at a fraction of the size.
• quality-ui — Use q=90 for UI assets (icons, logos, illustrations) where detail matters.
• quality-thumbnail — Use q=60 for thumbnails ≤ 200 px wide.

React / Next.js Projects

In React or Next.js projects, prefer <AuraImage /> over writing raw <picture> elements. The component fetches a BlurHash placeholder, decodes it client-side, and crossfades the full image in once it loads. Falls back to LQIP if the BlurHash fetch fails.

Install: npx shadcn@latest add https://auraimage.ai/registry/image.json

See the auraimage-react skill for full component documentation. Use the raw <picture> patterns below for plain HTML, email templates, Open Graph tags, and CSS backgrounds.

How to Use

Read individual rule files for detailed explanations and code examples:

rules/url-construction.md
rules/responsive-picture.md
rules/format-selection.md
rules/fit-modes.md

Quick Reference: Responsive Picture Element

<picture>
  <source
    type="image/avif"
    srcSet="
      https://cdn.auraimage.ai/{project}/w=400/{name}.avif 400w,
      https://cdn.auraimage.ai/{project}/w=800/{name}.avif 800w,
      https://cdn.auraimage.ai/{project}/w=1200/{name}.avif 1200w
    "
  />
  <source
    type="image/webp"
    srcSet="
      https://cdn.auraimage.ai/{project}/w=400/{name}.webp 400w,
      https://cdn.auraimage.ai/{project}/w=800/{name}.webp 800w,
      https://cdn.auraimage.ai/{project}/w=1200/{name}.webp 1200w
    "
  />
  <img
    src="https://cdn.auraimage.ai/{project}/w=1200/{name}"
    alt="..."
    width={1200}
    loading="lazy"
  />
</picture>

The <img> fallback is extension-less, so it auto-negotiates — a modern browser gets AVIF from it directly. The <source>s above are only needed to pin formats or art-direct.

For Next.js, prefer the MCP tool generate_responsive_tag which produces this automatically.