OGForge API Documentation

OGForge generates Open Graph images on the fly. Pass a title and optional parameters via a simple GET or POST 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 image in PNG (default), WebP, JPEG, or SVG format 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)
`caption`	string	optional	Small tagline or footer text rendered below the subtitle in the accent color (max 100 characters). Useful for branding, attribution, or URLs.
`theme`	string	optional	Color theme: `dark` (default), `light`, `gradient`, `cyberpunk`, `minimal`, `bold`
`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 40 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`)
`bgColor`	string	optional	Custom background color as 6-character hex without `#` (e.g., `1a1a2e`). Overrides theme background.
`titleColor`	string	optional	Custom title text color as 6-character hex without `#` (e.g., `ffffff`). Overrides theme title color.
`subtitleColor`	string	optional	Custom subtitle text color as 6-character hex without `#` (e.g., `cccccc`). Overrides theme subtitle color.
`gradientStart`	string	optional	Gradient start color as 6-character hex without `#` (e.g., `1a1a2e`). When set with `gradientEnd`, creates a custom gradient background that takes priority over `bgColor`.
`gradientEnd`	string	optional	Gradient end color as 6-character hex without `#` (e.g., `2e1a2e`). Used together with `gradientStart`.
`gradientAngle`	number	optional	Gradient direction angle in degrees (0–360, default: 135). Works with custom `gradientStart`/`gradientEnd` gradients and also overrides the angle on theme gradients (e.g., `gradient` theme).
`format`	string	optional	Output format: `png` (default), `webp`, `jpeg`, or `svg`. WebP offers the best compression — up to 80% smaller than PNG.
`size`	string	optional	Size preset: `og` (1200×630, default), `square` (1080×1080), `twitter-banner` (1500×500), `twitter-summary` (800×418), `linkedin` (1200×627), `instagram-story` (1080×1920), `facebook-cover` (820×312). See GET /sizes.
`width`	number	optional	Custom width in pixels (200–2400). Cannot combine with `size`.
`height`	number	optional	Custom height in pixels (200–2400). Cannot combine with `size`.
`layout`	string	optional	Layout type: `standard` (default) or `metric` (KPI/stat card with prominent value). See GET /layouts.
`value`	string	optional	Prominent number/stat for metric layout (e.g., `2.4M`, `99.9%`, `$1.2B`). Required when `layout=metric`. Max 20 characters.
`pattern`	string	optional	Background pattern overlay: `dots`, `grid`, `diagonal`, `waves`, `circuit`, or `none` (default). See GET /patterns.
`border`	string	optional	Border/frame color as 6-character hex without `#` (e.g., `ff00aa`). Adds a visible frame around the entire image. Great for preventing images from “floating” on white backgrounds (LinkedIn, Slack light mode).
`borderWidth`	number	optional	Border width in pixels (1–10, default: 3). If set without `border`, uses the theme’s accent color.

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

# Square format for Instagram/LinkedIn
curl "https://ogforge.dev/api/v1/og?title=Square+Post&size=square" -o og-square.png

# Custom dimensions
curl "https://ogforge.dev/api/v1/og?title=Custom+Banner&width=1500&height=500" -o banner.png

Response

Returns a binary image with the following headers:

Header	Value
`Content-Type`	`image/png`, `image/webp`, `image/jpeg`, or `image/svg+xml`
`Cache-Control`	`public, max-age=86400`
`X-OGForge-Theme`	The theme used for generation
`X-OGForge-Size`	The output dimensions (e.g., `1200x630`)
`X-OGForge-Border`	Border color and width when border is applied (e.g., `ff00aa@3px`)

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" />

POST /og

POST /api/v1/og

Generate an Open Graph image using a JSON request body. Accepts the same parameters as GET /og but via a JSON body instead of query parameters. This is ideal for titles with special characters, long URLs, or programmatic integrations.

Request Body

          
          
          
          JSON Body
        
{
  "title": "My Blog Post",
  "subtitle": "A developer blog about code & architecture",
  "theme": "bold",
  "icon": "rocket",
  "brand": "mybrand.dev",
  "accent": "ff6600",
  "bgColor": "1a1a2e",
  "titleColor": "ffffff",
  "subtitleColor": "cccccc",
  "gradientStart": "1a1a2e",
  "gradientEnd": "2e1a2e",
  "gradientAngle": 135,
  "format": "png",
  "size": "og",
  "pattern": "dots",
  "border": "ff00aa",
  "borderWidth": 3
}

Example Request

          
          cURL
        
curl -X POST "https://ogforge.dev/api/v1/og" \
  -H "Content-Type: application/json" \
  -d '{"title":"My Blog Post","theme":"minimal","icon":"code"}' \
  --output og.png

GET /themes

GET /api/v1/themes

List all available themes.

Example Response

          
          
          
          200 OK
        
{
  "themes": ["dark", "light", "gradient", "cyberpunk", "minimal", "bold"],
  "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"
}

GET /sizes

GET /api/v1/sizes

List all available image size presets and custom dimension constraints. Use the preset name as the size parameter in /api/v1/og, or provide custom width/height.

Example Response

          
          
          
          200 OK
        
{
  "presets": {
    "og": { "width": 1200, "height": 630, "label": "Open Graph (Facebook, LinkedIn)" },
    "square": { "width": 1080, "height": 1080, "label": "Square (Instagram, LinkedIn)" },
    "twitter-banner": { "width": 1500, "height": 500, "label": "Twitter/X Banner" },
    "twitter-summary": { "width": 800, "height": 418, "label": "Twitter/X Summary Card" },
    "linkedin": { "width": 1200, "height": 627, "label": "LinkedIn Post" },
    "instagram-story": { "width": 1080, "height": 1920, "label": "Instagram Story" },
    "facebook-cover": { "width": 820, "height": 312, "label": "Facebook Cover Photo" }
  },
  "default": "og",
  "custom": {
    "min": 200,
    "max": 2400,
    "description": "Use width and/or height parameters for custom dimensions"
  }
}

GET /layouts

GET /api/v1/layouts

List all available image layout types. Use the layout name as the layout parameter in /api/v1/og.

Example Response

          
          
          
          200 OK
        
{
  "layouts": ["standard", "metric"],
  "default": "standard",
  "descriptions": {
    "standard": "Default layout with title, subtitle, icon, and brand",
    "metric": "KPI/stat card layout with a prominent value, label (title), and optional subtitle. Requires the \"value\" parameter."
  }
}

Metric Layout Example

          
          cURL
        
# Generate a KPI/metric card
curl "https://ogforge.dev/api/v1/og?title=Monthly+Users&value=2.4M&layout=metric&theme=bold" -o metric.png

# With subtitle and icon
curl "https://ogforge.dev/api/v1/og?title=Uptime&value=99.9%25&subtitle=Last+30+days&layout=metric&icon=check&theme=cyberpunk" -o uptime.png

GET /patterns

GET /api/v1/patterns

List all available background pattern overlays. Use the pattern name as the pattern parameter in /api/v1/og.

          
          
          
          response
        
{
  "patterns": ["dots", "grid", "diagonal", "waves", "circuit"],
  "default": "none",
  "descriptions": {
    "dots": "Subtle dot matrix overlay",
    "grid": "Fine grid lines (also applied automatically by cyberpunk theme)",
    "diagonal": "Diagonal hatching lines",
    "waves": "Horizontal wave pattern",
    "circuit": "Circuit board trace pattern",
    "none": "No pattern overlay (default)"
  },
  "description": "Use the pattern parameter in /api/v1/og to add a subtle background pattern overlay"
}

Pattern Examples

          
          cURL
        
# Dot matrix pattern on dark theme
curl "https://ogforge.dev/api/v1/og?title=Dot+Matrix&pattern=dots&theme=dark" -o dots.png

# Circuit board pattern with cyberpunk theme
curl "https://ogforge.dev/api/v1/og?title=Tech+Post&pattern=circuit&theme=gradient" -o circuit.png

# Diagonal lines on bold theme
curl "https://ogforge.dev/api/v1/og?title=Bold+Design&pattern=diagonal&theme=bold" -o diagonal.png

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

# Custom brand colors (background, title, subtitle)
curl "https://ogforge.dev/api/v1/og?title=My+Brand&bgColor=1a1a2e&titleColor=ffffff&subtitleColor=aabbcc" -o og.png

# With caption/tagline
curl "https://ogforge.dev/api/v1/og?title=My+Blog&subtitle=Dev+thoughts&caption=blog.example.com&theme=dark" -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","minimal","bold"]

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'])

MCP Integration

OGForge ships with a built-in Model Context Protocol (MCP) server. Connect OGForge directly to Claude, VS Code, Cursor, or any MCP-compatible AI client to generate OG images from your assistant.

Installation

Add the following to your MCP client configuration:

claude_desktop_config.json
{
  "mcpServers": {
    "ogforge": {
      "command": "npx",
      "args": ["-y", "ogforge-api"]
    }
  }
}

Available Tools

Tool	Description	Parameters
`generate_og_image`	Generate an Open Graph image with customizable options	`title` (string, required), `subtitle`, `caption`, `theme`, `icon`, `brand`, `accent`, `bgColor`, `titleColor`, `subtitleColor`, `format`
`list_themes`	List all available OG image themes	None

Environment Variables

Variable	Default	Description
`OGFORGE_BASE_URL`	`https://ogforge.dev`	Override the base URL for API requests (e.g., for self-hosted instances)