Tham chiếu OG Image API

Tham chiếu OG image API bao gồm endpoint, các tham số và danh mục template để tạo hình ảnh Open Graph động với FastOG. API yêu cầu gói đăng ký — cần có gói Dynamic API đang hoạt động, nhưng bản thân các lần render không bị tính phí: không có hạn mức render hàng tháng và không tính phí vượt mức. Các URL được ký HMAC giúp mỗi yêu cầu luôn an toàn. Đăng ký, chọn gói Dynamic API, sau đó tạo API key và HMAC secret trong dashboard; các lần render API trả phí đều rõ ràng. Hợp đồng OpenAPI được tạo là danh sách tham số, mã lỗi và template slug có thẩm quyền ở dạng máy đọc được.

URL cơ sở

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

Xác thực

Tất cả các yêu cầu đều yêu cầu xác thực bằng chữ ký HMAC-SHA256. key công khai và chữ ký s là tham số truy vấn; xác thực dựa trên header hiện chưa được hỗ trợ. Xem Tài liệu HMAC để biết chi tiết.

Endpoint

GET `/api/v1/og`

Tạo hình ảnh Open Graph động dựa trên các tham số được cung cấp.

Tham số truy vấn

Tham số	Kiểu	Bắt buộc	Mô tả
`template`	string	Không	Tên template (mặc định: `default`)
`title`	string	Có	Tiêu đề chính. Bắt buộc — ảnh bìa không có tiêu đề không phải là bản xem trước hữu ích.
`subtitle`	string	Không	Văn bản phụ đề hoặc mô tả
`key`	string	Có	API key đầy đủ
`s`	string	Có	Chữ ký HMAC-SHA256 (64 ký tự hex)

Tham số riêng theo template

Mỗi template chấp nhận các tham số dùng chung bên dưới cộng với các tham số riêng của template đó (xem bảng chỉ mục). Tham số truy vấn template chọn bố cục được sử dụng (mặc định: default).

Tham số dùng chung (tất cả template)

Tham số	Kiểu	Mô tả
`title`	string	Văn bản tiêu đề chính
`subtitle`	string	Văn bản bổ trợ
`tags`	list	Các nhãn tag phân tách bằng dấu phẩy
`theme`	string	`dark` \| `light` \| `glass` \| `solid` \| `midnight` \| `vivid` \| `paper` \| `glass_light` \| `custom`
`gradient_preset`	string	Preset gradient có tên (ví dụ: `indigo`, `ocean`, `sunset`, `cosmic`)
`gradient_direction`	number	Góc gradient tính bằng độ (mặc định `135`)
`bg_color`	hex	Màu nền đặc
`pattern`	string	Họa tiết nền (`grid`, `dots`, `noise`, `none`, …)
`pattern_color`	hex	Màu họa tiết
`pattern_intensity`	number	Độ mờ của họa tiết (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	Màu nhấn cho các điểm nổi bật
`auto_text_color`	bool	Suy ra màu chữ từ nền (mặc định `true`)
`title_color`	hex	Ghi đè màu tiêu đề
`subtitle_color`	hex	Ghi đè màu phụ đề
`brand_name`	string	Văn bản thương hiệu/logo (mặc định `FastOG`)
`brand_logo`	string	URL hình ảnh logo thương hiệu
`layout_mode`	string	`split` \| `centered` \| `banner` (áp dụng các biến thể riêng theo template)

Danh mục template — 67 slug có thể render, 48 slug có thể chọn. Bảng dưới đây ghi lại những giao diện được dùng nhiều nhất và các prop riêng của từng template; danh sách đầy đủ được sinh tự động (nhãn, danh mục, cờ đã ngừng dùng và mọi slug được chấp nhận) nằm trong /openapi.json tại mục x-template-catalogue, và các trường trong trình soạn thảo của từng template (key, label, type, default, options và định dạng URL) nằm tại mục x-template-fields. Các slug đã ngừng dùng vẫn có thể render để những URL đã tồn tại bên ngoài tiếp tục hoạt động, nhưng chúng không được đưa ra trong các trình chọn.

`template`	Template	Danh mục	Tham số bổ sung
`default`	Default	Brand	—
`blog`	Blog Post	Content	`author`, `date`, `domain`
`ecommerce`	E-commerce	Commerce	`price`, `original_price`, `rating`, `rating_total`, `features`, `badge`, `cta`, `image`, `domain`
`company`	Company	Brand	`domain`, `logo`, `tag`
`launch`	Product Launch	Brand	`kicker`, `version`, `tag`, `cta`, `domain`
`saaslaunch`	SaaS Launch	Brand	`kicker`, `cta`, `domain`
`devtool`	Developer Tool	Developer	`version`, `badge`, `domain`
`game`	Game	Content	`price`, `rating`, `image`, `domain`
`event`	Event	Social	`location`, `host`, `date`, `domain`
`quote`	Quote	Social	`quote`, `author_name`, `author_title`
`job`	Job Posting	Social	`location`, `department`, `salary`, `job_type`, `domain`
`stats`	Stats	Data	`metric`, `metric_label`, `delta`
`pricing`	Pricing	Commerce	`price`, `period`, `cta`
`podcast`	Podcast	Media	`episode_number`, `guest_name`, `guest_role`, `duration`
`video`	Video	Media	`duration`, `channel`, `views`
`editorial`	Editorial	Content	`kicker`, `author`, `date`, `domain`
`minimal`	Minimal	Brand	`domain`
`changelog`	Changelog	Developer	`version`, `tag`
`corporate`	Corporate	Brand	`kicker`, `tag`, `domain`
`hero`	Hero	Brand	`kicker`, `cta`, `status`, `domain`
`imageright`	Image Right	Commerce	`kicker`, `price`, `original_price`, `rating`, `rating_total`, `badge`, `cta`, `image`, `domain`
`specgrid`	Spec Grid	Commerce	`specs` (danh sách `Label
`logos`	Logo Wall	Brand	`kicker`, `brand_logos`, `domain`
`notice`	Notice	Social	`notice_status`, `notice_icon`, `notice_text`, `date`, `domain`
`testimonial`	Testimonial	Social	`quote`, `author_name`, `author_title`, `company`, `author_avatar`, `rating`, `rating_total`, `quote_style`
`logofocus`	Logo Focus	Content	`kicker`, `domain`
`xheader`	X Header	Social	`size`, `handle`, `followers`, `location`, `website`, `avatar`
`bento`	Bento	Data	`kicker`, `tiles`, `domain`
`comparison`	Comparison	Commerce	`kicker`, `left_label`, `left_desc`, `left_points`, `right_label`, `right_desc`, `right_points`, `verdict`
`timeline`	Timeline	Content	`kicker`, `milestones`, `domain`
`countdown`	Countdown	Brand	`kicker`, `target_date`, `cta`, `domain`
`news`	News	Content	`headline`, `byline`, `author`, `date`, `source`, `image`
`code`	Code	Developer	`code`, `language`, `terminal_title`, `author`, `domain`
`testimonialpro`	Testimonial Pro	Social	`quote`, `author_name`, `author_title`, `company`, `author_avatar`, `rating`, `rating_total`, `cta`
`product`	Product	Commerce	`badge`, `title`, `price`, `original_price`, `rating`, `rating_total`, `features`, `cta`, `image`, `layout_mode`
`promo`	Promo	Brand	`brand_name`, `benefits`, `title`, `subtitle`, `domain`, `layout_mode`
`devblog`	Dev Blog	Content	`category`, `title`, `subtitle`, `tags`, `author`, `author_title`, `date`, `read_time`, `views`, `likes`, `comments`, `code`, `language`, `file_path`
`codepost`	Code Post	Content	`category`, `date`, `title`, `subtitle`, `author`, `read_time`, `code`, `file_path`, `language`
`statsbar`	Stats Bar	Data	`kicker`, `metric`, `metric_label`, `delta`, `stats`, `domain`
`changelogpro`	Changelog Pro	Developer	`version`, `tag`, `title`, `changes`, `features`, `domain`
`quotecta`	Quote CTA	Social	`quote`, `author_name`, `author_title`, `company`, `cta`, `domain`
`appscreenshot`	App Screenshot	Media	`badge`, `title`, `subtitle`, `app_name`, `rating`, `screenshot`, `domain`
`realestate`	Real Estate	Commerce	`title`, `subtitle`, `price`, `beds`, `baths`, `sqft`, `cta_text`, `status`, `image_url`, `domain`
`autorental`	Auto Rental	Commerce	`title`, `subtitle`, `rate_badge`, `cta_text`, `fleet_tag`, `image_url`, `domain`
`restaurant`	Restaurant	Commerce	`kicker`, `title`, `subtitle`, `price`, `cta_text`, `badge`, `image_url`, `domain`
`hospitality`	Hospitality	Media	`kicker`, `title`, `subtitle`, `rate`, `cta_text`, `image_url`, `domain`
`saasspend`	SaaS Spend	Brand	`status_pill`, `title`, `subtitle`, `cta_text`, `stat_callout`, `dashboard_image`, `domain`
`brutalist`	Brutalist	Brand	`agency_tag`, `title`, `subtitle`, `cta_text`, `footer_note`, `domain`
`training`	Training	Social	`track`, `dates`, `title`, `subtitle`, `cta_text`, `location`, `image_url`, `domain`
`ecosystem`	Ecosystem	Developer	`kicker`, `title`, `subtitle`, `apps_list`, `dock_label`, `domain`

glassproduct cũng chấp nhận cta. Các template ecommerce, product, glassproduct và imageright hiển thị “Shop now” theo mặc định; đặt cta thành giá trị rỗng để ẩn nút dạng viên.

Các kiểu tham số có cấu trúc

Kiểu	Định dạng	Ví dụ
`list`	Các giá trị phân tách bằng dấu phẩy	`features=Fast,Cheap,Secure`
`tiles`	Các cặp `label\|value` phân tách bằng dòng	`tiles=Requests\|12.4M\nUptime\|99.99%`
`milestones`	`date\|title\|description` phân tách bằng dòng	`milestones=Q3 2026\|Alpha\|Invite-only`
`changes`	`type\|text` phân tách bằng dòng (`added`,`fixed`,`improved`,`removed`)	`changes=added\|Bento templates`

Phản hồi

200 OK — Trả về dữ liệu ảnh PNG
401 Unauthorized — Xác thực không hợp lệ hoặc bị thiếu
422 Unprocessable — Tham số template không hợp lệ

Phản hồi lỗi

Mã lỗi	Trạng thái HTTP	Mô tả
`missing_signature`	401	Thiếu tham số `key` hoặc `s`
`invalid_signature`	401	Xác minh chữ ký thất bại

Yêu cầu mẫu

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

cURL mẫu

bash

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

Giá & Giới hạn

FastOG yêu cầu gói đăng ký: cần có gói Dynamic API đang hoạt động. Việc render không bị tính phí theo lượt — không có hạn mức render hàng tháng và không có phí vượt mức. Gói đăng ký chính là điều kiện, và mọi gói đều render không cần bộ đếm. Xem Giá để biết các gói và mức giá hiện tại.

Hình ảnh đã cache là miễn phí: các yêu cầu được phục vụ từ cache biên của Cloudflare (cùng template + params, bất kể chữ ký s trên một URL đã được cache trước đó) không bao giờ chạm tới origin, vì vậy một URL giống hệt không tốn thêm một lượt render.

Mặc định sạch: mọi lượt render đều sạch — không có watermark trên bất kỳ gói nào, và cũng không có trên OG Image Tester miễn phí, bản xem trước Studio hay bản xuất Studio. Prop render fastog_watermark vẫn được hỗ trợ cho những ai chủ động yêu cầu huy hiệu "Made with FastOG", nhưng không có gì tự động bật nó.

Tài liệu — Tất cả hướng dẫn và tài liệu tham khảo của FastOG
Công cụ kiểm tra OG Image miễn phí— Xem trước mà không cần tài khoản
Hướng dẫn bắt đầu nhanh — bao gồm luồng kiến trúc (ký tại thời điểm render)
Hướng dẫn chữ ký HMAC
Xác thực HMAC
Hướng dẫn JavaScript