Dynamic OG Images in Astro

On-demand: add an Astro API endpoint

For an Astro project using server or hybrid output, create src/pages/api/og.ts. The key remains in import.meta.env.OGSHOT_API_KEY, which must not use the PUBLIC_ prefix. The endpoint streams the card and adds a cache header suitable for repeated crawler requests.

import type { APIRoute } from "astro"; export const GET: APIRoute = async ({ url }) => { const title = (url.searchParams.get("title") || "Untitled").slice(0, 90); const site = (url.searchParams.get("site") || "example.com").slice(0, 60); const query = new URLSearchParams({ title, site, author: "Your team" }); const image = await fetch(`https://ogshot.dev/v1/template/article?${query}`, { headers: { "x-api-key": import.meta.env.OGSHOT_API_KEY }, }); if (!image.ok) return new Response("OG render failed", { status: 502 }); return new Response(image.body, { headers: { "content-type": image.headers.get("content-type") || "image/png", "cache-control": "public, max-age=86400, stale-while-revalidate=604800", }, }); };

Point the document head at the endpoint

A reusable SEO component should receive the page title, description, and canonical URL. Astro escapes attribute values, while URLSearchParams handles the query encoding.

--- const { title, description } = Astro.props; const query = new URLSearchParams({ title, site: Astro.site.hostname }); const image = new URL(`/api/og?${query}`, Astro.site); --- <title>{title}</title> <meta name="description" content={description} /> <meta property="og:title" content={title} /> <meta property="og:description" content={description} /> <meta property="og:image" content={image} /> <meta property="og:image:width" content="1200" /> <meta property="og:image:height" content="630" /> <meta name="twitter:card" content="summary_large_image" />

Static sites: create signed URLs during the build

A fully static Astro deployment cannot run an API route after deployment. Instead, use the signing id and signing secret from the ogshot dashboard in build-time server code. Generate a signed template URL for each page and write only the finished URL into HTML. The signature prevents visitors from changing the title, dimensions, or other parameters.

The signed URL documentation includes the complete Node implementation. Store both signing values in the build environment, never in a PUBLIC_ variable or client-side component. When content changes, the new build creates a new signed request and therefore a new cached card.

Map content collection fields consistently

Define a small card contract—usually title, author, site, accent, and optional logo—and derive it from each collection entry. Keep title length constraints in the content schema so unusually long headings do not create unpredictable typography. For custom editorial art direction, add frontmatter fields such as ogTemplate, ogAccent, or ogImage and pass them only to templates that support those parameters.

Use one component for both Open Graph and Twitter metadata. A single canonical image URL avoids two crawlers producing different cache keys for the same page.

Verify before publishing the link

Deploy one representative article with a short title, one with a long title, and one containing punctuation or emoji. Paste each URL into the ogshot inspector to confirm that the final tags, image response, dimensions, and platform crops are correct. The inspector needs no account and does not alter the page.

Related guides: Next.js App Router, Hugo, and real Chromium compared with Satori.

Turn Astro frontmatter into a card people want to open.

On-demand: add an Astro API endpoint

Point the document head at the endpoint

Static sites: create signed URLs during the build

Map content collection fields consistently

Verify before publishing the link

Render the first collection entry free.