حشو الصورة

احشُ صورة إلى نسبة عرض إلى ارتفاع مستهدفة بإضافة لون خالص أو خلفية شفافة أو مموّهة حولها. مفيد لملاءمة الصور في نسب عرض إلى ارتفاع ثابتة لوسائل التواصل الاجتماعي أو الطباعة دون اقتصاص.

نقطة نهاية API

POST /api/v1/tools/image/image-pad

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

المعاملات

المعامل	النوع	مطلوب	الافتراضي	الوصف
target	string	لا	"1:1"	نسبة العرض إلى الارتفاع المستهدفة: 16:9، 9:16، 1:1، 4:3، 3:4، أو custom
ratioW	integer	لا	1	عرض النسبة المخصصة (1-100، يُستخدم عندما يكون target هو custom)
ratioH	integer	لا	1	ارتفاع النسبة المخصصة (1-100، يُستخدم عندما يكون target هو custom)
background	string	لا	"color"	وضع الخلفية: color، transparent، أو blur
color	string	لا	"#ffffff"	لون خلفية hex (عندما تكون الخلفية color)
padding	integer	لا	0	حشو إضافي كنسبة مئوية من اللوحة (0-50)

مثال على طلب

curl -X POST http://localhost:1349/api/v1/tools/image/image-pad \
  -H "Authorization: Bearer si_your-api-key" \
  -F "[email protected]" \
  -F 'settings={"target": "16:9", "background": "blur", "padding": 5}'

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

{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/photo.jpg",
  "originalSize": 2450000,
  "processedSize": 3100000
}

ملاحظات

• ينشئ وضع الخلفية blur نسخة مموّهة من الصورة الأصلية كحشو للتعبئة، ما يُنتج نتيجة متماسكة بصرياً.
• عند استخدام خلفية transparent، تُحوَّل المخرجات إلى PNG للحفاظ على قناة alpha.
• تتطابق صيغة المخرجات مع صيغة الإدخال ما لم تكن هناك شفافية. تُفك ترميز إدخالات HEIC وRAW وPSD وSVG تلقائياً قبل المعالجة.
• عيّن target إلى custom ووفّر ratioW وratioH للحصول على نسب عرض إلى ارتفاع اعتباطية (مثل ratioW: 3, ratioH: 2 لـ 3:2).