Asset Options

Multiple assets can be passed in the request. Each asset can have its own options for canvas size, initial fill color, cropping, positioning, and output disposition.

Parameters

Parameter	Type	Description
canvas	JSON	(optional) Canvas options for the image. Canvas is optional if bg_add is specified.
canvas.color	string	(optional) Color applied to the canvas on initialization. If not provided, set to transparent.
canvas.size	JSON	Canvas dimensions as { "width": ..., "height": ... }.
size	JSON	(optional) Size of the output image as { "width": ..., "height": ... }.
crop	JSON	(optional) Crop dimensions as { "left": ..., "top": ..., "right": ..., "bottom": ... }.
position	JSON	(optional) Position of the image asset on the canvas as { "x": ..., "y": ... }. Defaults to center.
disposition.add_as_conversion	boolean	If true, output is added as a conversion to the original asset. Default: false.
disposition.create_asset	boolean	If true, output is added as a new asset. Default: false.
disposition.conversion_name	string	Name for the conversion (max 30 alphanumeric characters, no spaces). Required when add_as_conversion is true.
disposition.mode	string	Mode for adding metadata to the new asset: APPEND or REPLACE.
disposition.data_schema_id	integer	Asset Schema ID of the metadata to be added to the new asset.
disposition.metadata	JSON	(optional) Metadata specification for new assets.
disposition.metadata.inherit	boolean	Whether the new asset should inherit all metadata from the parent asset.
disposition.metadata.src_asset_id	string	Asset ID of the source asset whose metadata is to be inherited.
disposition.metadata.inherit_fields	list	Metadata keys from the source asset to inherit.
disposition.metadata.data	JSON	Custom metadata to add to the new asset.

Notes

• If crop is provided, the crop dimensions (left, top, right, bottom) must be relative to the original image size. For example, if the original asset is 2000×2000, a crop of [left:0, top:0, right:100, bottom:200] crops to that region. Invalid crop parameters will produce incorrect output.
• When crop is specified, the original asset is retrieved and cropped first, then the cropped image is used in all subsequent processing operations.
• If add_as_conversion is true, the conversion_name must follow the naming specification. metadata will be ignored.
• If add_as_conversion is false, conversion_name will be ignored. The metadata field (if provided) will be used to add metadata to the new asset.
• If inherit is true and inherit_fields is not provided, all source asset custom metadata fields (including data_schema_id) are inherited.
• If inherit is false and data is not provided, the new asset will not have any metadata.