An Open Graph image is the picture that appears when someone shares your link on Slack, LinkedIn, WhatsApp, X or iMessage. It is, for most people, the only part of your page they see before deciding whether to click — and most sites ship one generic image for every URL, which makes every share look identical and anonymous.
The tags that matter
<meta property="og:title" content="PDF to HTML API — Convert PDF to Clean HTML">
<meta property="og:description" content="Headings, tables and lists preserved.">
<meta property="og:image" content="https://www.ashdocs.com/og/pdf-to-html.png">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:alt" content="PDF to HTML API">
<meta name="twitter:card" content="summary_large_image">
1200×630 is the safe size — roughly 1.91:1, which is what most platforms crop toward. Declaring width and height lets platforms lay out the preview before the image finishes downloading, which reduces the "link posted with no picture" effect on the first share.
Three ways to produce them
By hand in a design tool. Fine for a five-page site. It stops scaling the moment you have a blog, and the images drift out of sync with titles you later edit.
Screenshot the page. Capture the rendered page and use that as the card. Genuinely good for dashboards, docs pages and anything visual, because the preview shows the real thing:
curl -X POST https://www.ashdocs.com/api/v1/tools/screenshot \
-H "X-API-Key: ash_live_..." \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/pricing",
"options":{"viewport":{"width":1200,"height":630},"scale":2,
"block_ads":true,"wait_for":"networkidle",
"hide_selectors":[".cookie-banner"]}}'
Two things make or break this: waiting for the page to actually finish rendering, and hiding cookie banners and chat widgets — otherwise every social card you generate features a consent dialog. The Screenshot API handles both.
Render from a template. For text-heavy pages, a designed card beats a screenshot: your title, an eyebrow label, your logo, on brand colours.
curl -X POST https://www.ashdocs.com/api/v1/tools/og-image \
-H "X-API-Key: ash_live_..." \
-H "Content-Type: application/json" \
-d '{"template":"basic",
"fields":{"eyebrow":"GUIDE","title":"Static vs Dynamic QR Codes",
"logo_url":"https://example.com/logo.svg"}}'
The OG Image API renders the card server-side and shrinks the title automatically when it's long — the detail that separates a working template from one that overflows on your best headline.
Generate ahead or on demand?
Ahead of time, at build or publish: the image is a static file, serving costs nothing, and social crawlers never wait. The trade is a build step and stale images if you edit titles without regenerating.
On demand, at request time behind a cache: /og?title=... renders once, then serves from cache. Always current, no build step. The trade is a live dependency in a path that crawlers hit — so cache aggressively and keep a static fallback for when rendering fails.
Either way, put the image URL under version control of some kind: include a content hash or a ?v= parameter that changes when the title changes. Platforms cache aggressively, and without a changed URL your old card can persist long after the page is updated.
Common failures
A relative og:image path — the tag needs an absolute URL. An image behind authentication, so crawlers get a login page. Missing width and height. Text placed near the edges, then cropped by a platform with a different aspect ratio. And forgetting og:image:alt, which is free accessibility.
Always run a new template through the share debuggers of the platforms you care about before rolling it out site-wide — they show you exactly what was fetched and cached.
FAQ
What size should an Open Graph image be? 1200×630 pixels. It suits the ~1.91:1 ratio most platforms crop toward and stays sharp on high-density screens.
Can I generate OG images automatically for every page? Yes — render them from a template with the page title, or screenshot the page itself, either at build time or on demand behind a cache.
Why isn't my new image showing when I share the link? Platform caching. Change the image URL (add a version parameter) and re-scrape with the platform's share debugger.
Screenshot or designed template? Screenshot when the page itself is the selling point — dashboards, visual tools. Template when the page is mostly text, so the title carries the card.
Get an API key — 100 credits free, no card required.