OGsmithStart free

API reference

A GET request to one endpoint returns a 1200×630 PNG.

Endpoint

GET /api/og

Returns image/png on success. Errors return JSON with an error field: 400 invalid parameters, 401 bad key, 429 quota or rate limit exceeded.

Parameters

ParamTypeDefaultDescription
keystringnoneYour API key (og_…). Omit for watermarked, rate-limited demo renders.
templategradient | minimal | split | terminal | quote | announce | link | covergradientWhich card layout to render.
titlestring (≤ 200 chars)Hello, worldMain headline. Font size auto-scales with length.
subtitlestring (≤ 300 chars)noneSupporting line under the title.
sitestring (≤ 100 chars)noneSite or brand name shown in the footer of the card.
themedark | lightdarkBase color scheme (the terminal template is always dark).
accenthex color#6366f1Accent color. URL-encode the hash: %236366f1.
sizeog | square | story | youtube | wideogCanvas the card is rendered at. See Sizes. Ignored with tpl, where the size belongs to the design.
expstringnoneSlug of one of your experiments. Picks a design variant for this page and records that a card was served. See Experiments.
kstring (≤ 500 chars)url, if givenIdentifies the page under test, for exp. Must be a stable id, such as a post slug or database id, never the title. Defaults to the url value when you pass one.
urlhttps URLnoneRead this page and use its title, description, site name and image. Anything you pass explicitly wins. See Cards from a URL.
tplstringnoneSlug of one of your own templates from the visual editor. Replaces template; every other parameter becomes a {{placeholder}} value.
vstring (≤ 32 chars)noneCache-busting token. Ignored when rendering; changing it is what forces social platforms to re-fetch. See Refreshing cached cards.
acct + sigstringnoneSigned-URL auth: your account ID plus an HMAC signature. An alternative to key. See Signed URLs.

Use it in your HTML

<meta
  property="og:image"
  content="https://ogsmith.app/api/og?key=og_yourkey&template=split&title=My%20post&site=example.com&accent=%23f43f5e"
/>
<meta name="twitter:card" content="summary_large_image" />

Next.js example

export function generateMetadata({ params }) {
  const og = new URL("https://ogsmith.app/api/og");
  og.searchParams.set("key", process.env.OGSMITH_KEY);
  og.searchParams.set("title", post.title);
  og.searchParams.set("site", "example.com");
  return { openGraph: { images: [og.toString()] } };
}

Account defaults

Set default template, theme, accent, and site values in the dashboard (Brand defaults). They apply to authenticated renders whenever the parameter is omitted, so a URL can be as short as /api/og?key=…&title=Hello. Parameters in the URL always override defaults. You can create up to 10 named API keys and revoke each one separately. The dashboard shows render counts per key. On paid plans, an uploaded logo (dashboard → Brand defaults) renders on every card next to the site name.

More in the docs