An OG image API for your own HTML templates

From an HTML template to a 1200 × 630 PNG

An OG image is the picture that shows when a link is shared. You design the card once in HTML and CSS, fill in the title of each page, and the API returns the image at exactly the size of the window you set.

Use it from Next.js metadata

Render the card when a post is published or edited, save the file with your other images, and point the metadata at it. Do not point og:image at the API itself: a POST request cannot be a plain link, and files kept by the API are removed after a while.

export async function renderOgCard(title: string): Promise<Buffer> {
  const response = await fetch('https://curlshot.com/api/v1/screenshot', {
    method: 'POST',
    headers: { 'X-Access-Key': process.env.SCREENSHOT_ACCESS_KEY!, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      html: cardHtml(title), // your template; escape the title
      viewport_width: 1200,
      viewport_height: 630,
      cache: true,
      cache_key: 'card-v1',
    }),
  })
  if (!response.ok) throw new Error((await response.json()).error_message)
  return Buffer.from(await response.arrayBuffer()) // save as public/og/<slug>-<hash>.png
}

export async function generateMetadata({ params }: { params: { slug: string } }): Promise<Metadata> {
  const post = await getPost(params.slug)
  return {
    title: post.title,
    openGraph: { images: [{ url: post.ogImage, width: 1200, height: 630, alt: post.title }] },
    twitter: { card: 'summary_large_image' },
  }
}

Caching and updating cards

Two caches matter: the one in the API, and the copy each social network keeps of your image.

• With cache=true, the same HTML returns the stored card for free. A changed title is different HTML, so it gets a new card without any work on your side.
• Cached copies live 4 hours by default; cache_ttl sets up to 30 days.
• Swapped a logo or a font that the HTML only links to? Change cache_key from card-v1 to card-v2 and every card renders fresh.
• Social networks keep their own copy for a long time. Save each new card under a new file name, for example with a short hash of the title, so they fetch it again.