# Merge several images into one image Robot: `/image/merge` 🤖/image/merge merges several images into a single spritesheet. The final result will be a spritesheet, with the images displayed horizontally, vertically, or in a grid layout. It's recommended to use this Robot with [🤖/image/resize](/docs/robots/image-resize.md) so your images are of a similar size before merging them. Stage: ga ## Usage example Merge uploaded images into one, with a 5px gap between them on the spritesheet: ```json { "steps": { "merged": { "robot": "/image/merge", "use": { "steps": [ ":original" ], "bundle_steps": true }, "border": 5 } } } ``` ## Parameters * `interpolate`: Controls whether Assembly Variables are interpolated for individual instruction fields. By default, most Robot instruction fields interpolate Assembly Variables. Set this to `false` to treat every instruction field as literal text, or set an individual field path to `false` to treat only that field as literal text. For Robot-specific fields that are literal by default, set this to `true` or set that field path to `true` to opt back into interpolation. Use field names such as `path`, or dotted paths such as `ffmpeg.vf` for nested objects. * `output_meta`: Allows you to specify a set of metadata that is more expensive on CPU power to calculate, and thus is disabled by default to keep your Assemblies processing fast. For images, you can add `"has_transparency": true` in this object to extract if the image contains transparent parts and `"dominant_colors": true` to extract an array of hexadecimal color codes from the image. For images, you can also add `"blurhash": true` to extract a [BlurHash](https://blurha.sh) string — a compact representation of a placeholder for the image, useful for showing a blurred preview while the full image loads. For videos, you can add the `"colorspace": true` parameter to extract the colorspace of the output video. For videos, you can also add `"interlaced": true` to detect whether the video is interlaced. This combines the cheap ffprobe `field_order` flag with a bounded `idet` sampling pass over the first frames of the source, exposing `interlaced`, `field_order`, and a diagnostic `interlace_detection` object under `file.meta`. This is computationally expensive and billed accordingly. For audio, you can add `"mean_volume": true` to get a single value representing the mean average volume of the audio file. You can also set this to `false` to skip metadata extraction and speed up transcoding. * `user_meta`: Adds custom metadata to each file emitted by this Robot without modifying the file’s contents. The values are merged with any existing `user_meta` carried by the input file. If both objects contain the same key, this Robot’s value takes precedence. Assembly Variables are supported, for example `{ "internal_file_id": "${file.id}" }`. * `result`: Whether the results of this Step should be present in the Assembly Status JSON * `queue`: Setting the queue to 'batch', manually downgrades the priority of jobs for this step to avoid consuming Priority job slots for jobs that don't need zero queue waiting times * `force_accept`: Force a Robot to accept a file type it would have ignored. By default, Robots ignore files they are not familiar with. [🤖/video/encode](/docs/robots/video-encode.md), for example, will happily ignore input images. With the `force_accept` parameter set to `true`, you can force Robots to accept all files thrown at them. This will typically lead to errors and should only be used for debugging or combatting edge cases. * `ignore_errors`: Ignore errors during specific phases of processing. Setting this to `["meta"]` will cause the Robot to ignore errors during metadata extraction. Setting this to `["execute"]` will cause the Robot to ignore errors during the main execution phase. Setting this to `true` is equivalent to `["meta", "execute"]` and will ignore errors in both phases. * `use`: Specifies which Step(s) to use as input. * You can pick any names for Steps except `":original"` (reserved for user uploads handled by Transloadit) * You can provide several Steps as input with arrays: ```json { "use": [ ":original", "encoded", "resized" ] } ``` * You can also tag input Steps with `as` to pass semantic intent to robots: ```json { "use": [ { "name": ":original", "as": "image" }, { "name": ":original", "as": "mask" } ] } ``` > [!Tip] > That's likely all you need to know about `use`, but you can view [Advanced use cases](/docs/topics/use-parameter.md). * `format`: The output format for the modified image. * `direction`: Specifies the direction which the images are displayed. Use `grid` to arrange inputs left-to-right and top-to-bottom. Only applies to the default spritesheet layout. Ignored when `effect` is set to `polaroid-stack` or `mosaic`, as those effects use their own layout algorithms. * `effect`: Applies a styled collage layout instead of a plain horizontal or vertical spritesheet. Currently supports `polaroid-stack`, which renders the inputs as overlapping instant photos on a canvas, and `mosaic`, which builds a justified tiled collage. * `columns`: Number of columns in the grid layout. Only applies when `direction` is `grid`. If omitted, columns are calculated automatically from the number of inputs and requested rows. * `rows`: Number of rows in the grid layout. Only applies when `direction` is `grid`. If omitted, rows are calculated automatically from the number of inputs and requested columns. * `cell_width`: Uniform width for each grid cell in pixels. Only applies when `direction` is `grid`. Images are resized to fit within the cell while preserving aspect ratio. * `cell_height`: Uniform height for each grid cell in pixels. Only applies when `direction` is `grid`. Images are resized to fit within the cell while preserving aspect ratio. * `border`: An integer value which defines the gap between images on the spritesheet. A value of `10` would cause the images to have the largest gap between them, while a value of `1` would place the images side-by-side. When `effect` is `polaroid-stack`, this value is instead used as canvas padding so the outermost photos keep that many pixels of distance from the edge. When `effect` is `mosaic`, this value is used both as the outer canvas padding and as the gutter width between neighboring tiles. * `background`: Either the hexadecimal code or [name](https://www.imagemagick.org/script/color.php#color_names) of the color used to fill the background (only shown with a border > 1). By default, the background of transparent images is changed to white. Set to `none` or `transparent` for a transparent canvas — set `format` to `png` or `webp` to preserve alpha. For details about how to preserve transparency across all image types, see [this demo](/demos/image-processing/properly-preserve-transparency-across-all-image-types.md). * `width`: The output canvas width in pixels. This is mainly used by styled effects such as `polaroid-stack` and `mosaic`. * `height`: The output canvas height in pixels. This is mainly used by styled effects such as `polaroid-stack` and `mosaic`. * `seed`: Optional deterministic seed used by styled effects such as `polaroid-stack` and `mosaic`. * `shuffle`: Whether styled effects such as `polaroid-stack` and `mosaic` may shuffle the input order before laying out the canvas. * `sort_by`: Controls how bundled inputs are ordered when no explicit numbered alias for the input type is used. Numbered aliases end with a numeric suffix such as `_1`. The default `"basename"` keeps the legacy natural basename sorting behavior. Set this to `"import_order"` to preserve the order of array-based import steps when all input files carry complete import order metadata. `"auto"` has the same import-order preference with natural basename sorting as fallback. * `coverage`: Area-coverage multiplier for the `polaroid-stack` effect. Controls how large each polaroid is relative to the canvas and consequently how much of the canvas is covered by photos. The default of `1.5` leaves a subtle beige border along some edges. Use `2.0`–`2.5` for edge-to-edge coverage (photos overlap more). Values below `1.0` produce smaller, more widely spaced polaroids. Has no effect on the `mosaic` style or on plain spritesheets. * `adaptive_filtering`: Controls the image compression for PNG images. Setting to `true` results in smaller file size, while increasing processing time. It is encouraged to keep this option disabled. * `quality`: Controls the image compression for JPG, PNG, and WebP images. Please also take a look at [🤖/image/optimize](/docs/robots/image-optimize.md).