/v1/og

Generate dynamic Open Graph images using built-in templates.

GET https://api.urlpix.com/v1/og

Plan Requirement

OG image generation requires a Pro plan or higher.

Parameters

Parameter	Type	Default	Range	Required	Description
template	string	—	See templates	Yes	Template name
format	string	png	png, jpg, webp	No	Output format (no PDF)
width	integer	1200	100–4096	No	Canvas width
height	integer	630	100–4096	No	Canvas height
quality	integer	80	1–100	No	JPEG/WebP quality
response	string	—	json	No	Return JSON metadata
api_key	string	—	—	No	API key (alternative to header)

All additional query parameters are passed as template variables. See Templates for available variables per template.

Variable Types

Type	Format	Example
text	URL-encoded string	title=Hello%20World
color	Hex, RGB, or HSL	bgColor=%23ff0000
image_url	HTTPS URL only	avatar=https://example.com/photo.jpg

List Variables

Variables ending in _items accept newline-separated values (URL-encoded as %0A) and are rendered as lists in templates. Maximum 20 items.

change_items=Added%20dark%20mode%0AFixed%20login%20bug%0AUpdated%20docs

Examples

curl

# Default template
curl "https://api.urlpix.com/v1/og?template=default&title=Hello%20World&description=My%20awesome%20page" \
  -H "X-API-Key: sk_live_YOUR_KEY" \
  -o og.png

# Blog post with author
curl "https://api.urlpix.com/v1/og?template=blog-post&title=Getting%20Started%20with%20URLPix&author=John%20Doe&accent=%236366f1" \
  -H "X-API-Key: sk_live_YOUR_KEY" \
  -o blog-og.png

# Stats card
curl "https://api.urlpix.com/v1/og?template=stats-card&title=Dashboard&stat1_number=100K&stat1_label=Users&stat2_number=99.9%25&stat2_label=Uptime" \
  -H "X-API-Key: sk_live_YOUR_KEY" \
  -o stats.png

JavaScript (fetch)

const params = new URLSearchParams({
  template: 'blog-post',
  title: 'My Blog Post',
  author: 'Jane Doe',
  format: 'png',
})

const response = await fetch(
  `https://api.urlpix.com/v1/og?${params}`,
  { headers: { 'X-API-Key': 'sk_live_YOUR_KEY' } }
)

const blob = await response.blob()

Node.js

import fs from 'fs'

const params = new URLSearchParams({
  template: 'changelog-card',
  version: 'v2.1.0',
  date: '2026-03-10',
  change_items: 'Added dark mode\nFixed login bug\nUpdated docs',
  format: 'png',
})

const response = await fetch(
  `https://api.urlpix.com/v1/og?${params}`,
  { headers: { 'X-API-Key': process.env.URLPIX_API_KEY } }
)

const buffer = Buffer.from(await response.arrayBuffer())
fs.writeFileSync('changelog.png', buffer)

Error Responses

Status	Description
400	Missing template, invalid format, invalid variable, or template not found
401	Missing or invalid API key
403	Plan does not support OG generation (requires Pro+)
502	Renderer unavailable
504	Render timeout (>15s)

Caching

OG images are cached using the same TTL rules as screenshots. The cache key is derived from: template, all template variables, format, quality, width, and height.