OGForge API Documentation

OGForge generates Open Graph images on the fly. Pass a title and optional parameters via a simple GET request, and receive a 1200×630 PNG image ready for social sharing. The API is completely free — no API keys, no authentication, no signup required.

Base URL: https://ogforge.dev/api/v1

Authentication

No authentication is required. The API is free and open for everyone. Simply make HTTP requests to the endpoints below.

GET /og

GET /api/v1/og

Generate an Open Graph image. Returns a 1200×630 PNG (or SVG) image based on the provided parameters. Use the returned URL directly as your og:image meta tag value.

Query Parameters

Param	Type	Required	Description
`title`	string	required	Primary text displayed on the image (max 200 characters)
`subtitle`	string	optional	Secondary text below the title (max 300 characters)
`theme`	string	optional	Color theme: `dark` (default), `light`, `gradient`, `cyberpunk`
`icon`	string	optional	Icon shortcode from the Lucide icon set (e.g., `rocket`, `star`, `code`). Renders as a vector icon above the title. Supports all 1,668 Lucide icons. See GET /icons for the curated catalog. Max 10 characters.
`brand`	string	optional	Brand text in the bottom bar (default: ogforge.dev, max 50 characters)
`accent`	string	optional	Accent color as 6-character hex without `#` (e.g., `ff00aa`)
`format`	string	optional	Output format: `png` (default) or `svg`

Example Request

          
          cURL
        
# Generate a simple OG image
curl "https://ogforge.dev/api/v1/og?title=My+Blog+Post" --output og.png

# With subtitle and cyberpunk theme
curl "https://ogforge.dev/api/v1/og?title=Hello+World&subtitle=A+developer+blog&theme=cyberpunk" -o og.png

Response

Returns a binary image/png (or image/svg+xml with format=svg) with the following headers:

Header	Value
`Content-Type`	`image/png` or `image/svg+xml`
`Cache-Control`	`public, max-age=86400`
`X-OGForge-Theme`	The theme used for generation

Usage in HTML

          
          HTML
        
<!-- Drop this in your <head> -->
<meta property="og:image" content="https://ogforge.dev/api/v1/og?title=My+Blog+Post&theme=dark" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />

GET /themes

GET /api/v1/themes

List all available themes.

Example Response

          
          
          
          200 OK
        
{
  "themes": ["dark", "light", "gradient", "cyberpunk"],
  "default": "dark",
  "description": "Use the theme parameter in /api/v1/og to select a theme"
}

GET /icons

GET /api/v1/icons

List all curated icon shortcodes organized by category. Use these shortcodes as the icon parameter in /api/v1/og. Any valid Lucide icon name is also supported beyond this curated list.

Example Response

          
          
          
          200 OK
        
{
  "categories": {
    "development": [
      { "shortcode": "code", "emoji": null, "description": "Code brackets" },
      { "shortcode": "rocket", "emoji": "\ud83d\ude80", "description": "Rocket" },
      ...
    ],
    "content": [...],
    "status": [...],
    "engagement": [...],
    "technology": [...],
    "arrows": [...]
  },
  "total": 80,
  "usage": "Use the shortcode as the icon parameter in /api/v1/og.",
  "docs": "https://lucide.dev/icons"
}

Icons Reference

OGForge renders icons as crisp vector graphics using the Lucide icon set (MIT licensed). Icons render in the accent color as stroke-based outlines at the top of your OG image.

How to Use Icons

          
          examples
        
# Rocket icon
/api/v1/og?title=Launch+Day&icon=rocket

# Star icon with gradient theme
/api/v1/og?title=Featured&icon=star&theme=gradient

# Code icon with custom accent
/api/v1/og?title=Developer+Blog&icon=code&accent=39ff14

# Shield icon for security posts
/api/v1/og?title=Security+Update&icon=shield&theme=cyberpunk

Popular Icons by Category

Category	Shortcodes
Development	`code`, `terminal`, `bug`, `rocket`, `zap`, `database`, `server`, `git-branch`, `shield`, `cpu`
Content	`file-text`, `book-open`, `camera`, `pencil`, `link`, `globe`, `mail`, `message-circle`, `rss`
Status	`check`, `x`, `alert-triangle`, `info`, `bell`, `clock`, `calendar`, `eye`
Engagement	`heart`, `star`, `flame`, `trophy`, `sparkles`, `target`, `crown`, `gem`
Technology	`monitor`, `smartphone`, `laptop`, `wifi`, `chart-line`, `search`, `layers`
Arrows	`arrow-right`, `arrow-up`, `chevron-right`, `external-link`, `maximize`

All 1,668 Lucide icons are supported. Use any icon name from lucide.dev/icons as the icon parameter. If an unrecognized name is used, it falls back to a text badge.

Response Format

The /og endpoint returns binary image data (PNG or SVG). The /themes endpoint returns JSON. Error responses are always JSON with error and message fields.

Error Response

          
          
          
          400 Bad Request
        
{
  "error": "Invalid parameters",
  "message": "Missing required parameter: title",
  "usage": {
    "endpoint": "GET /api/v1/og",
    "required": { "title": "Primary text (max 200 chars)" },
    "optional": { ... },
    "example": "/api/v1/og?title=My+Blog&subtitle=A+developer+blog&theme=dark"
  }
}

Error Codes

Status	Meaning
`400`	Bad Request — Missing or invalid parameters (title, theme, accent, format)
`404`	Not Found — Endpoint does not exist
`429`	Too Many Requests — Rate limit exceeded
`500`	Internal Server Error — Image generation failed

Rate Limits

The API applies rate limiting to protect service quality:

Limit	Value
Requests per minute	`30` per IP address
Window	`60 seconds` sliding window

When rate limited, the API returns a 429 status with a Retry-After header.

Rate limit headers are included in every response: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset.

cURL Examples

          
          terminal
        
# Simple OG image
curl "https://ogforge.dev/api/v1/og?title=Hello+World" -o og.png

# With subtitle and theme
curl "https://ogforge.dev/api/v1/og?title=My+Blog&subtitle=Dev+thoughts&theme=gradient" -o og.png

# Custom accent color
curl "https://ogforge.dev/api/v1/og?title=Launch+Day&accent=ff6600&brand=myapp.dev" -o og.png

# SVG format
curl "https://ogforge.dev/api/v1/og?title=Vector+Image&format=svg" -o og.svg

# List available themes
curl "https://ogforge.dev/api/v1/themes"

JavaScript Example

          
          
          
          app.js
        
// Use as an og:image URL in your HTML
const title = encodeURIComponent('My Blog Post');
const ogUrl = `https://ogforge.dev/api/v1/og?title=${title}&theme=dark`;
// Set as <meta property="og:image" content="${ogUrl}" />

// Download the image as a file
const response = await fetch(
  'https://ogforge.dev/api/v1/og?title=Hello+World&theme=cyberpunk'
);
const blob = await response.blob();
const url = URL.createObjectURL(blob);
// Use url for preview, download, etc.

// List available themes
const themes = await fetch('https://ogforge.dev/api/v1/themes');
const data = await themes.json();
console.log(data.themes); // ["dark","light","gradient","cyberpunk"]

Python Example

          
          
          
          main.py
        
import requests

# Generate and save an OG image
response = requests.get(
    'https://ogforge.dev/api/v1/og',
    params={
        'title': 'My Blog Post',
        'subtitle': 'A developer blog about code',
        'theme': 'gradient',
        'accent': 'ff00aa'
    }
)
with open('og-image.png', 'wb') as f:
    f.write(response.content)

# List available themes
themes = requests.get('https://ogforge.dev/api/v1/themes')
print(themes.json()['themes'])