Dynamic OG Image API

Last updated: March 31, 2026 · 8 min read

Every link shared on social media gets a single chance to grab attention. When someone posts your URL on Twitter, LinkedIn, Facebook, or Discord, the platform fetches the page's Open Graph metadata and renders a preview card. If that card shows a generic fallback image, or worse, nothing at all, your click-through rate suffers. Static OG images work fine for a homepage or a landing page, but they fall apart the moment your site has hundreds or thousands of pages. Writing a blog post every week? Launching new products in your catalog? Hosting recurring events? You cannot manually design a unique 1200x630 preview card for every single page.

This is exactly the problem a dynamic OG image API solves. Instead of uploading pre-made images, you construct a URL with parameters like title, subtitle, and theme. When a social platform's crawler hits that URL, the API generates a polished image on the fly and returns it as a PNG. Every page on your site gets a unique, branded social preview card without any design work on your part.

OGForge is a free, open API that does exactly this. No API keys, no signup, no rate limits. A single GET request returns a production-ready OG image. This tutorial walks through the use cases, the API mechanics, and step-by-step integration with popular frameworks.

Use Cases for Dynamic OG Images

Blog Posts with Title and Author Overlays

Technical blogs, news sites, and content platforms publish new articles regularly. Each post has a unique title, author, and sometimes a category. With a dynamic OG image API, you set the title parameter to the post's headline and the subtitle to the author's name or the publication date. The result is a social card that looks custom-designed for every article. Readers scrolling through their feed see the exact title of the piece, making them far more likely to click than if they saw a generic site logo.

E-Commerce Product Cards

Online stores with thousands of products cannot create individual OG images for every SKU. Dynamic generation lets you pass the product name as the title and the price or a short description as the subtitle. When a customer shares a product link on social media, the preview card shows the product name and key details instead of a generic store banner. This contextual information drives higher engagement and conversion from social traffic.

Event Pages with Date and Location

Conference sites, meetup groups, and ticketing platforms host dozens of events. Each event has a name, date, and venue. By dynamically generating OG images with these details, every shared event link displays the specific event information in the preview card. Attendees sharing event links effectively become promoters, since the card itself communicates the essential details at a glance.

User Profile Shares

SaaS platforms, developer portfolios, and community sites often have public profile pages. When users share their profile links, a dynamic OG image showing their username and a personalized tagline makes the share feel polished and intentional. This works especially well for developer tools, where a profile card with the user's name and stats can drive organic signups through social proof.

How OGForge Dynamic Generation Works

OGForge exposes a single endpoint at /api/v1/og that accepts GET requests. You pass your content as query parameters, and the API returns a PNG image. The entire process is stateless: there is no session, no stored data, and no authentication. The URL itself is the image.

Here are the key parameters you can control:

• title (required) — The primary text on the image. Up to 200 characters.
• subtitle — Secondary text displayed below the title. Up to 300 characters.
• caption — A small tagline or footer line beneath the subtitle. Up to 100 characters.
• theme — Visual style: dark, light, gradient, or cyberpunk.
• pattern — Background pattern overlay: dots, grid, diagonal, waves, circuit, or none.
• icon — Any icon name from the Lucide icon library (e.g., rocket, code, calendar).
• layout — Choose standard (default) or metric for KPI-style cards with a prominent value.
• titleColor / subtitleColor — Custom hex colors without the # prefix (e.g., ff6600).
• bgColor / bgGradient — Custom background as a solid color or two-color gradient.

Because the image is generated from a URL, you can construct it dynamically in your templates. The social platform fetches the URL, receives the PNG, and renders it in the preview card. No build step, no image storage, no CDN configuration required.

Step-by-Step Tutorial

Let us walk through generating dynamic OG images using the OGForge API. These examples use the live production API at https://ogforge.dev.

cURL

The simplest way to test the API is with a cURL command. This fetches a PNG image and saves it locally:

curl -o preview.png "https://ogforge.dev/api/v1/og?title=How+to+Build+a+REST+API&subtitle=A+Complete+Guide+for+Beginners&theme=dark&pattern=dots&icon=code"

This generates a dark-themed image with a dot pattern background, the Lucide code icon, and your blog post title rendered as the headline.

JavaScript (Node.js / Browser)

In a web application, you typically do not download the image. Instead, you construct the URL and set it as the og:image meta tag. Here is how to build the URL dynamically:

function getOgImageUrl(title, subtitle, options = {}) {
  const params = new URLSearchParams({
    title,
    subtitle,
    theme: options.theme || 'dark',
    pattern: options.pattern || 'dots',
    ...(options.icon && { icon: options.icon }),
    ...(options.caption && { caption: options.caption }),
  });
  return `https://ogforge.dev/api/v1/og?${params.toString()}`;
}

const ogUrl = getOgImageUrl(
  'How to Build a REST API',
  'A Complete Guide for Beginners',
  { theme: 'cyberpunk', icon: 'rocket', pattern: 'circuit' }
);

console.log(ogUrl);
// https://ogforge.dev/api/v1/og?title=How+to+Build+a+REST+API&subtitle=...

Python

Python applications can use the urllib.parse module to construct the URL safely, or fetch the image directly with requests:

from urllib.parse import urlencode

def get_og_image_url(title, subtitle, theme="dark", pattern="dots", icon=None):
    params = {
        "title": title,
        "subtitle": subtitle,
        "theme": theme,
        "pattern": pattern,
    }
    if icon:
        params["icon"] = icon
    return f"https://ogforge.dev/api/v1/og?{urlencode(params)}"

og_url = get_og_image_url(
    title="How to Build a REST API",
    subtitle="A Complete Guide for Beginners",
    theme="gradient",
    icon="book-open"
)

print(og_url)

# To download the image directly:
import requests

response = requests.get(og_url)
with open("preview.png", "wb") as f:
    f.write(response.content)

Framework Integration

The real power of a dynamic OG image API is in framework integration. Instead of hardcoding meta tags, you inject the OGForge URL with page-specific data. Here is how to do it in three popular frameworks.

Next.js (App Router)

In Next.js 14+ with the App Router, use the generateMetadata function to set OG images dynamically per page:

// app/blog/[slug]/page.tsx
import { Metadata } from 'next';

type Props = { params: { slug: string } };

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const post = await getPostBySlug(params.slug);

  const ogImageUrl = new URL('https://ogforge.dev/api/v1/og');
  ogImageUrl.searchParams.set('title', post.title);
  ogImageUrl.searchParams.set('subtitle', post.author);
  ogImageUrl.searchParams.set('theme', 'dark');
  ogImageUrl.searchParams.set('pattern', 'circuit');
  ogImageUrl.searchParams.set('icon', 'file-text');

  return {
    title: post.title,
    description: post.excerpt,
    openGraph: {
      title: post.title,
      description: post.excerpt,
      images: [{ url: ogImageUrl.toString(), width: 1200, height: 630 }],
    },
    twitter: {
      card: 'summary_large_image',
      title: post.title,
      description: post.excerpt,
      images: [ogImageUrl.toString()],
    },
  };
}

Express.js (Server-Side Rendering)

In an Express application rendering HTML with a template engine, inject the OG image URL into your layout template:

// routes/blog.js
const express = require('express');
const router = express.Router();

router.get('/blog/:slug', async (req, res) => {
  const post = await getPost(req.params.slug);

  const ogParams = new URLSearchParams({
    title: post.title,
    subtitle: `By ${post.author} | ${post.date}`,
    theme: 'dark',
    pattern: 'dots',
    icon: 'pen-tool',
  });

  const ogImageUrl = `https://ogforge.dev/api/v1/og?${ogParams}`;

  res.render('blog-post', {
    post,
    ogImageUrl,
    pageTitle: post.title,
  });
});

module.exports = router;

// views/blog-post.ejs (head section)
// <meta property="og:image" content="<%= ogImageUrl %>">
// <meta name="twitter:image" content="<%= ogImageUrl %>">

Django

In Django, build the OGForge URL in your view and pass it to the template context:

# views.py
from urllib.parse import urlencode
from django.shortcuts import render, get_object_or_404
from .models import BlogPost

def blog_detail(request, slug):
    post = get_object_or_404(BlogPost, slug=slug)

    og_params = urlencode({
        'title': post.title,
        'subtitle': f'By {post.author.name}',
        'theme': 'gradient',
        'pattern': 'waves',
        'icon': 'newspaper',
    })
    og_image_url = f'https://ogforge.dev/api/v1/og?{og_params}'

    return render(request, 'blog/detail.html', {
        'post': post,
        'og_image_url': og_image_url,
    })

# templates/blog/detail.html (in <head>)
# <meta property="og:image" content="{{ og_image_url }}">
# <meta name="twitter:image" content="{{ og_image_url }}">

The pattern is the same across every framework: construct a URL with your page-specific parameters and set it as the og:image value. Since the image is generated via a GET request, there are no CORS issues and no server-side rendering complexity. The social platform's crawler fetches the URL directly from OGForge.

Best Practices for Dynamic OG Images

Keep your titles concise. Social platforms truncate long text in preview cards, and OGForge renders the title at a size proportional to the image. Titles under 60 characters look best. Use the subtitle for additional context like author names, dates, or categories.

Choose a theme that matches your brand. The dark theme works well for developer tools, light for corporate and educational content, gradient for creative projects, and cyberpunk for tech-forward brands. Alternatively, use the bgColor and titleColor parameters to match your exact brand palette.

Use patterns sparingly. A dots or grid pattern adds subtle visual texture that makes images feel more designed, but the content should always be the focus. The circuit pattern pairs especially well with the cyberpunk theme for developer-oriented products.

Test your images with the Facebook Sharing Debugger and Twitter Card Validator before launching. These tools show you exactly how your dynamic OG images will render in each platform's feed.

Frequently Asked Questions

Related Guides

Learn more about OG image generation and social sharing optimization:

• Free OG Image Generator — Generate Open Graph images without any code using our visual tool.
• Social Preview Generator — Preview how your links will appear on Twitter, Facebook, and LinkedIn.
• API Documentation — Complete reference for all OGForge API parameters, themes, and layouts.
• Interactive Playground — Try the API live in your browser with instant preview.