Overlay images

POST /api/image-overlay

Overlay one image on top of another at a chosen position. Supports alpha transparency, configurable blend mode and opacity.

Composites a foreground image on top of a background image at the specified position. Inputs: - `background` / `foreground`: the two images. - `x` / `y` (default 0): pixel offset of the foreground's top-left. - `opacity` (default 1.0): foreground opacity multiplier. - `blend`: composition mode. `over` (default), `multiply`, `screen`, `overlay`, etc. Useful for adding logos, watermarks, or composing shots in design pipelines.

Inputs

Name	Type	Default	Description
image*	file	—	Background image bytes.
foreground*	file	—	Foreground image bytes.
gravity	enum (north \| south \| east \| west \| northeast \| northwest \| southeast \| southwest \| center)	"center"	Anchor for the foreground.
opacity	number (0…100)	100	Foreground opacity (percent).
scale	number (0…100)	0	Foreground scale relative to background's smaller side (0 = native).
offsetX	number (-8192…8192)	0	Horizontal offset in pixels.
offsetY	number (-8192…8192)	0	Vertical offset in pixels.
format	enum (png \| jpeg \| webp)	—	Output format. Defaults to the background's format.

Response

Modes: binary, json. Cache: yes (24h TTL).