صورة إلى Base64

حوّل صورة واحدة أو أكثر إلى سلاسل مُرمّزة بـ base64 وdata URIs. يدعم تحويل الصيغة الاختياري والتحكم في الجودة وإعادة التحجيم. مفيد لتضمين الصور مباشرة في HTML أو CSS أو JSON أو قوالب البريد الإلكتروني.

نقطة نهاية API

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

يقبل بيانات نموذج multipart تحتوي على ملف صورة واحد أو أكثر وحقل JSON اختياري settings.

المعاملات

المعامل	النوع	مطلوب	الافتراضي	الوصف
outputFormat	string	لا	"original"	التحويل قبل الترميز: original، jpeg، png، webp، avif، jxl
quality	number	لا	80	جودة المخرجات للصيغ ذات الفقدان (1 إلى 100)
maxWidth	number	لا	0	أقصى عرض بالبكسل (0 = بلا إعادة تحجيم، لن يتم التكبير)
maxHeight	number	لا	0	أقصى ارتفاع بالبكسل (0 = بلا إعادة تحجيم، لن يتم التكبير)

مثال على طلب

curl -X POST http://localhost:1349/api/v1/tools/image/image-to-base64 \
  -H "Authorization: Bearer si_your-api-key" \
  -F "[email protected]" \
  -F 'settings={"outputFormat": "webp", "quality": 80, "maxWidth": 200}'

ملفات متعددة:

curl -X POST http://localhost:1349/api/v1/tools/image/image-to-base64 \
  -H "Authorization: Bearer si_your-api-key" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F 'settings={"outputFormat": "original"}'

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

{
  "results": [
    {
      "filename": "icon.png",
      "mimeType": "image/webp",
      "width": 200,
      "height": 200,
      "originalSize": 45000,
      "encodedSize": 28800,
      "overheadPercent": -36.0,
      "base64": "UklGRlYAAABXRUJQ...",
      "dataUri": "data:image/webp;base64,UklGRlYAAABXRUJQ..."
    }
  ],
  "errors": []
}

حقول الاستجابة

الحقل	النوع	الوصف
results	array	الصور التي تم تحويلها بنجاح
errors	array	الصور التي فشلت في المعالجة (مع اسم الملف ورسالة الخطأ)

كائن النتيجة

الحقل	النوع	الوصف
filename	string	اسم الملف الأصلي
mimeType	string	نوع MIME للمخرجات المُرمّزة
width	number	العرض النهائي بالبكسل (بعد أي إعادة تحجيم)
height	number	الارتفاع النهائي بالبكسل (بعد أي إعادة تحجيم)
originalSize	number	حجم الملف الأصلي بالبايت
encodedSize	number	حجم سلسلة base64 بالبايت
overheadPercent	number	نسبة فرق الحجم مقابل الأصل (موجب = أكبر، سالب = أصغر)
base64	string	بيانات الصورة الخام المُرمّزة بـ base64
dataUri	string	data URI كامل جاهز للاستخدام في سمات src

ملاحظات

• عادةً ما يزيد ترميز base64 الحجم بنحو 33٪ مقارنةً بالملف الثنائي. يُظهر حقل overheadPercent الفرق الفعلي.
• عندما يكون outputFormat هو "original"، تُحوَّل ملفات HEIC/HEIF إلى JPEG (لأن المتصفحات لا تستطيع عرض HEIC في data URIs).
• يعيد خيارا maxWidth وmaxHeight التحجيم باستخدام fit: inside مع withoutEnlargement، لذا لا يتم تكبير الصور الأصغر من الأبعاد المحددة.
• يمكن معالجة ملفات متعددة في طلب واحد. تتم معالجة كل ملف على حدة، والفشل لا يمنع نجاح الملفات الأخرى.
• تُمرَّر ملفات SVG كما هي بصيغة image/svg+xml دون إعادة ترميز (ما لم يُطلب تحويل صيغة).
• هذه نقطة نهاية للقراءة فقط. لا تُنتج ملفاً قابلاً للتنزيل ولا jobId. تُرجَع بيانات base64 مباشرة في جسم الاستجابة.