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.
  • Photo API = GET /api/og — pass template=photo-* + bgId (no separate /api/photo route).
  • GET/POST/PATCH/DELETE /api/my-templates — user-scoped saved templates (D1).
  • GET/POST/DELETE /api/favorites — user-scoped favorite background IDs (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=xuZTzyXCbTw&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.

Photo API Samples (/api/og)

For photo variants, call /api/og directly with template=photo-hero | photo-glass | photo-caption | photo-split | photo-duotone, and include bgId from /api/backgrounds.

Photo hero launch card
Photo hero launch card

Homepage-style hero image with photo background + overlay.

GET https://og-image.org/api/og?template=photo-hero&title=Product+Launch&description=Ship+faster+with+og-image.org&icon=🚀&bgId=xuZTzyXCbTw
Photo glass card
Photo glass card

Glass-style content layer over catalog background.

GET https://og-image.org/api/og?template=photo-glass&title=Design+System&description=Production+UI+in+days&icon=✨&bgId=zdfVYtP4zNQ&overlay=0.65
Photo caption story card
Photo caption story card

Nature photo with stronger overlay for contrast.

GET https://og-image.org/api/og?template=photo-caption&title=Weekend+Guide&description=6+quiet+hiking+routes&icon=🌿&bgId=LUMeoI4ehNM&overlay=0.72
Photo split product card
Photo split product card

City image + split layout for product updates.

GET https://og-image.org/api/og?template=photo-split&title=Release+2.3&description=New+analytics+dashboard&icon=📊&bgId=T1ugdMvuVqM&overlay=0.58
Photo duotone social campaign
Photo duotone social campaign

Photo-duotone style for campaign consistency.

GET https://og-image.org/api/og?template=photo-duotone&title=Spring+Campaign&description=Performance+creative+kit&icon=🎯&bgId=NHopyVfddF8&overlay=0.7
Template + SVG
Template + SVG

Switch response MIME type via format=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
Photo hero (Chinese)
Photo hero (Chinese)

Chinese title + subtitle rendering test.

GET https://og-image.org/api/og?template=photo-hero&title=春节发布计划&description=支持中文标题与表情图标&icon=🧧&bgId=bKESVqfxass&overlay=0.62
Photo glass (Chinese)
Photo glass (Chinese)

Chinese text rendering with photo background.

GET https://og-image.org/api/og?template=photo-glass&title=设计系统周报&description=通过API自动生成社媒封面图&icon=🛰️&bgId=RYGq_PGtPPk&overlay=0.66
Photo caption (Chinese)
Photo caption (Chinese)

Chinese line breaks and spacing coverage.

GET https://og-image.org/api/og?template=photo-caption&title=增长周报+第12期&description=中文与日本語を同時表示+含むEmoji&icon=📈&bgId=rlh8o7OaOU0&overlay=0.74
Photo split (Chinese)
Photo split (Chinese)

Chinese body copy on right panel with icon.

GET https://og-image.org/api/og?template=photo-split&title=产品更新日志&description=支持+bgId+emoji+和多语言字体&icon=🛠️&bgId=lMq3sfMMViM&overlay=0.6
Photo duotone (Chinese)
Photo duotone (Chinese)

Duotone layout with Chinese copy.

GET https://og-image.org/api/og?template=photo-duotone&title=新功能上线&description=一键生成社媒预览图+支持缓存&icon=🚀&bgId=sBTxuKtdK80&overlay=0.72
Photo hero (Japanese)
Photo hero (Japanese)

Japanese title and emoji rendering check.

GET https://og-image.org/api/og?template=photo-hero&title=春の新機能リリース&description=写真テンプレートをAPIで自動生成&icon=🎌&bgId=PFKx7Srejek&overlay=0.64

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"
  }
}