Docs / OG images

Open Graph image API

GET /v1/og returns a social image (default 1200×630 JPEG) — either from a title rendered on the built-in template, or from any URL. Authenticated and metered.

From a title (template mode)

terminal

curl -H "Authorization: Bearer $PROOFITO_KEY" \
  "https://api-staging.astraeatech.dev/proofito/v1/og?title=Launch+day&subtitle=We+are+live&theme=dark" \
  -o og.jpg

From a URL

terminal

curl -H "Authorization: Bearer $PROOFITO_KEY" \
  "https://api-staging.astraeatech.dev/proofito/v1/og?url=https://example.com/blog/launch" \
  -o og.jpg

Parameters

title— — Present: template mode. Up to 300 characters.
subtitle— — Optional second line in template mode. Up to 300 characters.
url— — Used when title is absent: screenshot the page itself at the requested size.
themelight — light or dark (case-insensitive). Styles the built-in template; URL captures render the page as-is.
layoutclassic — classic or minimal (case-insensitive; minimal hides the rule and brand mark). Template mode only.
accent— — Brand accent as a 6-digit hex color, e.g. #4f46e5. Template mode only.
logo_url— — Logo image URL, fetched server-side and embedded (must be an image under 256 KB). Template mode only.
formatjpeg — jpeg (quality 90) or png (case-insensitive).
width1200 — Capture width, 600–2400 px. Template typography scales with width.
height630 — Capture height, 300–1260 px.
timeout_ms— — Per-request render cap, 1000–60000 ms. Can only tighten the worker default.
ttl86400 — Cache freshness in seconds, 0–604800. 0 bypasses the cache.

Caching and errors

Output defaults to 1200×630 JPEG and is byte-cached (X-Cache: HIT/MISS); cached responses still count as one metered request each. One of title/url is required, else 400 (when both are given, title wins and url is ignored); a missing key returns 401 invalid_api_key; quota exhaustion returns HTTP 429. Back to the docs index.