# FireImg image URL reference

FireImg serves optimized images from a CDN. You can use the image URL directly in an <img /> tag’s src attribute, or build URLs programmatically with @fireimg/js or @fireimg/react.

Optimized URLs use path-based parameters (not query strings) so CloudFront can resolve the same S3 object key the optimizer writes—no Lambda@Edge rewrite required.

https://img.fireimg.com/{project}/images/{variant}/{imageKey}

• Base URL — Use https://img.fireimg.com for all image URLs. (The domains https://i.fireimg.com and https://images.fireimg.com are equivalent aliases.)
• — Your project slug (from the FireImg dashboard).
• — Comma-separated optimization tokens (see below). Omit this segment only when you have no parameters (rare); the @fireimg/js client always includes at least default quality and inferred format so CDN cache keys stay stable.
• — The image path/key (e.g. hero.jpg, gallery/photo.png). A leading slash is optional.

Build tokens in this order for best cache alignment across clients and documentation:

1. w_<pixels> — width (1–4000)
2. h_<pixels> — height (1–4000)
3. q_<preset or number> — q_low, q_medium, q_high, or q_1 … q_100
4. fmt_<format> — fmt_jpg, fmt_png, fmt_webp, fmt_avif, or fmt_auto (prefer inferring from the file extension when using auto)
5. fit_<fill|cover|contain> — only when both width and height are set
6. pos_<center|top|bottom|left|right> — only when fit_cover

Example:

https://img.fireimg.com/firelit-marketing/images/w_270,h_760,q_medium,fit_cover,pos_right/mountain.jpg

When the optimizer writes to S3, tokens that appear in your URL path are kept in that order; any additional parameters the server infers (for example resolved output format) are appended after them in the recommended order above so the stored object key stays stable.

The optimizer may still accept legacy query-string URLs for a transition period (?width=270&height=760&…); new links should use the path form above.

If you still have old variant keys under modified-images/ (nested param/value segments instead of /images/{variant}/), the repo includes scripts/migrate-modified-images-s3.py. Run it locally with bucket credentials; it copies each legacy key to the new …/images/{tokens}/{imageKey} layout using the recommended token order, skips keys that already exist, and is safe to stop and resume. Large buckets can take many hours.

Omit width and height to use the raw image dimensions (quality and format still apply).

<img
  src="https://img.fireimg.com/my-project/images/w_800,q_high,fmt_jpg/hero.jpg"
  alt="Hero"
  width="800"
  height="450"
/>

Fixed width and format:

<img
  src="https://img.fireimg.com/my-project/images/w_400,q_medium,fmt_webp/photo.png"
  alt="Photo"
  width="400"
/>

Thumbnail with both dimensions and cover fit:

<img
  src="https://img.fireimg.com/my-project/images/w_300,h_200,q_medium,fmt_jpg,fit_cover,pos_center/banner.jpg"
  alt="Banner thumbnail"
  width="300"
  height="200"
/>

Responsive image with srcset (multiple widths):

<img
  src="https://img.fireimg.com/my-project/images/w_800,q_medium,fmt_jpg/hero.jpg"
  srcset="
    https://img.fireimg.com/my-project/images/w_400,q_medium,fmt_jpg/hero.jpg 400w,
    https://img.fireimg.com/my-project/images/w_800,q_medium,fmt_jpg/hero.jpg 800w,
    https://img.fireimg.com/my-project/images/w_1200,q_medium,fmt_jpg/hero.jpg 1200w
  "
  sizes="(max-width: 600px) 100vw, 800px"
  alt="Hero"
/>

For dynamic or responsive URLs, use the npm packages so tokens and order stay consistent with the CDN:

JavaScript / TypeScript (@fireimg/js):

import { createFireimg } from '@fireimg/js';

const fireimg = createFireimg({ project: 'my-project' });

const url = fireimg.getUrl('hero.jpg', { width: 800, quality: 'high' });
const srcset = fireimg.getSrcSet('hero.jpg', { minWidth: 400, maxWidth: 1200, snapStep: 200 });

React (@fireimg/react):

import { FireImg } from '@fireimg/react';
import { configureFireimg } from '@fireimg/react';
configureFireimg({ project: 'my-project' });

<FireImg imageKey="hero.jpg" width={800} quality="high" alt="Hero" />

See @fireimg/js and @fireimg/react for full options and installation.