# Auraimage Url API

> Rules for constructing AuraImage transformation URLs and responsive image elements. Use when writing or reviewing any code that displays images — <img> tags, CSS background-image, Next.js Image components, or image-related utility functions. Triggers on tasks involving image display, optimization, or responsive layouts.

- Skill: `auraimage/auraimage-url-api` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add auraimage/auraimage-url-api`
- Raw SKILL.md: https://api.skillmd.com/api/skills/auraimage/auraimage-url-api/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: MIT
- Author: auraimage (https://skillmd.com/u/auraimage)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/auraimage/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}`.

| Option | Type | Description |
|--------|------|-------------|
| `w` | integer | Output width in px. Always set this — never serve full-resolution images. |
| `h` | integer | Output height in px. Optional; omit to preserve aspect ratio. |
| `q` | 1–100 | Quality. Default: `80`. Use `60`–`75` for photos, `90` for logos/UI. |
| `fit` | `cover` \| `contain` \| `face` \| `auto` | Crop mode. Default: `cover`. |
| `lqip` | `true` | Returns a tiny low-quality placeholder image to show while the full image loads. For a client-decoded BlurHash placeholder, fetch `GET /v1/blurhash/{project}/{name}` instead. |

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

```tsx
<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.