Blog heroes

Hero images for article pages. Wider than OG — ideal for above-the-fold banners on long-form posts.

Endpoint

GET /hero/{publicId}?url={pageUrl}&aspectRatio=16:9

Returns a PNG directly, same as OG images. All style and AI query parameters are identical; the only new one is aspectRatio.

Aspect ratios

Default is 16:9. Pick 16:10 when your layout has a wider hero slot.

Cache

Cache-Control: public, max-age=86400, s-maxage=2592000 — 30-day edge cache (longer than OG, since blog covers rarely change).

Next.js app router example

// app/blog/[slug]/page.tsx
import Image from "next/image";
 
export default async function Post({ params }: { params: { slug: string } }) {
  const pageUrl = `https://example.com/blog/${params.slug}`;
  const hero = `https://api.ogstack.dev/hero/${process.env.OGSTACK_PUBLIC_ID}?url=${encodeURIComponent(pageUrl)}&aspectRatio=16:9`;
 
  return (
    <article>
      <Image src={hero} alt="" width={1600} height={900} priority />
      <h1>{/* ... */}</h1>
    </article>
  );
}

Markdown front matter pattern

If your static site reads cover images from front matter, skip hardcoding a URL — build it from the slug:

// in your build step
const cover = `https://api.ogstack.dev/hero/${PUBLIC_ID}?url=${encodeURIComponent(pageUrl)}&template=panorama`;

Use the API for batch builds

If you’re pre-rendering hundreds of posts at build time, prefer server-side generation with an API key. You get back a stable CDN URL you can cache as a build artifact, avoiding re-scrape traffic on every build.