Dokumentacja API obrazów OG

Dokumentacja API obrazów OG obejmuje endpoint, parametry i katalog szablonów do generowania dynamicznych obrazów Open Graph za pomocą FastOG. API jest dostępne w ramach subskrypcji — wymagany jest aktywny plan Dynamic API, ale same rendery nie są rozliczane: nie ma miesięcznego limitu renderów ani opłat za nadwyżkę. Adresy URL podpisane HMAC zapewniają bezpieczeństwo każdego żądania. Zarejestruj się, wybierz plan Dynamic API, a następnie utwórz klucz API i sekret HMAC w panelu; płatne rendery API są czyste. Wygenerowany kontrakt OpenAPI jest autorytatywną, czytelną maszynowo listą parametrów, kodów błędów i slugów szablonów.

Bazowy URL

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

Uwierzytelnianie

Wszystkie żądania wymagają uwierzytelniania sygnaturą HMAC-SHA256. Publiczny key oraz sygnatura s są parametrami zapytania; uwierzytelnianie oparte na nagłówkach nie jest obecnie obsługiwane. Szczegóły znajdziesz w dokumentacji HMAC.

Endpoint

GET `/api/v1/og`

Generuje dynamiczny obraz Open Graph na podstawie podanych parametrów.

Parametry zapytania

Parametr	Typ	Wymagany	Opis
`template`	string	Nie	Nazwa szablonu (domyślnie: `default`)
`title`	string	Tak	Główny nagłówek. Wymagany — okładka bez tytułu nie jest użytecznym podglądem.
`subtitle`	string	Nie	Podtytuł lub tekst opisu
`key`	string	Tak	Pełny klucz API
`s`	string	Tak	Sygnatura HMAC-SHA256 (64 znaki hex)

Parametry specyficzne dla szablonu

Każdy szablon przyjmuje poniższe wspólne parametry oraz swoje parametry specyficzne dla szablonu (zobacz tabelę indeksu). Parametr zapytania template wybiera używany układ (domyślnie: default).

Wspólne parametry (wszystkie szablony)

Parametr	Typ	Opis
`title`	string	Tekst głównego nagłówka
`subtitle`	string	Tekst uzupełniający
`tags`	list	Etykiety tagów oddzielone przecinkami
`theme`	string	`dark` \| `light` \| `glass` \| `solid` \| `midnight` \| `vivid` \| `paper` \| `glass_light` \| `custom`
`gradient_preset`	string	Nazwany preset gradientu (np. `indigo`, `ocean`, `sunset`, `cosmic`)
`gradient_direction`	number	Kąt gradientu w stopniach (domyślnie `135`)
`bg_color`	hex	Jednolity kolor tła
`pattern`	string	Wzór tła (`grid`, `dots`, `noise`, `none`, …)
`pattern_color`	hex	Kolor wzoru
`pattern_intensity`	number	Krycie wzoru (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	Kolor akcentu dla wyróżnień
`auto_text_color`	bool	Wyprowadź kolor tekstu z tła (domyślnie `true`)
`title_color`	hex	Nadpisz kolor tytułu
`subtitle_color`	hex	Nadpisz kolor podtytułu
`brand_name`	string	Tekst marki/logo (domyślnie `FastOG`)
`brand_logo`	string	URL obrazu logo marki
`layout_mode`	string	`split` \| `centered` \| `banner` (obowiązują warianty specyficzne dla szablonu)

Indeks szablonów — 67 renderowalnych slugów, 48 wybieralnych. Poniższa tabela dokumentuje najczęściej używane wyglądy i ich właściwości specyficzne dla szablonu; wyczerpująca, wygenerowana lista (etykieta, kategoria, flaga wycofania i każdy akceptowany slug) znajduje się w /openapi.json pod x-template-catalogue, a pola edytora każdego szablonu (klucz, etykieta, typ, wartość domyślna, opcje i format URL) są pod x-template-fields. Wycofane slugi pozostają renderowalne, dzięki czemu adresy URL już krążące w sieci nadal działają, ale nie są oferowane przez selektory.

`template`	Szablon	Kategoria	Dodatkowe parametry
`default`	Default	Marka	—
`blog`	Blog Post	Treść	`author`, `date`, `domain`
`ecommerce`	E-commerce	Handel	`price`, `original_price`, `rating`, `rating_total`, `features`, `badge`, `cta`, `image`, `domain`
`company`	Company	Marka	`domain`, `logo`, `tag`
`launch`	Product Launch	Marka	`kicker`, `version`, `tag`, `cta`, `domain`
`saaslaunch`	SaaS Launch	Marka	`kicker`, `cta`, `domain`
`devtool`	Developer Tool	Developer	`version`, `badge`, `domain`
`game`	Game	Treść	`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	Dane	`metric`, `metric_label`, `delta`
`pricing`	Pricing	Handel	`price`, `period`, `cta`
`podcast`	Podcast	Media	`episode_number`, `guest_name`, `guest_role`, `duration`
`video`	Video	Media	`duration`, `channel`, `views`
`editorial`	Editorial	Treść	`kicker`, `author`, `date`, `domain`
`minimal`	Minimal	Marka	`domain`
`changelog`	Changelog	Developer	`version`, `tag`
`corporate`	Corporate	Marka	`kicker`, `tag`, `domain`
`hero`	Hero	Marka	`kicker`, `cta`, `status`, `domain`
`imageright`	Image Right	Handel	`kicker`, `price`, `original_price`, `rating`, `rating_total`, `badge`, `cta`, `image`, `domain`
`specgrid`	Spec Grid	Handel	`specs` (lista `Label
`logos`	Logo Wall	Marka	`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	Treść	`kicker`, `domain`
`xheader`	X Header	Social	`size`, `handle`, `followers`, `location`, `website`, `avatar`
`bento`	Bento	Dane	`kicker`, `tiles`, `domain`
`comparison`	Comparison	Handel	`kicker`, `left_label`, `left_desc`, `left_points`, `right_label`, `right_desc`, `right_points`, `verdict`
`timeline`	Timeline	Treść	`kicker`, `milestones`, `domain`
`countdown`	Countdown	Marka	`kicker`, `target_date`, `cta`, `domain`
`news`	News	Treść	`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	Handel	`badge`, `title`, `price`, `original_price`, `rating`, `rating_total`, `features`, `cta`, `image`, `layout_mode`
`promo`	Promo	Marka	`brand_name`, `benefits`, `title`, `subtitle`, `domain`, `layout_mode`
`devblog`	Dev Blog	Treść	`category`, `title`, `subtitle`, `tags`, `author`, `author_title`, `date`, `read_time`, `views`, `likes`, `comments`, `code`, `language`, `file_path`
`codepost`	Code Post	Treść	`category`, `date`, `title`, `subtitle`, `author`, `read_time`, `code`, `file_path`, `language`
`statsbar`	Stats Bar	Dane	`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	Handel	`title`, `subtitle`, `price`, `beds`, `baths`, `sqft`, `cta_text`, `status`, `image_url`, `domain`
`autorental`	Auto Rental	Handel	`title`, `subtitle`, `rate_badge`, `cta_text`, `fleet_tag`, `image_url`, `domain`
`restaurant`	Restaurant	Handel	`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	Marka	`status_pill`, `title`, `subtitle`, `cta_text`, `stat_callout`, `dashboard_image`, `domain`
`brutalist`	Brutalist	Marka	`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 akceptuje również cta. Szablony ecommerce, product, glassproduct i imageright domyślnie wyświetlają „Shop now”; ustaw cta na pustą wartość, aby ukryć wizualną pigułkę.

Typy parametrów strukturalnych

Typ	Format	Przykład
`list`	Wartości oddzielone przecinkami	`features=Fast,Cheap,Secure`
`tiles`	Pary `label\|value` oddzielone wierszami	`tiles=Requests\|12.4M\nUptime\|99.99%`
`milestones`	`date\|title\|description` oddzielone wierszami	`milestones=Q3 2026\|Alpha\|Invite-only`
`changes`	`type\|text` oddzielone wierszami (`added`,`fixed`,`improved`,`removed`)	`changes=added\|Bento templates`

Odpowiedź

200 OK — Zwraca dane obrazu PNG
401 Unauthorized — Nieprawidłowe lub brakujące uwierzytelnienie
422 Unprocessable — Nieprawidłowe parametry szablonu

Odpowiedzi błędów

Kod błędu	Status HTTP	Opis
`missing_signature`	401	Brak parametru `key` lub `s`
`invalid_signature`	401	Weryfikacja podpisu nie powiodła się

Przykładowe żądanie

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

Przykładowy cURL

bash

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

Cennik i limity

FastOG działa na zasadzie subskrypcji: wymagany jest aktywny plan Dynamic API. Rendery nie są rozliczane — nie ma miesięcznego limitu renderów ani opłat za przekroczenie. Plan jest warunkiem dostępu, a każdy poziom renderuje bez licznika. Aktualne poziomy i ceny znajdziesz w sekcji Cennik.

Zbuforowane obrazy są darmowe: żądania obsługiwane z pamięci podręcznej Cloudflare edge (ten sam szablon + parametry, niezależnie od podpisu s w uprzednio zbuforowanym URL-u) nigdy nie docierają do originu, więc identyczny URL nie zużywa kolejnego renderu.

Domyślnie czysto: każdy render jest czysty — brak znaku wodnego na każdym planie, a także w darmowym OG Image Tester, podglądach Studio i eksportach Studio. Właściwość renderu fastog_watermark jest nadal obsługiwana dla wywołujących, którzy jawnie żądają plakietki „Made with FastOG”, ale nic nie ustawia jej automatycznie.

Dokumentacja — Wszystkie przewodniki i materiały referencyjne FastOG
Darmowy tester obrazów OG— Podgląd bez konta
Przewodnik szybkiego startu — zawiera przepływ architektury (podpis w momencie renderowania)
Przewodnik po podpisach HMAC
Walidacja HMAC
Samouczek JavaScript