Image API integration checklist

Phase 1: define the asset contract

• Choose the canonical source: managed media library, object storage, CMS, or application upload.
• Store a durable asset ID separately from transformed delivery URLs.
• Record intrinsic width, height, media type, and meaningful alt text at ingest.
• Decide how source replacement affects existing URLs and caches.
• Define retention for originals, rejected uploads, and unused derivatives.

If applications or agents need to find and reason about media, the record should carry context instead of leaving every caller to reconstruct it from a filename. At minimum, preserve identity, dimensions, content type, ownership, and descriptive metadata with the source.

Phase 2: design a finite variant matrix

List interface intents, not raw operations. An avatar, product card, search result, and editorial hero have different crop and width rules. Give those rules names and keep the pixel ladder small.

const imagePolicy = {
  avatar: { aspect: "1:1", fit: "cover", widths: [96, 192] },
  card:   { aspect: "4:3", fit: "cover", widths: [480, 720, 960] },
  hero:   { aspect: "16:9", fit: "cover", widths: [960, 1280, 1600] }
} as const

• Map each preset to one crop mode and one focal-point policy.
• Reject widths outside the allowlist or round requests to the nearest allowed width.
• Keep format and quality defaults configurable without changing component code.
• Version a preset when its crop or visual output changes materially.

Phase 3: centralize URL generation

Create one server-safe module or framework adapter. It should accept asset identity and interface intent, validate inputs, then generate provider syntax. Feature components should not know how a vendor encodes crop, quality, or signatures.

Use the provider SDK when it improves signing, escaping, or type safety. Plain URL construction is reasonable when the grammar is small and covered by tests. Cloudinary documents the structure of its transformation URLs, while ImageKit documents path and query forms for real-time transformations.

Phase 4: lock the trust boundary

• Keep API secrets and signing keys out of browser bundles and public repositories.
• Use signed uploads or narrowly scoped unsigned upload rules.
• Allowlist remote source hosts if the optimizer can fetch arbitrary URLs.
• Set maximum source bytes, decoded pixels, output dimensions, and animation duration.
• Sign or preset any expensive or private delivery transformations.
• Decide whether a private source may ever become a publicly cached derivative.

For an edge-native example, Cloudflare documents origin access controls and the explicit choice involved when private source images become cacheable outputs.

Phase 5: render correct browser markup

• Generate real width candidates and declare their true widths in srcset.
• Make sizes reflect the CSS slot at every layout breakpoint.
• Include intrinsic width and height or a stable aspect ratio.
• Keep the likely LCP image eager; lazy-load images below the fold.
• Write alt text for meaning, not for image-processing metadata.

The responsive image API guide contains a complete markup pattern and explains how the browser selects a candidate.

Phase 6: make caching intentional

• Make transformed URLs immutable or versioned whenever possible.
• Know which request headers vary the response, especially format negotiation.
• Document cache keys, TTLs, validators, purge scope, and source replacement behavior.
• Warm only high-value variants; do not pre-generate every theoretical combination.
• Log the normalized preset and source ID so cache behavior can be aggregated.

Cloudflare explains its source-plus-parameters cache flow in the image transformations overview. Each provider differs, so verify cache headers and invalidation with real requests.

Phase 7: observe quality and cost

Track image requests by preset, width, format, status, cache result, bytes, and transform latency when available. Alert on error rate, origin fetch failures, a sudden rise in unique variants, and large responses for small rendered slots.

Add visual regression cases for transparency, small text, gradients, faces near crop edges, animation, and orientation metadata. Automatic quality is a good baseline, but product acceptance needs representative assets.

Phase 8: roll out with a reversible path

1. Ship the URL builder and response telemetry behind a configuration switch.
2. Migrate one low-risk component and compare bytes, visual output, and Core Web Vitals.
3. Migrate the LCP image only after candidate selection and priority are correct.
4. Retain the prior source URL until replacement and rollback behavior are proven.
5. Expand by preset, not by random pages, so problems map to one transformation policy.