الموضوع

مرجع OG Image API

يغطي مرجع OG image API نقطة النهاية (endpoint) والمعاملات وكتالوج القوالب اللازمة لإنشاء صور Open Graph ديناميكية باستخدام FastOG. تخضع هذه الواجهة لاشتراك — إذ يلزم وجود خطة Dynamic API نشطة، لكن عمليات العرض (renders) نفسها لا تُحتسب: فلا توجد حصة شهرية للعرض ولا فواتير تجاوز. وتضمن الروابط الموقّعة بـ HMAC أمان كل طلب. سجّل، واختر خطة Dynamic API، ثم أنشئ مفتاح API وسرّ HMAC في لوحة التحكم (dashboard)؛ وعمليات العرض المدفوعة عبر API خالية من أي التزامات إضافية. ويُعد عقد OpenAPI المُولَّد القائمة المرجعية القابلة للقراءة آليًا للمعاملات ورموز الأخطاء ومعرّفات القوالب (template slugs).

عنوان URL الأساسي

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

المصادقة

تتطلب جميع الطلبات مصادقة عبر توقيع HMAC-SHA256. المفتاح العام key والتوقيع s هما معاملان في سلسلة الاستعلام (query parameters)؛ المصادقة المعتمدة على الترويسات (headers) غير مدعومة حاليًا. راجع توثيق HMAC للحصول على التفاصيل.

نقطة النهاية (Endpoint)

GET `/api/v1/og`

يولّد صورة Open Graph ديناميكية بناءً على المعاملات المقدَّمة.

معاملات الاستعلام (Query Parameters)

المعامل	النوع	مطلوب	الوصف
`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	لون التمييز (accent) للإبرازات
`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 قابلاً للاختيار. يوثّق الجدول أدناه المظاهر الأكثر استخداماً وخصائصها الخاصة بكل قالب؛ أما القائمة الشاملة المولّدة (التسمية، والفئة، وعلامة الإيقاف، وكل slug مقبول) فهي في /openapi.json ضمن x-template-catalogue، كما أن حقول محرّر كل قالب (المفتاح، والتسمية، والنوع، والقيمة الافتراضية، والخيارات، وصيغة URL) موجودة ضمن x-template-fields. تبقى الـ slugs الموقوفة قابلة للعرض كي تستمر الروابط المنتشرة بالعمل، لكنّ منتقيات القوالب لا تعرضها.

`template`	القالب	الفئة	معاملات إضافية
`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` (قائمة من `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 أيضًا 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 المؤقتة على الحافة (نفس القالب + المعاملات، بغض النظر عن توقيع s على URL مخزّن مؤقتًا سابقًا) لا تصل إلى الأصل، لذا فإن URL مطابقًا لا يستهلك عملية عرض أخرى.

نظيف افتراضيًا: كل عملية عرض نظيفة — لا علامة مائية على أي خطة، ولا على أداة اختبار صور OG المجانية، ولا على معاينات Studio أو صادرات Studio. لا يزال خاصية العرض fastog_watermark مدعومة للجهات التي تطلب صراحةً شارة "Made with FastOG"، لكن لا شيء يضبطها تلقائيًا.

التوثيق — جميع أدلة ومراجع FastOG
أداة اختبار صور OG المجانية — عاين دون حساب
دليل البدء السريع — يتضمن مخطط البنية (التوقيع عند العرض)
دليل توقيع HMAC
التحقق من HMAC
درس JavaScript

جرّبه مجانًا — لا حاجة للتسجيل

معاينة واختبار صور OG الديناميكية في ثوانٍ.

افتح أداة اختبار OG المجانية