이미지 변환 API#

Snapkit의 이미지 변환 API를 사용하여 URL 파라미터로 실시간 이미지 변환을 수행하세요. Sharp 라이브러리 기반의 고성능 처리와 CloudFront CDN을 통해 전세계 어디서나 빠른 이미지 전송을 제공합니다.

빠른 시작#

기본 사용법#

업로드된 이미지 URL에 쿼리 파라미터를 추가하여 실시간으로 변환할 수 있습니다:

GET https://{organization}-cdn.snapkit.studio
  /{project}
  /{path}
  /{filename}
  ?transform=w:800,h:600,fit:cover,flip,grayscale,dpr:2

URL 구성 요소:

{organization}: 조직명 (예: acme-corp)
{project}: 프로젝트 이름
{path}: 폴더 경로
{filename}: 이미지 파일명
쿼리 파라미터: 변환 옵션 (w, h, fit 등)

주요 특징#

실시간 변환: URL 파라미터로 즉시 이미지 변환 실행
CDN 캐싱: 첫 변환 후 CloudFront에서 빠른 이미지 전송
자동 최적화: 브라우저에 맞는 최적 포맷 자동 선택
고해상도 지원: DPR(Device Pixel Ratio) 기반 반응형 이미지 생성

변환 파라미터 레퍼런스#

크기 및 레이아웃#

파라미터	타입	설명	기본값	제한
`w`	number	너비 (픽셀)	-	최대 4,096px
`h`	number	높이 (픽셀)	-	최대 4,096px
`fit`	string	맞춤 방식: `contain`, `cover`, `fill`, `inside`, `outside`	`cover`	-
`dpr`	number	Device Pixel Ratio	1.0	1.0-4.0

변형 및 효과#

파라미터	타입	설명	제한
`rotation`	number	회전 각도 (0-360도, 자동 정규화)	-
`flip`	boolean	상하 뒤집기	-
`flop`	boolean	좌우 뒤집기	-
`blur`	number	블러 강도	최대 20
`grayscale`	boolean	흑백 변환	-

영역 및 포맷#

파라미터 타입 설명 기본값 제한

extract

string

추출 영역: x-y-width-height 형식
0-100 사이 값은 백분율로 해석 (원본 이미지 크기 기준)
100 초과 값은 픽셀 단위로 처리

0-100 (백분율) 또는 픽셀 값

format

string

출력 포맷: jpeg, jpg, png, webp, avif, gif, tiff, animated-webp, auto

quality

number

이미지 품질 (JPEG/WebP/AVIF만 지원)

JPEG: 85

WebP: 85

AVIF: 80

1-100

애니메이션 최적화#

파라미터	타입	설명	기본값	제한
`fps`	number	프레임 레이트 (animated-webp 포맷 전용)	원본 유지	1-60
`frameRange`	string	프레임 범위 추출 (animated-webp 포맷 전용) `start-end` 형식 (예: `0-10`, `5-20`)	전체 프레임	start ≥ 0, end > start 최대 1000 프레임

Animated WebP란?

Animated WebP는 GIF를 대체하는 최신 애니메이션 이미지 포맷으로, 다음과 같은 장점이 있습니다:

60% 용량 절감: 동일한 품질로 GIF 대비 파일 크기 대폭 감소
품질 유지: 손실 압축임에도 시각적 품질 유지
부드러운 재생: fps 조정으로 프레임 레이트 최적화
빠른 로딩: 작은 파일 크기로 웹 페이지 성능 향상

사용 시나리오:

웹사이트 로딩 속도 개선이 필요한 경우
대용량 GIF 애니메이션을 최적화하고 싶을 때
모바일 환경에서 빠른 이미지 로딩이 중요한 경우
SNS나 메신저에서 공유할 애니메이션 최적화

주의사항:

fps와 frameRange는 format:animated-webp와 함께 사용해야 합니다
다른 포맷(jpeg, png 등)에서는 이 파라미터들이 무시됩니다
원본이 GIF가 아닌 경우 animated-webp 변환이 제대로 작동하지 않을 수 있습니다

실용적 사용 예시#

반응형 이미지 최적화#

데스크탑용 고해상도

?transform=w:800,h:600,dpr:2.0,format:webp,fit:cover

모바일 최적화

?transform=w:375,dpr:3,format:auto,fit:cover

썸네일 생성

?transform=w:200,h:200,fit:cover

고급 변환 조합#

포트폴리오 갤러리

?transform=w:400,h:300,grayscale,blur:1,format:webp

상품 이미지

?transform=w:600,h:600,fit:contain,format:auto

이미지 미리보기 (백분율 기반 영역 추출)

?transform=extract:25-25-50-50,w:300,format:jpeg

원본 이미지의 중앙 50% 영역을 추출 (각 방향 25% 오프셋)

GIF 애니메이션 최적화#

Animated WebP 변환 - GIF 대비 60% 용량 절감

?transform=format:animated-webp,quality:85

프레임 레이트 조정 - 부드러운 애니메이션

?transform=format:animated-webp,fps:24,quality:85

특정 프레임 구간 추출 - 0번부터 50번 프레임까지

?transform=format:animated-webp,frameRange:0-50

프레임 레이트 + 구간 추출 - 최적화된 애니메이션 생성

?transform=format:animated-webp,fps:30,frameRange:10-60,quality:80

기본 변환 옵션#

크기 조정

?transform=w:800,h:600,fit:cover

회전 및 뒤집기

?transform=rotation:90,flip

블러 및 흑백 효과

?transform=blur:2,grayscale

원본 이미지

크기 조정 적용 (transform=w:300,h:200,fit:cover)

변환 효과 시각화#

원본 이미지

크기 조정 + 고해상도 (transform=w:300,h:200,fit:cover,dpr:2.0)

원본

흑백 변환

블러 효과

원본

블러 적용 (transform=blur:5)

회전 효과 (transform=rotation:15,w:200)

Device Pixel Ratio (DPR) 활용#

고해상도 디스플레이 지원을 위해 이미지의 실제 크기를 조정하세요. 지정한 크기에 DPR 값을 곱해 실제 이미지 크기를 계산합니다.

DPR 작동 원리#

transform=w:300,dpr:1.0 → 실제 이미지 크기: 300px (300 × 1.0)
transform=w:300,dpr:1.5 → 실제 이미지 크기: 450px (300 × 1.5)
transform=w:300,dpr:2.0 → 실제 이미지 크기: 600px (300 × 2.0)

브라우저에서는 여전히 지정한 크기(300px)로 표시되지만, 실제로는 더 큰 이미지를 다운로드하여 선명하게 렌더링됩니다.

DPR 1.0 (실제 300px)

DPR 1.5 (실제 450px)

DPR 2.0 (실제 600px)

사용 예시#

데스크탑 표준 해상도

?transform=w:400,h:300,dpr:2

고해상도 Retina 모바일용

?transform=w:400,h:300,dpr:3

고품질 이미지 출력

?transform=w:1920,h:1080,format:webp,quality:95

용량 최적화 (낮은 품질)

?transform=w:800,h:600,format:webp,quality:60

변환 처리 순서#

이미지 변환은 다음 순서로 처리됩니다:

Extract (영역 추출) - 원본 이미지에서 영역 추출
Resize (크기 조정) - DPR 적용
Rotation (회전)
Flip/Flop (뒤집기)
Blur (블러 효과)
Grayscale (흑백 변환)
Format (포맷 변환)

복합 변환 예시#

여러 변환을 조합하여 사용할 수 있습니다:

크기 조정 + 흑백 변환 + 블러

?transform=w:400,h:300,grayscale,blur:2

영역 추출 + 회전

?transform=extract:25-25-50-50,rotation:90

고해상도 디스플레이 최적화

?transform=w:400,h:300,dpr:2.0,format:webp

모바일 반응형 이미지

?transform=w:375,dpr:1.5,format:auto,fit:cover

회전과 뒤집기 조합

?transform=rotation:45,flip,blur:1

성능 및 캐싱#

CloudFront CDN#

모든 변환된 이미지는 CloudFront CDN에 캐시되어 빠른 전송을 보장합니다:

첫 요청: 원본 이미지 변환 후 캐시 저장
후속 요청: 캐시된 이미지 즉시 전송
캐시 기간: 1년

Accept 헤더 기반 최적화#

format의 파라미터가 auto인 경우 브라우저의 Accept 헤더를 기반으로 최적의 포맷을 자동 선택합니다:

AVIF 지원 브라우저: AVIF 포맷으로 변환
WebP 지원 브라우저: WebP 포맷으로 변환
일반 브라우저: JPEG/PNG 포맷으로 변환

시스템 제한사항 및 안전장치#

처리 제한#

최대 이미지 크기: 4,096 x 4,096 픽셀
입력 픽셀 제한: 268,402,689 픽셀 (약 16K x 16K)
블러 강도: 최대 20 (CPU 보호)
DPR 범위: 1.0-4.0

자동 폴백 시스템#

변환 과정에서 문제 발생 시 자동 처리:

파라미터 오류: 잘못된 값 자동 수정
변환 실패: 원본 이미지 반환
메모리 부족: 처리 제한으로 시스템 안전성 확보
포맷 오류: 기본 JPEG 포맷으로 변환

메모리 최적화#

캐시 비활성화: Sharp 메모리 캐시 미사용
자동 정리: 처리 완료 후 Sharp 라이브러리 인스턴스 자동 해제
단일 처리: 메모리 보호를 위한 동시성 제한

통합 및 활용#

Next.js 통합 (준비중)#

현재 개발 중입니다. 곧 출시될 예정입니다.

최신 소식을 놓치고 싶지 않으시다면:

Discord 커뮤니티↗에 참여하세요
GitHub 저장소↗를 Star하고 Watch하세요
블로그에서 업데이트를 확인하세요

import { Image } from "@snapkit/nextjs";
 
<Image
  src="https://{organization}-<your-org>-cdn.snapkit.studio/{project}/images/hero.jpg"
  alt="Hero"
  width={800}
  height={600}
  transforms={{
    blur: 0,
    format: "auto",
    dpr: 2.0,
  }}
/>;

반응형 이미지 구현#

const getResponsiveUrl = (src: string, width: number, mobile = false) => {
  const dpr = mobile ? 1.5 : 3.0;
  return `${src}?transform=w:${width},dpr:${dpr},fit:cover,format:auto`;
};
 
// 사용 예시
<picture>
  <source media="(min-width: 768px)" srcSet={getResponsiveUrl(baseUrl, 800)} />
  <img src={getResponsiveUrl(baseUrl, 400, true)} alt="Responsive" />
</picture>;

다음 단계#

Next.js 통합 가이드 - @snapkit/nextjs로 웹 애플리케이션에 통합
Figma 플러그인 사용 - 디자인 워크플로우에서 직접 이미지 최적화
성능 최적화 팁 - 웹사이트 로딩 속도 개선 전략