API Documentation

ShotOG generates beautiful OG images with a single API call. Edge-native, globally fast, developer-friendly.

Authentication

Pass your API key via the X-Api-Key header or api_key query parameter. Demo mode (no key) allows 10 requests/day.

# Create a free API key
curl -X POST https://karta-shotog.royal-dew-cbe4.workers.dev/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'

# Returns: { "key": "sk_...", "tier": "free", "monthly_limit": 500 }

Generate OG Image

GET /v1/og

Generate an image via query parameters. Perfect for embedding in <meta> tags.

# Simple
curl "https://karta-shotog.royal-dew-cbe4.workers.dev/v1/og?title=Hello%20World"

# Full options
curl "https://karta-shotog.royal-dew-cbe4.workers.dev/v1/og?title=My%20Post&subtitle=Great%20read&template=blog&eyebrow=Tech&author=Jane&api_key=sk_..."

POST /v1/og

Generate an image via JSON body.

curl -X POST https://karta-shotog.royal-dew-cbe4.workers.dev/v1/og \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sk_..." \
  -d '{
    "title": "My Post",
    "template": "blog",
    "subtitle": "A great read",
    "eyebrow": "Tech",
    "author": "Jane Doe"
  }'

POST /v1/og/batch

Generate up to 20 images in a single request. Returns JSON with base64 data URIs.

curl -X POST https://karta-shotog.royal-dew-cbe4.workers.dev/v1/og/batch \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sk_..." \
  -d '{
    "images": [
      {"id": "hero", "title": "My Product", "template": "product"},
      {"id": "blog-1", "title": "First Post", "template": "blog", "author": "Alice"}
    ],
    "defaults": {"format": "png", "width": 1200, "domain": "example.com"}
  }'

# Response:
# {
#   "results": [
#     {"id":"hero","success":true,"dataUri":"data:image/png;base64,..."},
#     {"id":"blog-1","success":true,"dataUri":"data:image/png;base64,..."}  
#   ],
#   "summary": {"total":2,"succeeded":2,"failed":0}
# }

Parameters

Parameter	Type	Required	Description
title	string	Yes	Main title text
template	string	No	Template name (default: basic). Options include wordpress, basic, blog, product, social, event, changelog, testimonial, announcement
subtitle	string	No	Subtitle or description
eyebrow	string	No	Small text above title (e.g. "NEW", "Blog")
author	string	No	Author name
domain	string	No	Domain watermark (default: karta.media)
bgColor	string	No	Background color (hex, e.g. #667eea)
textColor	string	No	Text color (hex)
accentColor	string	No	Accent color (hex)
format	string	No	Output format: png (default) or svg
width	number	No	Image width, 200-2400 (default: 1200)
height	number	No	Image height, 200-1260 (default: 630)
fontUrl	string	No	URL to a TTF/OTF font file (max 5MB, cached 1h)
avatar	string	No	Avatar image URL (for blog, social, testimonial templates)
logo	string	No	Logo image URL (for basic, product templates)
backgroundImage	string	No	HTTPS featured image URL for the wordpress template. featuredImage is accepted as an alias.
overlayOpacity	number	No	Dark overlay opacity, 0-0.9 (default: 0.56)
backgroundPosition	string	No	Image crop alignment: center, top, bottom, left, or right

Other Endpoints

Endpoint	Method	Description
/v1/og/templates	GET	List all available templates
/v1/keys	POST	Create a new API key (self-service)
/v1/keys/usage	GET	Check usage (requires X-Api-Key header)
/v1/og/batch	POST	Batch generate up to 20 images (returns JSON with base64)
/health	GET	Health check

SDK (TypeScript / JavaScript)

npm install shotog

import { ShotOG } from "shotog";

const og = new ShotOG({ apiKey: "sk_..." });

// Generate URL (no network request)
const url = og.url({ title: "Hello", template: "blog" });

// Generate image binary
const buffer = await og.generate({ title: "Hello", template: "blog" });

Response Headers

Header	Description
X-Cache	HIT or MISS — indicates cache status
X-Render-Time-Ms	Total render time in milliseconds
X-SVG-Time-Ms	SVG generation time
X-PNG-Time-Ms	PNG conversion time

Rate Limits

See Pricing for tier-based limits. Demo mode (no API key): 10 requests/day.