Asset CDN

Describes the CDN used for delivering assets

Sanity offers a global content delivery network (CDN) for serving assets, at cdn.sanity.io. This is based on Google's global CDN. Note that this is a different system from our API CDN.

Assets are uploaded content such as images, videos, and other files - see separate article for details. These assets can only be accessed by clients via our asset CDN, optionally with processing by our image pipeline. When an asset is first requested, it is processed by our backend systems and then cached by the CDN on servers located near end-users. Subsequent requests are then served from the cache, ensuring fast response times and a better user experience.

Assets are cached indefinitely. The asset URL includes a SHA-1 hash of the asset contents, so any content changes will generate a new URL, thus avoiding the need to invalidate the cached entries. We only invalidate caches when a dataset/project is deleted.

Image responses larger than 10 MB currently cannot be cached in the CDN, and are instead returned from the backend servers. However, for all other file types (including videos) we support caching of responses up to 5 TB.

Clients can use standard cache headers such as Cache-Control, If-Modified-Since, If-None-Match, and Accept-Encoding to control cache behavior - for details, see the Google Cloud CDN documentation.

If you run your own CDN or reverse proxy in front of cdn.sanity.io, it requests assets from the asset CDN like any other client. Asset URLs contain a SHA-1 hash of the asset contents, so an edited asset gets a new URL and your cache never serves stale content for it. The following behaviors need attention when you cache asset responses yourself:

• Format negotiation: With auto=format, the Image API picks the format from the Accept header of the requesting client. Forward that header to the asset CDN and key your own cache on it. Without it, the Image API returns the source format, and a cache that ignores it serves one format to every client.
• AVIF encoding: The first few requests for an AVIF-eligible image return the second-best format, because encoding AVIF is slow. A long-lived cache entry created from that first response keeps your users on the second-best format. See AVIF transformations.
• Deleted assets: Deleting an asset does not clear caches that already hold it. Revalidate against the asset CDN, or purge your own cache when you delete an asset.
• Private assets: Switching a Media Library asset from public to private does not clear caches. The asset CDN can keep serving cached responses for up to 30 days after the change, and your own cache extends that window. See Asset visibility.
• Container URLs: A Container URL stays the same while the asset behind it changes version or visibility, so a content change does not produce a new URL. Use a short cache lifetime for these URLs, or purge them when the underlying asset changes.
• Signed URLs: The asset CDN validates the signature on a signed URL and serves only the transformations that the URL pins. Pass these requests through to the asset CDN instead of answering them from your own cache.