HTML إلى صورة

التقط عنوان URL لصفحة ويب أو محتوى HTML خام كصورة لقطة شاشة. يدعم محاكاة الأجهزة (سطح المكتب، الجهاز اللوحي، الهاتف المحمول)، والتقاط الصفحة الكاملة، وصيغ مخرجات متعددة.

نقطة نهاية API

POST /api/v1/tools/image/html-to-image

يقبل جسم JSON (وليس multipart). لا حاجة لرفع ملف.

المعاملات

المعامل	النوع	مطلوب	الافتراضي	الوصف
url	string	مشروط	-	عنوان URL للالتقاط (يجب أن يكون عنوان URL صالحاً)
html	string	مشروط	-	محتوى HTML خام للتصيير (1 إلى 5,000,000 حرف)
format	string	لا	"png"	صيغة المخرجات: jpg، png، webp
quality	number	لا	90	جودة المخرجات للصيغ ذات الفقدان (1 إلى 100)
fullPage	boolean	لا	false	التقاط الصفحة القابلة للتمرير بالكامل، وليس منفذ العرض فقط
devicePreset	string	لا	"desktop"	محاكاة الجهاز: desktop، tablet، mobile، custom
viewportWidth	number	لا	1280	عرض منفذ العرض المخصص بالبكسل (320 إلى 3840، يُستخدم عندما يكون devicePreset هو custom)
viewportHeight	number	لا	720	ارتفاع منفذ العرض المخصص بالبكسل (320 إلى 2160، يُستخدم عندما يكون devicePreset هو custom)

يجب توفير url أو html، لكن ليس كليهما.

إعدادات الأجهزة المسبقة

الإعداد المسبق	العرض	الارتفاع	UA الجوال
desktop	1280	720	لا
tablet	768	1024	لا
mobile	375	812	نعم
custom	(يحدده المستخدم)	(يحدده المستخدم)	لا

مثال على طلب

التقاط صفحة ويب:

curl -X POST http://localhost:1349/api/v1/tools/image/html-to-image \
  -H "Authorization: Bearer si_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "format": "png", "fullPage": true, "devicePreset": "desktop"}'

تصيير محتوى HTML:

curl -X POST http://localhost:1349/api/v1/tools/image/html-to-image \
  -H "Authorization: Bearer si_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"html": "<div style=\"padding: 20px; background: #f0f0f0;\"><h1>Hello</h1></div>", "format": "png"}'

مثال على استجابة

{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/screenshot.png",
  "originalSize": 0,
  "processedSize": 145000
}

ملاحظات

• يتطلب تثبيت Chromium على الخادم. يُرجع HTTP 503 إذا لم تكن خدمة المتصفح متاحة.
• يتم التحقق من عناوين URL ضد هجمات SSRF (يتم حظر عناوين الشبكة الخاصة/الداخلية).
• نقطة النهاية هذه محدودة المعدل إلى 120 طلباً في الساعة.
• originalSize يكون دائماً 0 لأن هذه الأداة تولّد صوراً من عناوين URL/HTML.
• اسم ملف المخرجات هو screenshot.<format>.
• إذا استغرقت الصفحة وقتاً طويلاً في التحميل، يُرجع الطلب HTTP 504 (مهلة البوابة).
• إذا تعطلت خدمة المتصفح مراراً، يتم تعطيلها مؤقتاً وتُرجع HTTP 503 مع الرمز BROWSER_CRASHED.