Bildkomposition

Legt ein Overlay-Bild mit konfigurierbarer Position, Deckkraft und Mischmodus über ein Basisbild. Nützlich zum Zusammenstellen von Logos, Grafiken oder zum Kombinieren mehrerer Bilder.

API-Endpunkt

POST /api/v1/tools/image/compose

Akzeptiert Multipart-Formulardaten mit zwei Bilddateien und einem JSON-Feld settings.

Parameter

Parameter	Typ	Erforderlich	Standard	Beschreibung
x	number	Nein	0	Horizontaler Versatz des Overlays von der oberen linken Ecke in Pixeln (min. 0)
y	number	Nein	0	Vertikaler Versatz des Overlays von der oberen linken Ecke in Pixeln (min. 0)
opacity	number	Nein	100	Deckkraft des Overlays in Prozent (0 bis 100)
blendMode	string	Nein	"over"	Mischmodus für die Komposition

Mischmodi

Wert	Beschreibung
over	Normales Overlay (Standard)
multiply	Abdunkeln durch Multiplizieren der Pixelwerte
screen	Aufhellen durch Invertieren, Multiplizieren und erneutes Invertieren
overlay	Kombiniert Multiplizieren und Negativ multiplizieren je nach Helligkeit des Basisbildes
darken	Behält das dunklere Pixel jeder Ebene
lighten	Behält das hellere Pixel jeder Ebene
hard-light	Starkes Kontrast-Overlay
soft-light	Dezentes Kontrast-Overlay
difference	Absolute Differenz zwischen den Ebenen
exclusion	Ähnlich wie Differenz, aber mit geringerem Kontrast

Dateifelder

Feldname	Erforderlich	Beschreibung
file	Ja	Das Basis-/Hintergrundbild
overlay	Ja	Das Overlay-/Vordergrundbild

Beispielanfrage

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"}'

Mit dem Mischmodus Multiplizieren:

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"}'

Beispielantwort

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

Hinweise

• Beide Bilder werden vor der Komposition validiert und dekodiert (HEIC, RAW, PSD, SVG werden unterstützt).
• Das Overlay wird an den exakten Pixelkoordinaten platziert, die durch x und y angegeben werden. Es wird nicht passend skaliert.
• Ist die Deckkraft kleiner als 100, wird vor dem Mischen eine Alphamaske auf das Overlay angewendet.
• Das Overlay kann über die Grenzen des Basisbildes hinausragen (es wird dann beschnitten).
• Die EXIF-Ausrichtung wird vor der Verarbeitung automatisch auf beide Bilder angewendet.
• Die Ausgabeabmessungen entsprechen den Abmessungen des Basisbildes.