Skip to main content
Documentation

API Documentation

og-image.org exposes a no-auth API surface for image rendering and catalog discovery. The API is designed for static sites, edge functions, and backend automation workflows.

Available Endpoints

  • GET /api/og — render OG images from template parameters.
  • GET /api/templates — list available templates and defaults.
  • GET /api/backgrounds — list/search curated background photos.
  • GET/POST/DELETE /api/my-templates — user-scoped saved templates (D1).

1) Render Endpoint: /api/og

Generate Open Graph images via URL parameters. Default output is PNG. Set format=svg for SVG output.

GET https://og-image.org/api/og?template=photo-hero&title=Hello+World&description=Launch+day&bgId=qOGTYdYWQ7I&format=png

Query Parameters

ParameterTypeRequiredRules
templatestringNoTemplate ID from /api/templates. Defaults to gradient.
titlestringNoMax 80 characters.
descriptionstringNoMax 200 characters. Alias: subtitle.
iconstringNoMax 12 characters (emoji supported).
bg / backgroundColorstringNoBackground string used by template (hex or gradient).
text / textColorhexNo6-digit hex, with or without #.
accent / accentColorhexNo6-digit hex, with or without #.
bgIdstringNoBackground ID from /api/backgrounds.
overlaynumberNoClamped to 0..1. Default 0.55.
formatenumNopng (default) or svg.

Example Outputs

Template + PNG (default)
Template + PNG (default)
GET https://og-image.org/api/og?template=photo-hero&title=Product+Launch&description=Ship+faster+with+og-image.org&bgId=qOGTYdYWQ7I
Template + SVG
Template + SVG
GET https://og-image.org/api/og?template=minimal&title=Weekly+Report&description=KPI+up+34%25&format=svg&bg=ffffff&text=171717&accent=3b82f6
Catalog photo + overlay
Catalog photo + overlay
GET https://og-image.org/api/og?template=photo-glass&title=Design+System&description=Production+UI+in+days&bgId=Q1p7bh3SHj8&overlay=0.65

Rate Limits

  • 2 requests / 10 seconds / IP
  • 5 requests / minute / IP
  • 25 requests / hour / IP

Response headers include X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After on 429 responses.

2) Catalog Endpoint: /api/backgrounds

GET https://og-image.org/api/backgrounds?category=technology&search=neon&limit=30&offset=0
  • id: fetch single item by ID.
  • category: filter by category.
  • search: fuzzy text search over ID/title/author.
  • limit: 1..200 (default 30).
  • offset: pagination offset (default 0).

3) Template Catalog Endpoint: /api/templates

GET https://og-image.org/api/templates?category=social&search=photo
  • id: fetch single template item.
  • category: filter templates by category.
  • search: search by name/description/id.

4) My Templates Endpoint: /api/my-templates

Persist user-scoped templates to D1 so users can keep reusable designs. This endpoint requires the OG_DB binding.

GET https://og-image.org/api/my-templates?userKey=team-marketing
POST https://og-image.org/api/my-templates
PATCH https://og-image.org/api/my-templates
DELETE https://og-image.org/api/my-templates?userKey=team-marketing&id=tpl_xxx
  • GET: list templates for one userKey.
  • POST: save template snapshot: { userKey, name?, payload, templateId? }.
  • PATCH: rename template: { userKey, id, name }.
  • DELETE: remove a template by id + userKey.
  • If D1 is missing, API returns 501 D1_UNAVAILABLE.

5) Favorites Endpoint: /api/favorites

Sync user favorite backgrounds to D1 for cross-device persistence. This endpoint requires the OG_DB binding.

GET https://og-image.org/api/favorites?userKey=team-marketing
POST https://og-image.org/api/favorites
DELETE https://og-image.org/api/favorites?userKey=team-marketing&id=bg_xxx
  • GET: list favorite background IDs for one userKey.
  • POST: sync all favorites (replace): { userKey, ids: string[] }.
  • DELETE: remove a single favorite by id + userKey.
  • If D1 is missing, API returns 501 D1_UNAVAILABLE.

Error Format

{
  "success": false,
  "error": {
    "code": "TITLE_TOO_LONG",
    "message": "title must be <= 80 characters"
  }
}