Composite (Overlay) Images

Overlay one image on top of a base image at a specified gravity and blend mode.

When to use

• Add a logo or watermark — place a brand mark in a corner of product images.
• Combine design layers — merge a background with a foreground graphic.
• Apply a frame or border overlay — superimpose a decorative frame PNG over photographs.

Inputs & outputs

Input modality	Image file (URL)
Output modality	Image file (GCS URL)
Max input size	50 MB (base + overlay combined)
Supported formats	JPEG, PNG, WebP

Parameters

Param	Required	Description
overlay_url	yes	URL of the image to overlay on the base. Must be publicly accessible or a GCS URL.
gravity	no	Position of the overlay — nw, n, ne, w, center (default), e, sw, s, se.
blend	no	Blend mode — over (default), multiply, screen, overlay, darken, lighten.

Examples

Logo in bottom-right corner

{
  "type": "image.composite",
  "input": { "image_url": "gs://infery-prod-media/photos/product.jpg" },
  "params": {
    "overlay_url": "gs://infery-prod-media/assets/logo.png",
    "gravity": "se",
    "blend": "over"
  }
}

Screen-blend texture overlay

{
  "type": "image.composite",
  "input": { "image_url": "gs://infery-prod-media/photos/portrait.jpg" },
  "params": {
    "overlay_url": "gs://infery-prod-media/textures/light-leak.png",
    "gravity": "center",
    "blend": "screen"
  }
}

Pricing

Billed per megapixel of output image. See pricing dashboard for current rates.

Related capabilities

• image.resize — resize overlay to desired dimensions before compositing
• image.add_alpha_channel — ensure overlay has transparency before blending
• image.pipeline — chain composite with other ops in a single execution

{
  "overlay_url": "gs://b/logo.png",
  "gravity": "se",
  "blend": "over"
}