Image Composition

ضع صورة متراكبة فوق صورة أساسية مع موضع وشفافية ووضع مزج قابل للتهيئة. مفيد لتركيب الشعارات أو الرسومات أو دمج عدة صور.

API Endpoint

POST /api/v1/tools/image/compose

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

Parameters

Parameter	Type	Required	Default	Description
x	number	No	0	الإزاحة الأفقية للطبقة المتراكبة من الزاوية العلوية اليسرى بالبكسل (الحد الأدنى 0)
y	number	No	0	الإزاحة العمودية للطبقة المتراكبة من الزاوية العلوية اليسرى بالبكسل (الحد الأدنى 0)
opacity	number	No	100	نسبة شفافية الطبقة المتراكبة (0 إلى 100)
blendMode	string	No	"over"	وضع مزج التركيب

Blend Modes

Value	Description
over	تراكب عادي (افتراضي)
multiply	تعتيم بضرب قيم البكسل
screen	تفتيح بالعكس ثم الضرب ثم العكس مرة أخرى
overlay	يجمع بين الضرب والشاشة استنادًا إلى سطوع الأساس
darken	الاحتفاظ بالبكسل الأغمق من كل طبقة
lighten	الاحتفاظ بالبكسل الأفتح من كل طبقة
hard-light	تراكب تباين قوي
soft-light	تراكب تباين خفيف
difference	الفرق المطلق بين الطبقتين
exclusion	مشابه للفرق لكن بتباين أقل

File Fields

Field Name	Required	Description
file	Yes	الصورة الأساسية/الخلفية
overlay	Yes	الصورة المتراكبة/الأمامية

Example Request

curl -X POST http://localhost:1349/api/v1/tools/image/compose \
  -H "Authorization: Bearer si_your-api-key" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F 'settings={"x": 100, "y": 50, "opacity": 80, "blendMode": "over"}'

باستخدام وضع مزج الضرب:

curl -X POST http://localhost:1349/api/v1/tools/image/compose \
  -H "Authorization: Bearer si_your-api-key" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F 'settings={"x": 0, "y": 0, "opacity": 50, "blendMode": "multiply"}'

Example Response

{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/background.jpg",
  "originalSize": 3200000,
  "processedSize": 3450000
}

Notes

• تُتحقَّق كلتا الصورتين وتُفَكّ شفرتهما (HEIC وRAW وPSD وSVG مدعومة) قبل التركيب.
• تُوضَع الطبقة المتراكبة عند إحداثيات البكسل المحددة بالضبط بواسطة x وy. ولا يُعاد تحجيمها لتلائم.
• إذا كانت الشفافية أقل من 100، يُطبَّق قناع ألفا على الطبقة المتراكبة قبل المزج.
• يمكن أن تمتد الطبقة المتراكبة إلى ما وراء حدود الصورة الأساسية (وستُقتَص).
• يُطبَّق اتجاه EXIF تلقائيًا على كلتا الصورتين قبل المعالجة.
• تطابق أبعاد الإخراج أبعاد الصورة الأساسية.