compose_image

Stack workspace images into one flat PNG: overlays, backgrounds with a foreground, or collages.

A deterministic file operation: no model runs and no Creative Units are spent. Each layer places
one image in a box on the canvas (by default the size of the first layer's image), positioned by edge anchors and filled by its
resize strategy; layers stack bottom first and blend by their alpha. Parts of the canvas no
layer covers stay transparent.
The image is saved to the workspace library and, when the call runs in a session, placed on
its board (`image.placed_on_board`).

Parameters

Parameter	Type	Default	Description
width	integer1–4096	—	Canvas width in pixels. Omit to use the width of the first layer's image.
height	integer1–4096	—	Canvas height in pixels. Omit to use the height of the first layer's image.
layersrequired	ComposeImageLayer[]	—	The layers, bottom first: each later layer is drawn over the earlier ones.
file_idrequired	string (uuid)	—	Workspace file id of the image drawn in this layer.
anchors	Anchor	—	Pixel offsets of the layer box from the canvas edges. Both `left` and `right` set: the box spans between them (omit `width`). One set: the box sits that far from that edge. Neither: the box sits at the left edge. `top`/`bottom` work the same way vertically. To center an image or pin it to a corner without knowing its size, anchor all four sides (0, or the margin) and set the alignments.
top	integer	—	The top anchor position in pixels.
left	integer	—	The left anchor position in pixels.
bottom	integer	—	The bottom anchor position in pixels.
right	integer	—	The right anchor position in pixels.
width	integer1–4096	—	Layer width in pixels. Required unless both `left` and `right` are anchored.
height	integer1–4096	—	Layer height in pixels. Required unless both `top` and `bottom` are anchored.
resize_strategy	enum	place_and_crop	How the image fills the layer box: `stretch` distorts to the box; `fit_and_crop` scales to cover the box and crops the overflow (full-bleed backgrounds); `fit_and_pad` scales to fit inside the box and pads with `padding_color` (a logo or character in a box you size); `place_and_crop` keeps native scale and crops what exceeds the box. One of: stretch, fit_and_crop, fit_and_pad, place_and_crop
horizontal_alignment	enum	center	Where the image sits inside the layer box horizontally when it is cropped or padded. One of: left, center, right
vertical_alignment	enum	center	Where the image sits inside the layer box vertically when it is cropped or padded. One of: top, center, bottom
padding_color	RGBAColor	—	Fill for the padded part of the layer box. Transparent by default; `alpha` defaults to 255 when you pass a color.
red	integer0–255	0	The red component of the color
green	integer0–255	0	The green component of the color
blue	integer0–255	0	The blue component of the color
alpha	integer0–255	255	The alpha component of the color
rotation	enum	0	Turns the image clockwise by this many degrees before it is placed, losslessly; the box, the canvas it sizes and the resize strategy all apply to the turned image. 180 places a playing card's top-left index upside down in the bottom-right corner. One of: 0, 90, 180, 270
name	string0–120 chars	—	File name for the composed image.
workspace_idrequired	string (uuid)	—	The user's workspace id.
session_id	string (uuid)	—	Session whose board receives the image. Omit to only save it to the library.
project_id	string (uuid)	—	Optional project to add the result to; use list_projects to find project ids.