How Vyso image delivery and CDN caching work

Vyso image delivery uses the asset key and transformation chain in a CDN URL to identify a requested representation. Reusing that URL gives the delivery layer an opportunity to reuse the generated output. Changing the source or a preset while keeping the URL requires a separate decision about cache invalidation.

Use stable URLs for stable representations. Choose a new delivery identity deliberately when the output changes, and inspect response headers when checking how a particular request was served.

A delivery URL identifies a representation

The source asset is the authoritative original in the media library. A delivery representation is the output requested from that source, such as an 800px image or an 800px WebP. A cache can hold that output without changing the original.

asset key + ordered transformation chain
→ requested image representation
→ delivery URL

These Vyso URLs request different representations:

https://cdn.vyso.io/resize:width=800/ASSET_ID.jpg
https://cdn.vyso.io/resize:width=1200/ASSET_ID.jpg
https://cdn.vyso.io/resize:width=800/format:type=webp/ASSET_ID.jpg

Replace ASSET_ID.jpg with your source asset key. The first two request different widths. The third adds an explicit WebP conversion. Vyso preserves the source format unless a format transformation or a format-specific operation changes it; the filename extension alone does not tell you the delivered format. Check the response Content-Type and the output-format reference.

Transformation order is also intentional. resize:width=800/format:type=webp and format:type=webp/resize:width=800 specify different ordered chains. Even if two recipes look equivalent for one image, keep one consistent URL recipe for that placement. Do not assume the delivery system merges equivalent chains into a single cache identity.

Keep unchanged representations at unchanged URLs

Store or construct a consistent recipe for each image placement. For example, all uses of an 800px product image with the same treatment should use the same asset key and transformation sequence. Small, arbitrary differences in widths or effects create additional requested outputs that the application then has to maintain.

A common source of unnecessary variation is adding a fresh timestamp on every render. This is an anti-pattern, not a supported Vyso transformation or invalidation instruction:

https://cdn.vyso.io/resize:width=800/ASSET_ID.jpg?v=1701
https://cdn.vyso.io/resize:width=800/ASSET_ID.jpg?v=1702
https://cdn.vyso.io/resize:width=800/ASSET_ID.jpg?v=1703

The application has produced different request URLs even though the intended image is unchanged. HTTP cache keys include the target URI, although managed caches can apply their own rules. Vyso's public reference does not define arbitrary query parameters as a cache-busting mechanism. Keep representation changes in the documented delivery contract instead of relying on an assumed treatment of these parameters. RFC 9111 describes HTTP cache keys.

Useful versioning happens when there is an actual new source or recipe to publish. A timestamp that changes on every page load gives the application no stable version to reuse.

What happens when a representation is requested

The Vyso delivery model generates the representation requested by the URL, with generated variants available for later reuse. A practical request flow is:

The application requests a specific delivery URL.
The delivery layer resolves that representation. A reusable cached response can satisfy the request where it is available.
When the requested output needs to be generated, the source and ordered transformation chain determine the result.
Later requests at the same URL can reuse a cached representation according to the cache policy and current cache state.

A request from one location does not establish that every edge has the output. Repeating a URL also does not guarantee that the next response will be a cache hit. The URL makes consistent reuse possible; availability in a particular cache still has to be observed.

Separate browser caching from CDN caching

A browser can keep its own copy of an image. A CDN cache is a separate layer in the delivery path. A locally cached response can satisfy a page load before a network request reaches the CDN. These are different forms of reuse, as described in MDN's HTTP caching guide.

In browser DevTools, an entry marked as coming from memory cache or disk cache is evidence of local reuse. It does not tell you whether the CDN would have returned a hit or a miss.

When checking network delivery, record whether browser caching is enabled. Chrome DevTools has a Disable cache option for making requests without browser-cache reuse while DevTools is open. That setting does not purge the CDN. Reload and debugging options can also change request behavior, so compare requests under consistent conditions.

Inspect response headers instead of guessing

Use the Network panel to inspect a real image request, or make a GET request that prints the headers and discards the body:

curl --fail-with-body --silent --show-error \
  --dump-header - --output /dev/null \
  "https://cdn.vyso.io/resize:width=800/ASSET_ID.jpg"

Use a real asset key for this check. Inspect the HTTP status first, then Cache-Control and Content-Type. An error response is not a successful image representation, even if it arrives quickly.

Cache-Control describes response caching policy. For example, public allows shared caching, and max-age defines a freshness lifetime. Neither directive proves that the response was served from an edge cache. MDN explains the directives.

The current Vyso caching reference does not define a named cache-status header. Read any additional headers actually returned by the delivery endpoint using their documented meanings. Do not manufacture a HIT/MISS result from a short response time or an HTTP 200 status.

The caching documentation directs developers to response headers and warns against depending on undocumented TTLs. Use the values returned for the request being tested. Do not build an update workflow around an assumed hour, day or permanent cache lifetime.

A changed source needs an update strategy

If the source bytes change while the asset key and transformation URL stay the same, a previously cached representation can still contain the earlier image. A successful library update and a fresh delivered image are separate things to verify.

Changing a title or description is another kind of update. It does not express a new resize or format recipe in the delivery URL. If the application displays that metadata as page text, its own content caching may also need attention.

For source changes at an existing URL, establish how the relevant caches will refresh before depending on the new output. The current public documentation does not specify a purge API or a propagation deadline. Do not schedule a release around an assumed global purge time.

An alternative is to publish the new source under a new asset key and update the application to request its delivery URLs. This makes the new identity explicit. Pages that still reference the old key continue requesting the old identity, so switching references is part of the release. Publishing a new URL does not remove previously cached or downloaded copies of the old image.

A changed preset can keep the same URL

A delivery preset gives a saved transformation configuration a reusable name. For a preset you have created with the slug product-card, the delivery URL is:

https://cdn.vyso.io/preset/product-card/ASSET_ID.jpg

Editing that preset can change the requested output while this URL remains identical. Treat that as an invalidation concern. Saving a preset definition does not establish that every existing cached response has been replaced.

For a treatment that should become a distinct published version, an application can create a new preset slug, such as product-card-v2, and update its references:

https://cdn.vyso.io/preset/product-card-v2/ASSET_ID.jpg

This is an application versioning choice. Those slugs are examples, not built-in presets or an automatic version-history feature. Test the new recipe, switch the intended placements, and retain the previous configuration during the transition if other pages still use it.

With direct transformations, changing the recipe in the path makes the difference visible in the URL. With a preset, the recipe sits behind its name. Both approaches need a defined policy for changes.

Keep sizing and format decisions separate from caching

The delivery URL specifies the representation. For responsive images, the frontend exposes candidate URLs through srcset and sizes, and the browser selects a candidate. Each candidate can retain its own stable URL. Responsive images from one source with Vyso covers that implementation.

Width, output format and compression settings determine what the representation contains. Caching determines how that requested output can be reused. For those image decisions, use the image quality and web performance workflow. A cached oversized image is still oversized for its placement.

Debug unexpected cache behavior

When an image looks stale or repeated requests seem inconsistent, capture one concrete request before changing the application:

Copy the exact requested URL from the Network panel. Compare the asset key, transformation order and parameters with the intended recipe.
Check whether the browser supplied a memory or disk cache copy. Record the browser-cache setting used for the test.
For a network response, inspect the status, Cache-Control and Content-Type. Save the headers alongside the URL.
Check whether the source bytes changed or the preset definition changed while the URL stayed identical.
Check URL construction for timestamps, random values or unintended variation in transformation parameters.
Repeat the same URL under consistent conditions. If you need to escalate the issue, include the request URL, observed headers, returned image and relevant source or preset change.