콜라주 / 그리드

25개 이상의 템플릿으로 여러 이미지를 아름다운 그리드 콜라주로 결합합니다. 사용자 지정 간격, 모서리 반경, 배경색, 셀별 이동/확대·축소 컨트롤을 갖춘 2~9개 이미지 레이아웃을 지원합니다.

API 엔드포인트

POST /api/v1/tools/image/collage

매개변수

매개변수	유형	필수	기본값	설명
templateId	string	예	-	템플릿 레이아웃 ID (예: 2-h-equal, 3-left-large, 4-grid, 9-grid)
cells	array	아니요	-	imageIndex, panX, panY, zoom, objectFit을(를) 담은 셀별 설정 배열
cells[].imageIndex	integer	예	-	이 셀에 배치할 이미지의 인덱스 (0부터 시작)
cells[].panX	number	아니요	0	수평 이동 오프셋 (-100 ~ 100)
cells[].panY	number	아니요	0	수직 이동 오프셋 (-100 ~ 100)
cells[].zoom	number	아니요	1	확대/축소 수준 (1 ~ 10)
cells[].objectFit	string	아니요	"cover"	이미지가 셀을 채우는 방식: cover 또는 contain
gap	number	아니요	8	셀 간 간격(픽셀) (0 ~ 500)
cornerRadius	number	아니요	0	각 셀의 모서리 반경(픽셀) (0 ~ 500)
backgroundColor	string	아니요	"#FFFFFF"	배경색(16진수 또는 "transparent")
aspectRatio	string	아니요	"free"	캔버스 화면비: free, 1:1, 4:3, 3:2, 16:9, 9:16, 4:5
outputFormat	string	아니요	"png"	출력 형식: png, jpeg, webp, avif, jxl
quality	number	아니요	90	출력 품질 (1 ~ 100)

사용 가능한 템플릿

템플릿 ID	이미지	레이아웃
2-h-equal	2	동일한 두 개의 열
2-v-equal	2	동일한 두 개의 행
2-h-left-large	2	왼쪽 2/3, 오른쪽 1/3
2-h-right-large	2	왼쪽 1/3, 오른쪽 2/3
3-left-large	3	큰 왼쪽, 오른쪽에 두 개 세로 배치
3-right-large	3	왼쪽에 두 개 세로 배치, 큰 오른쪽
3-top-large	3	큰 위쪽, 아래에 두 개의 열
3-h-equal	3	동일한 세 개의 열
3-v-equal	3	동일한 세 개의 행
4-grid	4	2x2 그리드
4-left-large	4	큰 왼쪽, 오른쪽에 세 개 세로 배치
4-top-large	4	큰 위쪽, 아래에 세 개의 열
4-bottom-large	4	위에 세 개의 열, 큰 아래쪽
5-top2-bottom3	5	위에 두 개, 아래에 세 개
5-top3-bottom2	5	위에 세 개, 아래에 두 개
5-left-large	5	큰 왼쪽, 오른쪽에 네 개 세로 배치
5-center-large	5	큰 가운데, 네 모서리
6-grid-2x3	6	2열 x 3행
6-grid-3x2	6	3열 x 2행
6-top-large	6	큰 위쪽, 아래에 다섯 개의 열
7-mosaic	7	모자이크 레이아웃
8-mosaic	8	모자이크 레이아웃
9-grid	9	3x3 그리드

요청 예시

curl -X POST http://localhost:1349/api/v1/tools/image/collage \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F 'settings={"templateId":"4-grid","gap":12,"cornerRadius":8,"backgroundColor":"#F5F5F5","outputFormat":"png","quality":90}'

응답 예시

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

참고 사항

• multipart 요청에 여러 이미지 파일을 업로드하세요. 이미지는 업로드 순서대로 템플릿 셀에 할당됩니다.
• 템플릿이 지원하는 것보다 많은 이미지가 업로드되면 초과된 이미지는 무시됩니다.
• HEIC, RAW, PSD, SVG 입력 형식을 지원합니다(자동 디코딩).
• 캔버스 기본 크기는 가장 긴 변 기준 2400px이며, 선택한 화면비에 따라 조정됩니다.
• aspectRatio이(가) "free"일 때 캔버스는 기본적으로 4:3(2400x1800)으로 설정됩니다.
• 셀별 panX/panY 값은 셀 내에서 크롭 창을 이동합니다. 값이 100이면 한쪽 가장자리로 완전히 이동하고, -100이면 반대쪽으로 이동합니다.
• "transparent" 배경색은 png, webp 또는 avif 출력 형식에서만 유지됩니다.