Open Graph images: the complete guide

When someone shares a link to your page in a chat app or on a social site, the site reads a few meta tags from your page and shows a card with a title, a line of text, and a picture. That picture is the Open Graph image. A good one makes a link look like something worth opening. A missing one makes the same link look like a plain grey box. This guide covers the size to use, every tag you need, how the sites cache the picture, and how to make a fresh card for every page from one template.

The size: 1200 by 630 pixels

Use an image that is 1,200 pixels wide and 630 pixels tall. That ratio is about 1.91 to 1, and it is the shape that the large card uses on almost every site and app. A smaller image gets scaled up and looks soft. A much larger one costs bytes without a visible gain, and some sites refuse images over a few megabytes.

Keep the words near the middle. Some sites crop the edges to fit a square or a shorter card, so leave about 60 pixels of margin on every side with nothing important in it. Text below about 40 pixels tall is hard to read at the size a phone shows the card.

This is a finished card from the Open Graph card gallery template at 1,200 by 630 pixels.

A light link preview card with a blue top bar, a site name, a large page title, and a description line HTML

HTML for this image

The meta tags

Put these tags in the <head> of every page. The og:image address must be absolute, with https:// and your domain, because the site that reads it has no idea where a relative path points.

<meta property="og:title" content="Plan a client launch in one afternoon" />
<meta
  property="og:description"
  content="A practical workshop for small teams that want one clear story."
/>
<meta property="og:url" content="https://example.com/workshop" />
<meta property="og:type" content="article" />
<meta property="og:image" content="https://example.com/cards/workshop.png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta property="og:image:alt" content="Workshop card with the date and title" />

The width and height tags let a site draw the card before it downloads the picture, so the first share shows the image at once rather than on the second try. The og:image:alt tag gives a screen reader something to say.

The Twitter card tags

X and a few other readers look at twitter: tags first and fall back to og: tags for anything missing. Add these two lines and the rest comes from the Open Graph tags.

<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:image" content="https://example.com/cards/workshop.png" />

summary_large_image asks for the wide card with the picture on top. Without it you get a small square thumbnail beside the title, which crops a 1,200 by 630 image badly.

Caching, and why your new card does not show

Every site that shows cards keeps a copy of your picture. When you change the image and share the link again, you often see the old one. That is the cache, and it can last days or weeks.

The reliable fix is a new address. Put a version in the file name, such as workshop-v2.png, or add a query string that changes when the picture changes, such as ?v=2. A new address is a new image to every cache at once. Most sites also give you a debugger tool that fetches the page again and clears their copy, which is useful for one page but not for a hundred.

Set a long cache header on the image itself, such as Cache-Control: public, max-age=31536000, because the address already changes when the picture changes. Serve it from your own domain or your own storage bucket. Never point og:image at a signed link that expires, because the card breaks the moment the link does.

Make one card for every page

A page that has its own card gets shared more than a page with the site logo. Doing that by hand for every page is the part that people skip. With a template it is one request per page.

Copy the Open Graph card template into your account. It reads a site name, a page title, a description, the page address, and an optional logo. Then, when you publish a page, send its words to POST /v1/image with the template ID and save the result under a name that includes the page and a version.

curl --fail-with-body --silent --show-error https://thirds.ai/v1/image \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: og-card-workshop-v2' \
  --data '{"template_id":"tpl_00000000000000000000000000000000","version":1,"data":{"site_name":"Fieldnote sessions","page_title":"Plan a client launch in one afternoon","description":"A practical workshop for small teams that want one clear story and a reusable launch kit.","site_url":"example.com/workshop"},"image":{"format":"png","width":1200,"height":630},"wait":false}'

Poll GET /v1/image/{id} until status is succeeded, then read download.url, add https://thirds.ai in front of it, and download the PNG within 15 minutes. Save it to your own storage and point og:image at that copy. Each finished card costs one credit, and a failed render costs nothing. The Idempotency-Key makes a retry safe, so a build that runs twice never pays twice for the same page.

If you would rather not save a template, send the card HTML in the html field with {{ }} fields and a data object in the same request. thirds.ai fills the fields and renders without saving anything. Make Open Graph images from HTML shows that path with the full HTML.

Put it in your build

The clean place for this is the step that publishes a page. In a static site build, loop over the pages that changed, send one request each, and write the file into the output folder. In a CMS, run it on the publish hook. In both cases, key the request on the page slug and a hash of the title and description, so an unchanged page never spends a credit and a changed page gets a new address for the cache.

This is the same card idea in the Event promo template, which adds a date block for a page about an event.

A wide event image with a dark date block on the left and blue event details on the right HTML

HTML for this image

For a site with a brand kit, send brand_kit_id with the request and the card takes your colours, logo, and fonts without any change to the template. How to build a brand kit shows how.

Check the result

Open the page in a validator before you share it. Facebook, LinkedIn, and X each have a debugger that shows the card as they will draw it and lists any tag they could not read. Check three things: the image loads from an absolute address, the width and height tags match the file, and the title fits in two lines. Then share the link in a chat app and look at it on a phone, because that is where most people will see it.

Common mistakes

A relative og:image path. The card shows no picture at all.
An image behind a login or a signed link. The crawler cannot fetch it.
Text that runs to the edge. Square crops cut it off.
The same file name after a change. The old card stays in every cache.
No twitter:card tag. X shows a small thumbnail instead of the wide card.
A card with the page's whole first paragraph on it. Nobody reads that at 300 pixels wide.