Image Delivery#

HTMLPix serves images through signed URLs on Cloudflare's edge network. Here's how the flow works.

The flow#

  1. Your backend calls POST /v1/url to mint a signed URL.
  2. You place the URL in your page's <meta property="og:image"> tag.
  3. When a crawler or browser requests the URL, the image is rendered and cached at the edge.
  4. Subsequent requests for the same URL are served directly from cache.

Why signed URLs#

  • API keys stay private — only your backend talks to the minting API.
  • URLs are crawler-safe — no auth needed to fetch the image.
  • CDN-friendly — deterministic URLs map to consistent cache keys.
  • Billing at mint time — you know your costs upfront. Fetches are free.

Response headers#

Successful image responses include:

HeaderDescription
Cache-Controlpublic, max-age=86400 (24 hours)
ETagContent hash for conditional requests
X-Cacher2 (served from cache) or render (freshly rendered)
Server-TimingRender duration in ms (fresh renders only)

Cache invalidation#

Signed URLs are long-lived (5 years by default). To invalidate the cache after updating a template:

  • Mint new URLs — updated templates get a new tv (template version) parameter, which creates a different cache key.
  • Old URLs continue to serve the previous version until they expire.