OG Images

Open Graph (OG) images are the preview cards that appear when you share a link on social media, Slack, Discord, or messaging apps. PixDoc lets you generate these images dynamically from templates so every page on your site gets a unique, branded preview card without manual design work.

How It Works

OG images are served via a GET endpoint. You create a template with placeholder variables, then pass those variables as URL query parameters. PixDoc renders the HTML template as a 1200x630 PNG image, the standard OG image size.

GET /api/v1/og/{template-slug}?key={api-key}&title=...&author=...

The response is a PNG image served directly. No JSON wrapper. This means you can use the URL directly in your HTML meta tags.

Template Design Guidelines

OG images are rendered at a fixed 1200x630 pixels. Your template HTML should be designed to fit these dimensions. Set the outermost container to width:1200px;height:630px for best results.

Not all templates are suitable for OG images. Document-style templates (invoices, pay stubs, certificates) are designed for A4/Letter pages and will appear cropped or poorly scaled at 1200x630. For OG images, design templates specifically as landscape social cards with large text and simple layouts.

Creating an OG Template

Templates are HTML snippets with {{variable}} placeholders. You can create them through the dashboard or the API.

curl -X POST https://pixdoc.dev/api/v1/templates \
-H "Authorization: Bearer pd_live_a3b2c4d5..." \
-H "Content-Type: application/json" \
-d '{
  "name": "blog-card",
  "display_name": "Blog Card",
  "html": "<div style=\"width:1200px;height:630px;display:flex;flex-direction:column;justify-content:flex-end;padding:60px;background:linear-gradient(135deg,#667eea,#764ba2);font-family:system-ui;color:white;\"><h1 style=\"font-size:52px;font-weight:800;margin:0 0 24px 0;\">{{title}}</h1><p style=\"font-size:18px;opacity:0.9;\">By {{author}}</p></div>",
  "defaults": {
    "title": "My Blog Post",
    "author": "Jane Doe"
  }
}'

Variables are automatically detected from your HTML. Any {{variableName}} pattern in the HTML body is extracted and stored with the template.

URL Parameter Format

Once your template exists, generate OG images with a GET request:

GET /api/v1/og/{template-slug}?key={api-key}&title=Hello%20World&author=Jane%20Doe

Reserved parameters:

Parameter	Purpose
`key`	Your API key (required)
`v`	Pin a specific template version (e.g. `v=3`). If omitted, the latest version is used. Also serves as a cache-busting mechanism — changing the value invalidates cached images.
`no_cache`	Set to `1` to skip the cache and force a fresh render

All other query parameters are treated as template variables and substituted into the HTML.

Remember to URL-encode parameter values. Spaces become %20, ampersands become %26, and so on.

Caching

OG images are cached to reduce rendering costs and improve performance:

Cache key: generated from your user ID, template slug, all variable values, and the optional v parameter
Cache hits: return the image with an X-Cache: HIT header
Cache misses: render the image, cache it, then return with X-Cache: MISS
CDN caching: responses include Cache-Control: public, max-age=86400 (24 hours)
Render counting: only cache misses count toward your monthly render limit

Cache Invalidation

To clear the cache for a template, call the invalidation endpoint:

curl -X POST https://pixdoc.dev/api/v1/og/invalidate \
-H "Authorization: Bearer pd_live_a3b2c4d5..." \
-H "Content-Type: application/json" \
-d '{"template_name": "blog-card"}'

You can also bust the cache for a specific combination of variables by changing the v parameter in the URL.

Using OG Images in Your HTML

Add these meta tags to the <head> of each page on your site:

<head>
  <meta property="og:image" content="https://pixdoc.dev/api/v1/og/blog-card?key=pd_live_a3b2c4d5...&title=My%20Post&author=Jane%20Doe" />
  <meta property="og:image:width" content="1200" />
  <meta property="og:image:height" content="630" />
  <meta name="twitter:card" content="summary_large_image" />
  <meta name="twitter:image" content="https://pixdoc.dev/api/v1/og/blog-card?key=pd_live_a3b2c4d5...&title=My%20Post&author=Jane%20Doe" />
</head>

Include both og:image and twitter:image meta tags for maximum compatibility across platforms.

Common Patterns

Blog Posts

Use a template with title, author, date, and category variables. PixDoc includes a pre-built blog-post template you can use immediately.

<meta property="og:image"
  content="https://pixdoc.dev/api/v1/og/blog-post?key=pd_live_...&title=Building%20APIs&author=Jane%20Doe&date=March%202026&category=Engineering" />

Product Pages

Create a template with product_name, price, and tagline variables for consistent product cards across your catalog.

<meta property="og:image"
  content="https://pixdoc.dev/api/v1/og/product-card?key=pd_live_...&product_name=Widget%20Pro&price=$49&tagline=Built%20for%20developers" />

Event Cards

Use event_name, date, location, and speaker variables for conference talks, meetups, or webinars.

<meta property="og:image"
  content="https://pixdoc.dev/api/v1/og/event-card?key=pd_live_...&event_name=DevConf%202026&date=April%2015&location=San%20Francisco&speaker=Jane%20Doe" />

Image Specifications

Property	Value
Default width	1200px
Default height	630px
Format	PNG
Device scale factor	1x (configurable up to 3x)
Render timeout	15 seconds