Docs / OG images

Open Graph image API

GET /v1/og returns a 1200×630 JPEG social image — 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 $SHOTPDF_KEY" \
  "https://shotpdf.astraeatech.dev/v1/og?title=Launch+day&subtitle=We+are+live&theme=dark" \
  -o og.jpg

From a URL

terminal

curl -H "Authorization: Bearer $SHOTPDF_KEY" \
  "https://shotpdf.astraeatech.dev/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 OG size.
themelight — light or dark. Styles the built-in template; URL captures render the page as-is.
ttl86400 — Cache freshness in seconds, 0–604800. 0 bypasses the cache.

Caching and errors

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