홈▸개발문서▸워크플로우▸Step 4: Images

Step 4: 이미지 업로드 가이드

포토북에 사용할 이미지의 지원 포맷, 크기 제한, 자동 처리 방식, 배치 모드를 안내합니다.

지원 이미지 포맷

다음 이미지 포맷을 지원합니다.

포맷확장자비고
JPEG.jpg, .jpeg가장 일반적인 사진 포맷
PNG.png투명 배경 지원
GIF.gif첫 번째 프레임만 사용
BMP.bmp비압축 비트맵
WebP.webp구글 포맷, 자동 변환 처리
HEIC / HEIF.heic, .heifiPhone 기본 포맷, 자동으로 JPEG 변환
SVG는 지원하지 않습니다. 벡터 이미지(SVG)는 업로드할 수 없습니다. SVG 이미지를 사용해야 하는 경우, 먼저 PNG 또는 JPEG로 변환(래스터라이즈)한 후 업로드하세요.

자동 처리

업로드된 이미지는 서버에서 자동으로 다음 처리를 수행합니다.

처리설명
HEIC/HEIF 변환HEIC/HEIF 포맷은 자동으로 JPEG로 변환됩니다. 별도의 사전 변환이 필요 없습니다.
EXIF 회전 보정EXIF 메타데이터의 방향(orientation) 정보를 읽어 이미지를 올바른 방향으로 자동 회전합니다.
썸네일 생성업로드된 이미지의 썸네일을 자동 생성합니다. 최대 800px 크기로 리사이즈됩니다.
원본 이미지는 그대로 보존됩니다. 자동 처리는 인쇄 렌더링과 썸네일 표시에만 적용됩니다.

이미지 배치 모드

이미지가 템플릿의 이미지 영역에 배치될 때 두 가지 모드가 적용될 수 있습니다.

모드동작잘림 여부사용 예
cover (채우기)영역을 완전히 채우도록 이미지를 확대/축소합니다. 비율이 다르면 일부가 잘립니다.잘릴 수 있음전면 사진, 배경 이미지
contain (맞추기)이미지 전체가 영역 안에 보이도록 축소합니다. 비율이 다르면 여백이 생깁니다.잘리지 않음로고, 일러스트
배치 모드는 템플릿의 이미지 요소에 미리 설정되어 있습니다. API 호출 시 별도로 지정할 필요는 없습니다.

파일 크기 제한

항목제한비고
요청당 최대 크기200MB하나의 업로드 요청에 포함된 전체 파일 크기 합계
개별 파일 크기제한 없음요청당 최대 크기 이내라면 개별 파일 크기 제한 없음

해상도 권장사항

이미지 해상도에 대한 명시적 제한은 없지만, 인쇄 품질을 위해 고해상도 이미지를 권장합니다.

  • 인쇄 품질 기준으로 300 DPI 이상을 권장합니다.
  • 저해상도 이미지는 인쇄 시 흐릿하게 출력될 수 있습니다.
  • 스마트폰 기본 카메라로 촬영한 사진은 대부분 충분한 해상도를 가지고 있습니다.
SNS에서 다운로드한 이미지, 스크린샷, 메신저로 전송받은 이미지는 압축되어 해상도가 낮을 수 있습니다. 원본 이미지 사용을 권장합니다.

썸네일 자동 생성

업로드된 이미지에 대해 썸네일이 자동 생성됩니다. 썸네일은 긴 변 기준 최대 800px로 리사이즈되며, 앱에서 미리보기 용도로 활용할 수 있습니다.

json
{
  "fileName": "abc123_photo.jpg",
  "originalUrl": "https://storage.sweetbook.com/originals/abc123_photo.jpg",
  "thumbnailUrl": "https://storage.sweetbook.com/thumbnails/abc123_photo_thumb.jpg",
  "width": 4032,
  "height": 3024
}

업로드 예시

bash
curl -X POST 'https://api.sweetbook.com/v1/books/{bookUid}/photos' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'files=@photo1.jpg' \
  -F 'files=@photo2.jpg' \
  -F 'files=@photo3.heic'
json
{
  "success": true,
  "message": "Success",
  "data": {
    "photos": [
      {
        "fileName": "abc123_photo1.jpg",
        "thumbnailUrl": "https://storage.sweetbook.com/thumbnails/abc123_photo1_thumb.jpg",
        "width": 4032,
        "height": 3024
      },
      {
        "fileName": "def456_photo2.jpg",
        "thumbnailUrl": "https://storage.sweetbook.com/thumbnails/def456_photo2_thumb.jpg",
        "width": 3000,
        "height": 4000
      },
      {
        "fileName": "ghi789_photo3.jpg",
        "thumbnailUrl": "https://storage.sweetbook.com/thumbnails/ghi789_photo3_thumb.jpg",
        "width": 4032,
        "height": 3024
      }
    ]
  }
}
HEIC 파일(photo3.heic)이 자동으로 JPEG로 변환되어 .jpg 확장자로 반환된 것을 확인하세요.

다음 단계