API Documentation

Overview

The ogimagex API renders social share images on the edge from a single GET request. Pick a template, pass parameters as query strings, and drop the resulting URL straight into your og:image meta tag.

Quick start

<meta property="og:image"
  content="https://ogimagex.xyz/api/public/og/simple?title=Hello+World&accent=%237c3aed" />
<meta name="twitter:card" content="summary_large_image" />

URL-encode # in hex colors as %23 and spaces as +. Anything else is standard query-string escaping.

Endpoint

Common parameters

Every template accepts these three. Template-specific parameters are listed per template below.

Templates & parameters

18 templates. Each entry lists its use-case tags and full parameter set. Only required parameters must be present — everything else has a sensible default.

https://ogimagex.xyz/api/public/og/simple?title=example&description=example&brand=example

https://ogimagex.xyz/api/public/og/blog?category=example&title=example&excerpt=example

https://ogimagex.xyz/api/public/og/quote?quote=example&author=example&handle=example

https://ogimagex.xyz/api/public/og/stat?value=example&label=example&trend=example

https://ogimagex.xyz/api/public/og/logo?brand=example&monogram=example&tagline=example

https://ogimagex.xyz/api/public/og/testimonial?heading=example&quotes=example&brand=example

https://ogimagex.xyz/api/public/og/grid?title=example&description=example&brand=example

https://ogimagex.xyz/api/public/og/changelog?version=example&date=example&title=example

https://ogimagex.xyz/api/public/og/photo?image=example&label=example&title=example

https://ogimagex.xyz/api/public/og/product?brand=example&title=example&description=example

https://ogimagex.xyz/api/public/og/profile?name=example&role=example&bio=example

https://ogimagex.xyz/api/public/og/event?label=example&brand=example&title=example

https://ogimagex.xyz/api/public/og/terminal?title=example&caption=example&brand=example

https://ogimagex.xyz/api/public/og/editorial?kicker=example&title=example&author=example

https://ogimagex.xyz/api/public/og/showcase?title=example&subtitle=example&url=example

https://ogimagex.xyz/api/public/og/podcast?show=example&episode=example&title=example

https://ogimagex.xyz/api/public/og/newsletter?issue=example&date=example&title=example

https://ogimagex.xyz/api/public/og/course?category=example&title=example&instructor=example

https://ogimagex.xyz/api/public/og/saas-pro?badge=example&brand=example&title=example

https://ogimagex.xyz/api/public/og/course-pro?category=example&title=example&subtitle=example

https://ogimagex.xyz/api/public/og/podcast-pro?show=example&episode=example&title=example

https://ogimagex.xyz/api/public/og/hiring-pro?label=example&company=example&role=example

https://ogimagex.xyz/api/public/og/changelog-pro?version=example&date=example&title=example

SDK snippets

No SDK required — it's just a URL. Use any HTTP client.

curl -o cover.png \
  "https://ogimagex.xyz/api/public/og/blog?title=Rendering+OG+images+at+the+edge&author=Ada+Lovelace&accent=%237c3aed"

import { writeFile } from "node:fs/promises";

function ogUrl(template, params) {
  const qs = new URLSearchParams(params).toString();
  return `https://ogimagex.xyz/api/public/og/${template}?${qs}`;
}

const res = await fetch(ogUrl("blog", {
  title: "Rendering OG images at the edge",
  author: "Ada Lovelace",
  accent: "#7c3aed",
}));

if (!res.ok) throw new Error(`ogimagex ${res.status}`);
await writeFile("cover.png", Buffer.from(await res.arrayBuffer()));

import urllib.parse, urllib.request

def og_url(template, **params):
    qs = urllib.parse.urlencode(params)
    return f"https://ogimagex.xyz/api/public/og/{template}?{qs}"

url = og_url("blog",
    title="Rendering OG images at the edge",
    author="Ada Lovelace",
    accent="#7c3aed")

with urllib.request.urlopen(url) as res:
    with open("cover.png", "wb") as f:
        f.write(res.read())

export const metadata = {
  openGraph: {
    images: [`https://ogimagex.xyz/api/public/og/simple?title=${encodeURIComponent(title)}`],
  },
  twitter: { card: "summary_large_image" },
};

Output formats

• PNG (default): rasterised server-side, best for Open Graph and Twitter cards.
• SVG: request with ?format=svg for vector output — ideal for design tools or further processing.

Caching

Responses are cacheable at every layer. The cache key is the full URL including query string, so changing any parameter invalidates the cache for that variant.

Cache-Control: public, max-age=3600, s-maxage=3600, stale-while-revalidate=86400
Access-Control-Allow-Origin: *

Rate limits

Public endpoint is limited to 60 requests per minute per IP using a sliding window. Every response returns the current bucket state — no key or auth required.

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1735689600
Retry-After: 17            # only sent on 429

Because responses cache for an hour, most integrations never come close to the ceiling — production CDN traffic hits your cache, not this endpoint. Need higher throughput? Get in touch.

Error codes

On PNG render failure the endpoint transparently falls back to SVG and sets X-OG-Format-Fallback: svg. Callers receive a 200 in that case — inspect the header if you need to detect it.

License & ownership

Images you generate with ogimagex are yours to use for personal or commercial projects with no attribution required — see the FAQ for the full statement.