OGPipe API Documentation

Generate beautiful Open Graph images from templates or custom HTML with a single API call. Images are rendered with Chromium, cached on a global CDN, and served in milliseconds.

Base URL: https://api.ogpipe.dev

Authentication

All requests require an API key passed in the Authorization header.

Authorization: Bearer og_live_your_api_key_here

API keys start with og_live_ followed by 32 hex characters. Get your key at ogpipe.dev.

Quick Start

Generate your first OG image in 30 seconds:

cURL

curl -X POST https://api.ogpipe.dev/images \
  -H "Authorization: Bearer og_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "blog",
    "data": {
      "title": "How We Scaled to 1M Users",
      "author": "Jane Smith",
      "date": "June 2026",
      "site": "acme.dev"
    }
  }'

Node.js

const response = await fetch("https://api.ogpipe.dev/images", {
  method: "POST",
  headers: {
    "Authorization": "Bearer og_live_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    template: "blog",
    data: {
      title: "How We Scaled to 1M Users",
      author: "Jane Smith",
      date: "June 2026",
      site: "acme.dev",
    },
  }),
});

const { url } = await response.json();
// → https://d1234.cloudfront.net/renders/a1b2c3.png

Python

import requests

resp = requests.post(
    "https://api.ogpipe.dev/images",
    headers={"Authorization": "Bearer og_live_your_key"},
    json={
        "template": "blog",
        "data": {
            "title": "How We Scaled to 1M Users",
            "author": "Jane Smith",
            "date": "June 2026",
            "site": "acme.dev",
        },
    },
)

url = resp.json()["url"]

Generate Image

POST/images

Render an OG image from a template or custom HTML. Returns a permanent CDN URL for the generated image.

Request Body

Field	Type	Required	Description
`template`	string	*	Built-in template ID: `blog`, `docs`, `minimal`
`html`	string	*	Raw HTML to render (alternative to template)
`data`	object	No	Key-value pairs to inject into template placeholders
`width`	number	No	Image width in pixels (default: 1200)
`height`	number	No	Image height in pixels (default: 630)
`format`	string	No	Output format: `png`, `jpeg`, `webp` (default: png)

* Provide either template (with optional data) or html. Not both.

Response

200 Success

{
  "url": "https://d1234.cloudfront.net/renders/a1b2c3d4.png",
  "width": 1200,
  "height": 630,
  "format": "png",
  "cached": false
}

400 Bad Request

{
  "error": "Provide either \"template\" (with \"data\") or raw \"html\"."
}

401 Unauthorized

{
  "error": "Missing API key. Include header: Authorization: Bearer og_live_xxxxx"
}

429 Rate Limited

{
  "error": "Monthly limit reached (50 images). Upgrade your plan at ogpipe.dev/pricing"
}

List Templates

GET/templates

Returns all available built-in templates. No authentication required.

200 Success

{
  "templates": [
    { "id": "blog", "description": "Clean blog post card — title, author, date, site name" },
    { "id": "docs", "description": "Documentation page — category badge, title, description, brand" },
    { "id": "minimal", "description": "Just a big title on a colored background" }
  ]
}

Template: Blog

A clean blog post social card with title, author, date, and site name on a dark gradient background.

Variables

Variable	Description	Example
`title`	Post title (main heading)	How We Scaled to 1M Users
`author`	Author name	Jane Smith
`date`	Publication date	June 2026
`site`	Site name / domain	acme.dev

Template: Docs

A documentation-style card with category badge, title, description, and brand. Light background with mono font accents.

Variables

Variable	Description	Example
`category`	Category badge text	API Reference
`title`	Page title	Authentication Guide
`description`	Short description	Learn how to authenticate API requests
`site`	Brand name	Acme Docs

Template: Minimal

A big centered title on a solid colored background. Great for announcements or simple social cards.

Variables

Variable	Description	Example
`title`	The text to display	We just launched!
`background`	CSS background value	#1e40af
`color`	Text color	#ffffff

Custom HTML

Skip templates entirely and provide your own HTML. The entire page is rendered at the specified viewport size and screenshotted.

curl -X POST https://api.ogpipe.dev/images \
  -H "Authorization: Bearer og_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<!DOCTYPE html><html><body style=\"width:1200px;height:630px;display:flex;align-items:center;justify-content:center;background:#000;color:#fff;font-size:48px;font-family:sans-serif\">Hello OGPipe</body></html>",
    "width": 1200,
    "height": 630
  }'

Tip: Your HTML should set explicit width and height on the body to match your requested dimensions. Web fonts from Google Fonts and other CDNs are supported.

Rate Limits

Usage is tracked monthly per API key. Limits reset on the 1st of each month (UTC).

Plan	Monthly Renders	Price
Free	50	$0
Pro	5,000	$19/mo
Scale	25,000	$49/mo
Enterprise	Unlimited	Contact us

When you hit your limit, the API returns 429 with a message indicating how to upgrade.

Caching

Images are cached deterministically. The same input (HTML + dimensions + format) always produces the same cache key. This means:

Repeated requests with identical input return the same URL instantly
Images are stored for 30 days on S3 with a CloudFront CDN in front
CloudFront serves cached images globally with sub-50ms latency

Note: The cached field in the response indicates whether the image was rendered fresh (false) or served from cache (true). Both return the same URL.

Error Handling

All errors return a JSON body with an error field:

Status	Meaning	Resolution
400	Bad request — invalid input	Check request body format and required fields
401	Missing or invalid API key	Include a valid `Authorization: Bearer og_live_xxx` header
429	Monthly limit exceeded	Upgrade your plan or wait for monthly reset
500	Render failed	Check your HTML for errors. If persistent, contact support.