API Documentation

Everything you need to generate dynamic OG images programmatically.

Base URL

https://ogpeek.com

All API endpoints are under /api/v1/.

Authentication

The free tier (GET endpoint) requires no authentication. For the paid tier (POST endpoint), include your API key in the x-api-key header:

curl -H "x-api-key: ogp_your_key_here" ...

You can also pass it as a query parameter: ?api_key=ogp_your_key_here

Generate Image (Free Tier)

GET /api/v1/og No auth required

Generate a watermarked OG image via query parameters. Perfect for testing or low-volume usage.

curl "https://ogpeek.com/api/v1/og?title=Hello+World&template=gradient&theme=dark" \
  --output og.png

Or use directly in your HTML:

<meta property="og:image" content="https://ogpeek.com/api/v1/og?title=My+Post&theme=dark" />

Generate Image (Paid Tier)

POST /api/v1/og API key required

Generate a clean (no watermark) OG image with full parameter control.

curl -X POST "https://ogpeek.com/api/v1/og" \
  -H "x-api-key: ogp_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Blog Post",
    "subtitle": "A deep dive into modern APIs",
    "template": "gradient",
    "theme": "dark",
    "brandColor": "#6366f1"
  }' \
  --output og.png

Get an API Key

POST /api/v1/keys No auth required

Create a free API key. You'll start on the free plan with 50 requests/day.

curl -X POST "https://ogpeek.com/api/v1/keys" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

Response:

{
  "apiKey": "ogp_abc123...",
  "plan": "free",
  "limit": "50 requests/day"
}

Check Usage

GET /api/v1/usage API key required

curl -H "x-api-key: ogp_your_key_here" "https://ogpeek.com/api/v1/usage"

Response:

{
  "plan": "starter",
  "requestsToday": 142,
  "requestsThisMonth": 3847
}

Parameters Reference

Parameter	Type	Default	Description
title	string	"Hello World"	Main heading text (required for useful output)
subtitle	string	""	Secondary text below the title
template	string	"basic"	Layout template: `basic`, `gradient`, `split`, `hero`
theme	string	"dark"	Color theme: `dark`, `light`, `midnight`, `forest`, `sunset`
brandColor	string	"#6366f1"	Hex color for accent elements
logo	string	""	URL to a logo image (optional)

Templates & Themes

Templates

Name	Description
basic	Clean centered layout with title and subtitle
gradient	Bold gradient background with brand color accent
split	Two-column layout with colored sidebar
hero	Large title with decorative background elements

Themes

Name	Description
dark	Dark background, light text (most popular)
light	White background, dark text
midnight	Deep navy with blue accents
forest	Dark green tones
sunset	Warm gradient from orange to purple

Rate Limits

Plan	Price	Daily	Monthly	Watermark
Free	$0	50	500	Yes
Starter	$9/mo	500	10,000	No
Pro	$29/mo	2,500	50,000	No

Rate limits reset daily at midnight UTC and monthly on the 1st. Additionally, all endpoints have a global rate limit of 60 requests/minute (10/min for free GET endpoint).

Error Codes

200Image generated successfully (returns PNG binary)

400Bad request — invalid parameters or missing required fields

401Unauthorized — missing or invalid API key

429Rate limit exceeded — upgrade your plan or wait

500Server error — try again or contact support

Error responses return JSON:

{
  "error": "Daily limit reached",
  "limit": 50,
  "plan": "free",
  "upgrade": "https://ogpeek.com/#pricing"
}