What size should an OG image be?

The 1200x630 PNG matches the ogp.me recommendation. The same size works for Twitter summary_large_image, LinkedIn, Slack, and Discord unfurls. Anything smaller than 600x315 may not display on Facebook, so 1200x630 is the safest default.

How do I add it to my page?

Set in the page head, with og:image:width and og:image:height alongside it. For Twitter, also add twitter:card and twitter:image to enable the large card variant.

Why is my new image not showing on Facebook?

Facebook caches OG images by URL aggressively. Refresh via the Sharing Debugger to re-scrape the page, or change the og:image URL itself by appending a query string when the underlying content changes. The cache typically clears within an hour after a refresh.

Will Twitter pick this up?

Yes, Twitter falls back to OG tags if Twitter-specific tags are missing. For richer cards, also add twitter:card with the value summary_large_image and twitter:image with the same URL. The unfurl shows a full-width image below the post text.

Does it support color emoji?

Yes, the renderer handles color emoji in titles and subtitles through the system font fallback. Use emoji for genuinely playful content rather than as a substitute for clear copy. Most teams reserve emoji for very specific page types.

What is the maximum file size?

Facebook caps OG images at 8 MB. Default-DPI renders from this template land between 60 KB and 180 KB, well under the cap. For 2x DPI versions, monitor the size since the file can climb quickly with photographic backgrounds.

social template

Open Graph Image API

Send page title and metadata as JSON, get back a 1200x630 PNG sized for og:image tags.

Get started free Read the Open Graph Image API reference

Prefer to try it in your browser first? Open the Open Graph Image tool.

Open Graph Image template preview, a social image generated by the HTML to Image API

Marketing engineers and content tools use the Open Graph Image API to ship a unique share card for every page on a site without booking design time per URL. The 1200x630 ratio is the ogp.me recommendation, and the same file unfurls cleanly on Facebook, LinkedIn, Slack, Discord, and X. You post the title, subtitle, and brand details as JSON, and the response holds a PNG you can reference from the og:image meta tag in the page head.

API reference

View the Open Graph Image API reference

Inputs, defaults, error responses and cURL, PHP, Node and Python code samples.

Read the docs →

Use cases

Blogs auto-generating per-post OG images

Editorial sites with hundreds of posts cannot design a unique OG card for every URL. Hook the publishing flow into a webhook, post the title and category to the endpoint, and store the URL as the post's og_image meta. New posts get fresh share artwork on first publish, and historical posts can be backfilled with a single migration script. Northwind Weekly backfilled 1,400 archived posts in 11 minutes through this pipeline.

SaaS marketing pages with dynamic share cards

A pricing page, a feature page, and a docs landing all benefit from individual OG cards rather than one stock site image. Render at build time during your Next.js or Astro build, cache the URL on the page, and the same card serves every share without runtime calls. Halberd Software produces 80 OG variants per release and the marketing site's social click-through rate climbed 35 percent after the rollout.

Documentation sites with per-page OG previews

Doc pages benefit from share previews that show the topic rather than a generic logo. Render once per page during the build, embed in the head, and Algolia DocSearch results that surface in chat unfurl with a card matching the actual content. Wren Analytics' API reference renders one OG card per endpoint and the doc site sees 12 percent more shares from inside customer Slacks.

Link-in-bio tools

Linktree-style platforms that aggregate creator links benefit from OG cards that reflect the creator's brand rather than the platform's. Render with the creator's name, accent_color, and avatar, and the share card shows their identity rather than a generic platform logo. Linden & Co built this for 2,400 creators on its bio platform, and creator referrals grew because shared links unfurl with the creator's branding.

AI-generated content platforms branding shared output

AI tools that produce content for users (essays, summaries, briefs) benefit from share cards that show the user's prompt or topic. Generate one OG card per output, attached to the public URL, and the shared content carries identifying context rather than a generic platform name. Riverside Bakery's recipe generator uses this for every saved recipe URL.

Output specifications

Dimensions: 1200x630
Color space: sRGB
Transparency: Not supported
File size range: 60 KB to 180 KB

Matches the spec at Open Graph Protocol image specification.

How it works

Send a JSON payload

POST to the template endpoint with the values you want rendered. Authenticate with your API key.

We render the image

The template is rendered server-side as a 1200x630 PNG.

You get back a URL

Cache it, embed it in your page, attach it to an email.

Quick example

A single cURL call to render a Open Graph Image as a PNG:

curl -X POST https://app.html2img.com/api/v1/templates/open-graph-image \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"How to ship faster","subtitle":"A guide for engineering teams","author_name":"html2img.com","background_color":"#0F172A","accent_color":"#3B82F6"}'

For the full PHP, Node and Python equivalents, plus every input the template accepts, see the Open Graph Image API reference. Setting up your key is covered in the authentication guide.

Common pitfalls

Facebook caches OG images aggressively

You update the OG image but Facebook still shows the previous render for hours. Force a refresh with the Sharing Debugger by re-scraping the URL, or change the og:image URL itself by appending a cache-busting query string when content changes.

Images over 8 MB rejected by Facebook

Hi-DPI renders at 2x or 3x can exceed Facebook's file-size cap, and Facebook silently falls back to a generic preview. Keep the rendered file under 8 MB by sticking with default DPI and letting compression do the work.

Missing og:image:width and og:image:height tags

Some platforms fall back to a generic preview when only og:image is present. Add og:image:width and og:image:height meta tags with 1200 and 630 alongside the image URL, so platforms reserve the right space immediately during the unfurl.

Inputs at a glance

A quick summary of what the Open Graph Image template accepts. The full reference, with example values and array shapes, is in the docs.

Name	Type	Required
title	string	Required
subtitle	string	Optional
author_name	string	Optional
author_avatar_url	url	Optional
logo_url	url	Optional
background_color	string	Optional
accent_color	string	Optional