API Reference

Everything you need to integrate the Instant OG API into your application.

Base URL

https://instantog.com/api/og

Authentication

Instant OG supports two authentication methods, depending on your use case:

Option 1: Site ID (recommended for meta tags)

<meta
  property="og:image"
  content="https://instantog.com/api/og?site=site_b6bc4c3f&template=generic/standard&url=https://yoursite.com/page"
/>

The url domain must match your registered site. Instant OG also verifies that the page contains an og:image tag pointing back to the API, preventing unauthorized usage. Verification is cached for 24 hours.

Option 2: API key (for server-side / programmatic use)

Create a key in Dashboard → API Keys and pass it in the Authorization header:

curl "https://instantog.com/api/og?template=generic/standard&url=https://yoursite.com/page" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output og-image.png

Keep your API key secret — never expose it in client-side code or HTML. Use the site ID approach for meta tags.

Generate Image

GET /api/og — Generate (or serve from cache) an OG image for a given URL.

Query parameters

Parameter	Type	Required	Description
`url`	string	Yes	The page URL to extract metadata from
`template`	string	Yes	Template ID, e.g. `generic/standard`, `article/blog-post`
`site`	string	*	Your site ID (required if not using Bearer auth)
`theme`	string	No	`light` or `dark` (defaults to `light`)
`accentColor`	string	No	Hex color for accents and highlights, e.g. `%2316a34a` (URL-encoded `#16a34a`). Each template has its own default.
`gradientBg`	string	No	`true` to use a gradient background derived from the accent color. Supported by most templates.
`mode`	string	No	`ai` to enable AI-powered metadata extraction (costs 100 credits instead of 10, requires paid plan)
`refresh`	string	No	`true` to bypass cache and regenerate the image (API key auth only — not available with site-based auth)

Metadata overrides

Any additional query parameters not listed above are passed as metadata overrides, letting you replace values that would normally be extracted from the page. For example, &title=Custom+Title overrides the extracted title.

Override	Description
`title`	Page title
`description`	Page description / subtitle
`siteName`	Site name shown on the image
`author`	Author name (article templates)
`publishedAt`	Publication date (article templates)
`price`	Product price (product templates)
`rating`	Product rating (product templates)
`favicon`	URL to a favicon / logo image
`productImage`	URL to a product image (product templates)

Overrides are URL-encoded query params. For example:

https://instantog.com/api/og?site=site_b6bc4c3f&template=article/blog-post&url=https://yoursite.com/post&title=My+Custom+Title&author=Jane+Doe

Response

Returns a 200 response with Content-Type: image/png — the raw 1200×630 image bytes. Images are cached with Cache-Control: public, max-age=86400.

Full example

<!-- In your page's <head> -->
<meta property="og:image" content="https://instantog.com/api/og?site=site_b6bc4c3f&template=article/blog-post&url=https://yoursite.com/blog/my-post&theme=dark&accentColor=%236366f1&gradientBg=true" />
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:image" content="https://instantog.com/api/og?site=site_b6bc4c3f&template=article/blog-post&url=https://yoursite.com/blog/my-post&theme=dark&accentColor=%236366f1&gradientBg=true" />

Caching & Force Regeneration

Instant OG caches generated images based on the combination of URL, template, overrides, and options. If the same parameters are requested again, the cached image is served (1 credit). This means social platforms get fast responses and you save credits.

If your page content changes and you need a fresh image, add refresh=true to force a regeneration. This parameter requires API key authentication — it is not available with site-based auth to prevent abuse on public URLs.

curl "https://instantog.com/api/og?template=generic/standard&url=https://yoursite.com/page&refresh=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output og-image.png

This bypasses the cache, re-extracts metadata from the page, renders a new image, and replaces the cached version. It costs 10 credits (a standard generation). Subsequent requests without refresh=true will serve the updated cached image.

You can also manage cached images from Dashboard → History using the Regenerate or Delete buttons on any past generation.

Credits

Operation	Cost
Cached image (already generated)	1 credit
New generation (standard)	10 credits
New generation (AI mode)	100 credits

Rate Limits

API requests are rate-limited based on your plan:

Plan	Rate Limit
Free	60 requests/minute
Starter	120 requests/minute
Pro	300 requests/minute
Business	600 requests/minute
Enterprise	1,200 requests/minute

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

Error Codes

Code	Status	Description
`400`	Bad Request	Invalid parameters or missing required fields
`401`	Unauthorized	Missing or invalid API key
`402`	Payment Required	Insufficient credits
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Error	Something went wrong on our end

All error responses follow the format:

{
  "error": {
    "code": "insufficient_credits",
    "message": "You have 0 credits remaining. Upgrade your plan or purchase a credit pack."
  }
}

Ready to start building?

Create your free account, grab an API key, and generate your first OG image in minutes.

Get started free →