SVG إلى صورة نقطية

حوّل ملفات SVG إلى صيغ صور نقطية (PNG أو JPEG أو WebP أو AVIF أو TIFF أو GIF أو HEIF أو JXL) بدقة وكثافة DPI مخصصة. يدعم أيضًا التحويل الدفعي لعدة ملفات SVG.

نقطة نهاية API

POST /api/v1/tools/image/svg-to-raster

المعاملات

المعامل	النوع	مطلوب	الافتراضي	الوصف
width	integer	لا	-	العرض المستهدف بالبكسل (1 إلى 65536). يحافظ على نسبة الأبعاد إذا ضُبط بُعد واحد فقط.
height	integer	لا	-	الارتفاع المستهدف بالبكسل (1 إلى 65536). يحافظ على نسبة الأبعاد إذا ضُبط بُعد واحد فقط.
dpi	integer	لا	300	كثافة DPI للتصيير، تتحكم في كثافة التنقيط الأساسية (36 إلى 2400)
quality	number	لا	90	جودة المخرجات للصيغ ذات الفقد (1 إلى 100)
backgroundColor	string	لا	"#00000000"	لون الخلفية بصيغة hex (6 أو 8 أحرف، النسخة ذات 8 أحرف تتضمن الشفافية)
outputFormat	string	لا	"png"	صيغة المخرجات: png، jpg، webp، avif، tiff، gif، heif، jxl

مثال طلب

curl -X POST http://localhost:1349/api/v1/tools/image/svg-to-raster \
  -F "[email protected]" \
  -F 'settings={"width":1024,"dpi":300,"outputFormat":"png","backgroundColor":"#FFFFFF"}'

مثال استجابة

{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/logo.png",
  "previewUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/preview.webp",
  "originalSize": 12345,
  "processedSize": 67890
}

نقطة نهاية الدفعات

POST /api/v1/tools/image/svg-to-raster/batch

حوّل عدة ملفات SVG في طلب واحد. تُرجع أرشيف ZIP.

معاملات دفعات إضافية

المعامل	النوع	مطلوب	الافتراضي	الوصف
clientJobId	string	لا	-	معرّف مهمة اختياري يوفّره العميل لتتبع التقدّم (128 حرفًا كحد أقصى)

مثال طلب دفعي

curl -X POST http://localhost:1349/api/v1/tools/image/svg-to-raster/batch \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F 'settings={"width":512,"outputFormat":"png","dpi":150}'

استجابة الدفعات

تبثّ نقطة نهاية الدفعات ملف ZIP مباشرة مع الترويسات التالية:

• Content-Type: application/zip
• X-Job-Id: <jobId>
• X-File-Results: <url-encoded JSON mapping of index to filename>

ملاحظات

• تقبل ملفات SVG وSVGZ فقط (تتحقق من المحتوى، وليس من الامتداد فقط). تُفكّ ضغط SVGZ تلقائيًا.
• يُطهّر محتوى SVG قبل التصيير لمنع XSS وتحميل الموارد الخارجية.
• يتحكم إعداد dpi في الكثافة التي يُنقّط بها SVG. تنتج كثافة DPI الأعلى أبعاد بكسل أكبر من نفس منفذ عرض SVG.
• عند توفير كل من width وheight، يُعاد تحجيم الصورة باستخدام fit: inside (مع الحفاظ على نسبة الأبعاد ضمن الحدود).
• تُضمَّن previewUrl في الاستجابة للصيغ التي لا تستطيع المتصفحات عرضها أصليًا (TIFF، HEIF). المعاينة هي صورة مصغّرة WebP بحجم 1200 بكسل.
• الخلفية الافتراضية #00000000 شفافة تمامًا. اضبطها إلى #FFFFFF للحصول على خلفية بيضاء (مفيد مع مخرجات JPEG التي لا تدعم الشفافية).
• تحترم معالجة الدفعات تهيئة الخادم MAX_BATCH_SIZE وتستخدم عمّالًا متزامنين لتحسين الأداء.
• يمكن تتبع تقدّم عمليات الدفعات عبر SSE على /api/v1/jobs/:jobId/progress.