OG 圖片 API 參考

OG 圖片 API 參考涵蓋使用 FastOG 產生動態 Open Graph 圖片的端點、參數與範本目錄。此 API 需訂閱才能使用——必須具備有效的 Dynamic API 方案，但轉譯本身不計量：沒有每月轉譯配額，也沒有超額計費。HMAC 簽署的 URL 可確保每個請求安全無虞。請註冊、選擇 Dynamic API 方案，然後在 dashboard 中建立 API 金鑰與 HMAC 密鑰；付費 API 轉譯不會產生額外費用。產生的 OpenAPI 契約是參數、錯誤碼與範本 slug 的權威機器可讀清單。

基礎 URL

https://fastog.com/api/v1/og

驗證

所有請求都需要 HMAC-SHA256 簽章驗證。公開的 key 與 s 簽章屬於查詢參數；目前不支援以標頭為基礎的驗證。詳情請參閱 HMAC 文件。

端點

GET `/api/v1/og`

根據提供的參數產生動態 Open Graph 圖片。

查詢參數

參數	類型	必填	說明
`template`	string	否	範本名稱（預設：`default`）
`title`	string	是	主標題。必填——沒有標題的封面無法作為有用的預覽。
`subtitle`	string	否	副標題或說明文字
`key`	string	是	完整 API 金鑰
`s`	string	是	HMAC-SHA256 簽章（64 個十六進位字元）

範本專屬參數

每個範本除了接受下方的共用參數外，還會接受其範本專屬參數（請參閱索引表）。template 查詢參數用來選擇要使用的版面配置（預設：default）。

共用參數（所有範本）

參數	類型	說明
`title`	string	主標題文字
`subtitle`	string	輔助文字
`tags`	list	以逗號分隔的標籤
`theme`	string	`dark` \| `light` \| `glass` \| `solid` \| `midnight` \| `vivid` \| `paper` \| `glass_light` \| `custom`
`gradient_preset`	string	具名的漸層預設集（例如 `indigo`、`ocean`、`sunset`、`cosmic`）
`gradient_direction`	number	漸層角度（度）（預設 `135`）
`bg_color`	hex	純色背景色
`pattern`	string	背景圖案（`grid`、`dots`、`noise`、`none`、…）
`pattern_color`	hex	圖案顏色
`pattern_intensity`	number	圖案不透明度（1–30）
`font_family`	string	`font-sans`、`font-jakarta`、`font-dm`、`font-outfit`、`font-space`、`font-playfair`、`font-merriweather`、`font-instrument`、`font-jetbrains`、`font-fira`
`accent_color`	hex	用於強調的輔助色
`auto_text_color`	bool	從背景推導文字顏色（預設 `true`）
`title_color`	hex	覆寫標題顏色
`subtitle_color`	hex	覆寫副標題顏色
`brand_name`	string	品牌/標誌文字（預設 `FastOG`）
`brand_logo`	string	品牌標誌圖片 URL
`layout_mode`	string	`split` \| `centered` \| `banner`（適用範本專屬變體）

範本索引 — 67 個可渲染 slug，48 個可選取。下表說明最常用的外觀及其範本專屬 props；完整且自動產生的清單（標籤、分類、已淘汰旗標，以及所有可接受的 slug）位於 /openapi.json 的 x-template-catalogue 之下，而每個範本的編輯器欄位（key、label、type、default、options 與 URL 格式）則位於 x-template-fields 之下。已淘汰的 slug 仍可渲染，因此已在各處流通的 URL 仍可繼續運作，但選取器不會提供這些 slug。

`template`	範本	類別	其他參數
`default`	預設	品牌	—
`blog`	部落格文章	內容	`author`, `date`, `domain`
`ecommerce`	電子商務	商務	`price`, `original_price`, `rating`, `rating_total`, `features`, `badge`, `cta`, `image`, `domain`
`company`	公司	品牌	`domain`, `logo`, `tag`
`launch`	產品發布	品牌	`kicker`, `version`, `tag`, `cta`, `domain`
`saaslaunch`	SaaS 發布	品牌	`kicker`, `cta`, `domain`
`devtool`	開發者工具	開發者	`version`, `badge`, `domain`
`game`	遊戲	內容	`price`, `rating`, `image`, `domain`
`event`	活動	社群	`location`, `host`, `date`, `domain`
`quote`	引言	社群	`quote`, `author_name`, `author_title`
`job`	職缺	社群	`location`, `department`, `salary`, `job_type`, `domain`
`stats`	統計	資料	`metric`, `metric_label`, `delta`
`pricing`	定價	商務	`price`, `period`, `cta`
`podcast`	Podcast	媒體	`episode_number`, `guest_name`, `guest_role`, `duration`
`video`	影片	媒體	`duration`, `channel`, `views`
`editorial`	編輯特稿	內容	`kicker`, `author`, `date`, `domain`
`minimal`	極簡	品牌	`domain`
`changelog`	更新日誌	開發者	`version`, `tag`
`corporate`	企業	品牌	`kicker`, `tag`, `domain`
`hero`	主視覺	品牌	`kicker`, `cta`, `status`, `domain`
`imageright`	右側圖片	商務	`kicker`, `price`, `original_price`, `rating`, `rating_total`, `badge`, `cta`, `image`, `domain`
`specgrid`	規格格狀	商務	`specs` (`Label
`logos`	標誌牆	品牌	`kicker`, `brand_logos`, `domain`
`notice`	公告	社群	`notice_status`, `notice_icon`, `notice_text`, `date`, `domain`
`testimonial`	客戶見證	社群	`quote`, `author_name`, `author_title`, `company`, `author_avatar`, `rating`, `rating_total`, `quote_style`
`logofocus`	標誌聚焦	內容	`kicker`, `domain`
`xheader`	X 頁首	社群	`size`, `handle`, `followers`, `location`, `website`, `avatar`
`bento`	Bento	資料	`kicker`, `tiles`, `domain`
`comparison`	比較	商務	`kicker`, `left_label`, `left_desc`, `left_points`, `right_label`, `right_desc`, `right_points`, `verdict`
`timeline`	時間軸	內容	`kicker`, `milestones`, `domain`
`countdown`	倒數計時	品牌	`kicker`, `target_date`, `cta`, `domain`
`news`	新聞	內容	`headline`, `byline`, `author`, `date`, `source`, `image`
`code`	程式碼	開發者	`code`, `language`, `terminal_title`, `author`, `domain`
`testimonialpro`	客戶見證 Pro	社群	`quote`, `author_name`, `author_title`, `company`, `author_avatar`, `rating`, `rating_total`, `cta`
`product`	產品	商務	`badge`, `title`, `price`, `original_price`, `rating`, `rating_total`, `features`, `cta`, `image`, `layout_mode`
`promo`	促銷	品牌	`brand_name`, `benefits`, `title`, `subtitle`, `domain`, `layout_mode`
`devblog`	開發部落格	內容	`category`, `title`, `subtitle`, `tags`, `author`, `author_title`, `date`, `read_time`, `views`, `likes`, `comments`, `code`, `language`, `file_path`
`codepost`	程式碼文章	內容	`category`, `date`, `title`, `subtitle`, `author`, `read_time`, `code`, `file_path`, `language`
`statsbar`	統計列	資料	`kicker`, `metric`, `metric_label`, `delta`, `stats`, `domain`
`changelogpro`	更新日誌 Pro	開發者	`version`, `tag`, `title`, `changes`, `features`, `domain`
`quotecta`	引言 CTA	社群	`quote`, `author_name`, `author_title`, `company`, `cta`, `domain`
`appscreenshot`	應用程式截圖	媒體	`badge`, `title`, `subtitle`, `app_name`, `rating`, `screenshot`, `domain`
`realestate`	房地產	商務	`title`, `subtitle`, `price`, `beds`, `baths`, `sqft`, `cta_text`, `status`, `image_url`, `domain`
`autorental`	租車	商務	`title`, `subtitle`, `rate_badge`, `cta_text`, `fleet_tag`, `image_url`, `domain`
`restaurant`	餐廳	商務	`kicker`, `title`, `subtitle`, `price`, `cta_text`, `badge`, `image_url`, `domain`
`hospitality`	旅宿	媒體	`kicker`, `title`, `subtitle`, `rate`, `cta_text`, `image_url`, `domain`
`saasspend`	SaaS 支出	品牌	`status_pill`, `title`, `subtitle`, `cta_text`, `stat_callout`, `dashboard_image`, `domain`
`brutalist`	粗獷主義	品牌	`agency_tag`, `title`, `subtitle`, `cta_text`, `footer_note`, `domain`
`training`	教育訓練	社群	`track`, `dates`, `title`, `subtitle`, `cta_text`, `location`, `image_url`, `domain`
`ecosystem`	生態系	開發者	`kicker`, `title`, `subtitle`, `apps_list`, `dock_label`, `domain`

glassproduct 也接受 cta。ecommerce、product、glassproduct 與 imageright 範本預設會顯示「Shop now」；請將 cta 設為空值以隱藏視覺膠囊按鈕。

結構化參數類型

類型	格式	範例
`list`	以逗號分隔的值	`features=Fast,Cheap,Secure`
`tiles`	以換行分隔的 `label\|value` 鍵值對	`tiles=Requests\|12.4M\nUptime\|99.99%`
`milestones`	以換行分隔的 `date\|title\|description`	`milestones=Q3 2026\|Alpha\|Invite-only`
`changes`	以換行分隔的 `type\|text` (`added`,`fixed`,`improved`,`removed`)	`changes=added\|Bento templates`

回應

200 OK — 回傳 PNG 影像資料
401 Unauthorized — 驗證無效或缺少驗證
422 Unprocessable — 範本參數無效

錯誤回應

錯誤代碼	HTTP 狀態碼	說明
`missing_signature`	401	缺少 `key` 或 `s` 參數
`invalid_signature`	401	簽章驗證失敗

範例請求

GET /api/v1/og?template=blog&title=Hello%20World&subtitle=A%20test%20post&key=sk_quick_123abc&s=a1b2c3...

cURL 範例

bash

curl "https://fastog.com/api/v1/og?template=blog&title=Hello%20World&key=sk_quick_123abc&s=<signature>"

定價與限制

FastOG 採訂閱制：必須有啟用中的 Dynamic API 方案。算圖不計量——沒有每月算圖額度，也沒有超額計費。方案本身就是門檻，每個方案層級算圖都不計次。目前方案層級與價格請見定價。

快取圖片免費：由 Cloudflare 邊緣快取提供的請求（相同範本 + 參數，不論先前快取 URL 上的 s 簽章為何）不會到達來源伺服器，因此相同的 URL 不會再耗用一次算圖。

預設乾淨：每次算圖都是乾淨的——任何方案都沒有浮水印，免費的 OG Image Tester、Studio 預覽與 Studio 匯出也一樣。對於明確要求「Made with FastOG」徽章的呼叫端，仍支援 fastog_watermark 算圖 prop，但不會有任何東西自動設定它。

文件 — 所有 FastOG 指南與參考資料
免費 OG 圖片測試工具 — 無需帳號即可預覽
快速入門指南 — 包含架構流程（於渲染時簽章）
HMAC 簽章指南
HMAC 驗證
JavaScript 教學