Como Armazenar Imagens OG em Cache

Armazenar imagens OG em cache significa servir uma prévia social (social preview) gerada anteriormente a partir de uma CDN, em vez de re-renderizá-la a cada compartilhamento. O FastOG armazena imagens idênticas em cache na borda (edge) por um ano — a mesma URL retorna o PNG em cache sem contar contra sua cota e com latência praticamente zero, de modo que a maior parte do tráfego de OG de um site nunca chega ao renderizador.

Por que o cache é importante

Um compartilhamento social aciona uma busca pelo crawler da plataforma. Se cada compartilhamento fosse renderizado novamente, você gastaria cota e latência em conteúdo idêntico. Um cache agressivo — baseado no conteúdo da imagem — transforma "cada compartilhamento conta 1 renderização" em "o primeiro compartilhamento conta 1 renderização, todos os outros são gratuitos."

O modelo baseado em conteúdo que faz isso funcionar

O FastOG usa URLs assinadas por conteúdo: a URL é uma função pura dos parâmetros. Título idêntico + template idêntico → URL idêntica. Isso significa:

A borda do FastOG mantém a imagem sob a URL.
O mesmo conteúdo compartilhado 10.000 vezes → um render, uma contagem de cota, 9.999 acertos de cache.
Altere o conteúdo → URL diferente → um novo render.

GET /api/v1/og?title=Hello&template=default&key=...&s=...   → render (1 quota count), then
GET /api/v1/og?title=Hello&template=default&key=...&s=...   → cached (0 counts, instant)
GET /api/v1/og?title=Changed&template=default&key=...&s=... → render (1 quota count)

Cabeçalhos de cache do FastOG

O FastOG retorna Cache-Control: public, max-age=31536000, immutable (um ano) para imagens renderizadas. Uma capa é servida pela edge do FastOG em duas camadas: o cache de renderização na frente de fastog.com e um armazenamento durável de objetos atrás dele. Buscas repetidas são respondidas sem re-renderização, e X-FastOG-Worker-Cache na resposta indica qual camada respondeu (HIT, R2, MISS).

Como a cópia durável não depende do renderizador, capas que já foram buscadas pelo menos uma vez continuam sendo servidas enquanto o serviço de renderização do FastOG estiver brevemente indisponível — uma interrupção não apaga uma prévia que já foi gerada. Uma capa que nunca foi renderizada antes é o único caso que precisa do renderizador, e nesse caso o FastOG responde com uma imagem em vez de um erro:

Situação	O que um crawler recebe
Capa já renderizada	a capa, da edge ou do armazenamento durável
Nunca renderizada, serviço de renderização ativo	a capa, renderizada sob demanda
Nunca renderizada, serviço de renderização brevemente indisponível	a imagem própria da página carregada na URL (sua foto do produto), ou um card neutro — nunca uma página de erro

Se a própria requisição for inválida (uma assinatura adulterada, um title ausente), você ainda recebe o 4xx correspondente.

Alterando uma imagem que você já publicou

O que você alterou	O que fazer
O conteúdo (título, preço, foto)	nada: o conteúdo está na URL, então o novo conteúdo é uma nova URL e é renderizado do zero
O template ou um padrão de renderização	aumente a versão de cache-bust (`FASTOG_CACHE_BUST`) para que cada URL ganhe um novo parâmetro `v`
Você precisa que a mesma URL seja re-renderizada	peça ao suporte para purgar aquela URL específica — a purga por URL exata não é exposta como um endpoint público

Links que já foram compartilhados continuam funcionando e continuam exibindo a imagem que prometeram, a menos que você purgue aquela URL exata.

Armazenando em cache sua própria og:image (self-hospedado)

Se você armazenar as imagens por conta própria em vez de usar o cache do FastOG, aplique as mesmas regras:

Etapa	Detalhe
Chave de cache = hash do conteúdo	Armazene por um hash dos dados, não por um nome de arquivo mutável
TTL longo	`max-age=31536000, immutable` para conteúdo estável
URLs versionadas	Acrescente um hash/versão quando o conteúdo mudar
CDN na frente	Deixe o CDN absorver as buscas repetidas

FAQ

Compartilhamentos repetidos realmente custam 0 renders?

Sim. URLs idênticas atingem o cache de borda e nunca chegam ao renderizador — nenhuma cota é consumida.

Por quanto tempo o FastOG armazena uma imagem em cache?

Um ano (immutable). Muito tempo após o primeiro render, um card compartilhado é servido a partir do cache.

E se eu quiser que uma imagem seja atualizada (ex.: preço ao vivo)?

Altere um parâmetro (o preço) → nova URL → novo render. Conteúdo estável permanece em cache; conteúdo dinâmico é atualizado quando você quiser.