AeroModel

AeroModel

Documentation

Edge cache

The API is designed to serve the vast majority of requests from the Cloudflare edge cache, without touching R2 storage or the Worker runtime beyond the first hit.

Mechanics

Cache key

For /v1/images/plane, the cache key is built from:

  • Resolved plane (slug)
  • Resolved airline (slug, or null)
  • Applied liveryType (may differ from requested after fallback)
  • angle, gear, filetype
  • All render parameters: width / resolution, zoomType, zoomLevel, marginPercent
  • All composition parameters: pitch, scale, referencePlane, align, background, backgroundGradient
  • Resolution state (livery, blank, fallback)
  • Manifest version

Auth (x-api-key) is not part of the key: two different clients with the same request share the same cache hit.

Manifest versioning

On every server-side storage rebuild (new aircraft, new livery, re-render), the manifest version changes. Since this version is part of the cache key, all caches become invalid automatically without manual purge.

The current version is exposed in the x-manifest-version header on every response.

Lifetime

  • Cloudflare edge cache: Cache-Control: public, max-age=86400 (24h) by default.
  • The browser respects this and also caches.
  • Manifest bump invalidation bypasses the TTL.

Understanding cache headers

HeaderMeaning
cf-cache-status: HITServed from the edge cache
cf-cache-status: MISSFirst hit, generated by the Worker
cf-cache-status: REVALIDATEDCache stale, revalidated
cf-cache-status: BYPASSCache bypassed (e.g. session cookies)
age: 1234Seconds since the response was cached
x-manifest-version: 2026-04-29T18:03:11ZManifest version that served this asset

Optimizing your calls

Stabilize parameter order

?plane=A320&airline=AF and ?airline=AF&plane=A320 produce two different cache keys on Cloudflare. Always use the same order.

Prefer canonical values

Using the slug (airbus-a320-200) rather than the IATA code (320) ensures all your clients hit the same URL and share the cache. The API resolves both but caching is per-URL.

Prefer resolution presets

?resolution=card is more stable than ?width=1024. If we remap card to 1100 px tomorrow, your URL doesn't change → your clients keep hitting the cache.

Avoid floating values

zoomLevel=1.234567 breaks cache deduplication. Prefer zoomLevel=1.2. The API already rounds to 2 decimals but the URL must be stable.

Stale Cache

If Cloudflare can't reach R2 (outage), it serves the asset from the stale cache rather than failing. Header cf-cache-status: STALE.

Manual purge

If you need to purge an asset before a manifest bump (e.g. urgent livery fix), contact the maintainer — purge is done via the Cloudflare API server-side.