SnapOtter/apps/docs/tools/image/collage.md

description

description
Combine multiple images into grid collages with 25+ templates, adjustable gaps and corners, and per-cell pan and zoom.

Collage & Grid

Combine multiple images into beautiful grid collages with 25+ templates. Supports 2-9 image layouts with customizable gap, corner radius, background color, and per-cell pan/zoom controls.

API Endpoint

POST /api/v1/tools/image/collage

Parameters

Parameter	Type	Required	Default	Description
templateId	string	Yes	-	Template layout ID (e.g. 2-h-equal, 3-left-large, 4-grid, 9-grid)
cells	array	No	-	Per-cell settings array with imageIndex, panX, panY, zoom, objectFit
cells[].imageIndex	integer	Yes	-	Index of the image to place in this cell (0-based)
cells[].panX	number	No	0	Horizontal pan offset (-100 to 100)
cells[].panY	number	No	0	Vertical pan offset (-100 to 100)
cells[].zoom	number	No	1	Zoom level (1 to 10)
cells[].objectFit	string	No	"cover"	How image fills cell: cover or contain
gap	number	No	8	Gap between cells in pixels (0 to 500)
cornerRadius	number	No	0	Corner radius for each cell in pixels (0 to 500)
backgroundColor	string	No	"#FFFFFF"	Background color as hex or "transparent"
aspectRatio	string	No	"free"	Canvas aspect ratio: free, 1:1, 4:3, 3:2, 16:9, 9:16, 4:5
outputFormat	string	No	"png"	Output format: png, jpeg, webp, avif, jxl
quality	number	No	90	Output quality (1 to 100)

Available Templates

Template ID	Images	Layout
2-h-equal	2	Two equal columns
2-v-equal	2	Two equal rows
2-h-left-large	2	Left 2/3, right 1/3
2-h-right-large	2	Left 1/3, right 2/3
3-left-large	3	Large left, two stacked right
3-right-large	3	Two stacked left, large right
3-top-large	3	Large top, two columns bottom
3-h-equal	3	Three equal columns
3-v-equal	3	Three equal rows
4-grid	4	2x2 grid
4-left-large	4	Large left, three stacked right
4-top-large	4	Large top, three columns bottom
4-bottom-large	4	Three columns top, large bottom
5-top2-bottom3	5	Two top, three bottom
5-top3-bottom2	5	Three top, two bottom
5-left-large	5	Large left, four stacked right
5-center-large	5	Large center, four corners
6-grid-2x3	6	2 columns x 3 rows
6-grid-3x2	6	3 columns x 2 rows
6-top-large	6	Large top, five columns bottom
7-mosaic	7	Mosaic layout
8-mosaic	8	Mosaic layout
9-grid	9	3x3 grid

Example Request

curl -X POST http://localhost:1349/api/v1/tools/image/collage \
  -F "file=@photo1.jpg" \
  -F "file=@photo2.jpg" \
  -F "file=@photo3.jpg" \
  -F "file=@photo4.jpg" \
  -F 'settings={"templateId":"4-grid","gap":12,"cornerRadius":8,"backgroundColor":"#F5F5F5","outputFormat":"png","quality":90}'

Example Response

{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/collage.png",
  "originalSize": 2456789,
  "processedSize": 1823456
}

Notes

• Upload multiple image files in the multipart request. The images are assigned to template cells in upload order.
• If more images are uploaded than the template supports, extra images are ignored.
• Supports HEIC, RAW, PSD, and SVG input formats (automatically decoded).
• The canvas base size is 2400px on the longest side, scaled by the chosen aspect ratio.
• When aspectRatio is "free", the canvas defaults to 4:3 (2400x1800).
• Per-cell panX/panY values shift the crop window within the cell. A value of 100 moves fully to one edge, -100 to the other.
• The "transparent" background color is only preserved with png, webp, or avif output formats.