---
title: "Open Graph Image API: Render Dynamic OG PNGs from JSON"
description: "Generate share-ready OG cards using the Open Graph Image API. Send the page title, subtitle, and brand inputs as JSON, get back a 1200x630 PNG."
url: "https://html2img.com/templates/open-graph-image/"
---

# Open Graph Image API

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

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.

## At a glance

- **Template slug:** `open-graph-image`
- **Category:** social
- **Endpoint:** `POST https://app.html2img.com/api/v1/templates/open-graph-image`
- **Authentication:** `X-API-Key` header
- **Cost:** one credit per render, PNG or PDF
- **Page:** https://html2img.com/templates/open-graph-image/

## Fields

| Field | Type | Required | Example |
| --- | --- | --- | --- |
| `title` | string | Yes | How to ship faster |
| `subtitle` | string | No | A guide for engineering teams |
| `author_name` | string | No | html2img.com |
| `author_avatar_url` | url | No |  |
| `logo_url` | url | No |  |
| `background_color` | string | No | #0F172A |
| `accent_color` | string | No | #3B82F6 |

## Defaults

| Field | Default |
| --- | --- |
| `width` | 1200 |
| `height` | 630 |

## Example request

```bash
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"}'
```

## In your language

### PHP

```php
<?php
$response = \Illuminate\Support\Facades\Http::withHeaders([
    'X-API-Key' => 'YOUR_API_KEY',
])->post('https://app.html2img.com/api/v1/templates/open-graph-image', ['title' => 'How to ship faster', 'subtitle' => 'A guide for engineering teams', 'author_name' => 'html2img.com', 'background_color' => '#0F172A', 'accent_color' => '#3B82F6']);

$url = $response->json('url');
```

### Node.js

```javascript
const response = await fetch('https://app.html2img.com/api/v1/templates/open-graph-image', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "title": "How to ship faster",
    "subtitle": "A guide for engineering teams",
    "author_name": "html2img.com",
    "background_color": "#0F172A",
    "accent_color": "#3B82F6"
}),
});

const { url } = await response.json();
```

### Python

```python
import requests

response = requests.post(
    'https://app.html2img.com/api/v1/templates/open-graph-image',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    json={'title': 'How to ship faster', 'subtitle': 'A guide for engineering teams', 'author_name': 'html2img.com', 'background_color': '#0F172A', 'accent_color': '#3B82F6'},
)

url = response.json()['url']
```

## What it is for

### 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

- **Dimensions:** 1200x630
- **Colour space:** sRGB
- **Transparency:** Not supported
- **Typical file size:** 60 KB to 180 KB
- **Platform specification:** [Open Graph Protocol image specification](https://ogp.me/)

## Common mistakes

### 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.

## Questions

### 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 <meta property="og:image" content="YOUR_URL"> 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. The og:image tag itself always takes the PNG URL; format: "pdf" exists on the endpoint but suits proofing rather than meta tags.

## Preview

![Open Graph Image API example render](https://i.html2img.com/image-1777560076848-485083.png)

## Related templates

- [instagram-square-post](https://html2img.com/templates/instagram-square-post/)
- [twitter-post](https://html2img.com/templates/twitter-post/)
- [youtube-thumbnail](https://html2img.com/templates/youtube-thumbnail/)

## See also

- [Every template](https://html2img.com/templates/)
- [Templates API reference](https://html2img.com/docs/templates/)
- [OpenAPI specification](https://html2img.com/openapi.json)