이미지 변환 API#

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

빠른 시작#

기본 사용법#

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

GET https://{organization}-cdn.snapkit.studio
  /{project}
  /{path}
  /{filename}
  ?w=800&h=600&fit=cover&flip=true&grayscale=true&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%)	각각 0-100%
`format`	string	출력 포맷: `jpeg`, `jpg`, `png`, `webp`, `avif`, `auto`

실용적 사용 예시#

반응형 이미지 최적화#

데스크탑용 고해상도

?w=800&h=600&dpr=2.0&format=webp&fit=cover

모바일 최적화

?w=375&dpr=3&format=auto&fit=cover

썸네일 생성

?w=200&h=200&fit=cover

고급 변환 조합#

포트폴리오 갤러리

?w=400&h=300&grayscale=true&blur=1&format=webp

상품 이미지

?w=600&h=600&fit=contain&format=auto

이미지 미리보기

?extract=25,25,50,50&w=300&format=jpeg

기본 변환 옵션#

크기 조정

?w=800&h=600&fit=cover

회전 및 뒤집기

?rotation=90&flip=true

블러 및 흑백 효과

?blur=2&grayscale=true

원본 이미지

크기 조정 적용 (w=300&h=200&fit=cover)

변환 효과 시각화#

원본 이미지

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

원본

흑백 변환

블러 효과

원본

블러 적용 (blur=5)

회전 효과 (rotation=15)

Device Pixel Ratio (DPR) 활용#

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

DPR 작동 원리#

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

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

DPR 1.0 (실제 300px)

DPR 1.5 (실제 450px)

DPR 2.0 (실제 600px)

사용 예시#

데스크탑 표준 해상도

?w=400&h=300&dpr=2

고해상도 Retina 모바일용

?w=400&h=300&dpr=3

변환 처리 순서#

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

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

복합 변환 예시#

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

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

?w=400&h=300&grayscale=true&blur=2

영역 추출 + 회전

?extract=25,25,50,50&rotation=90

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

?w=400&h=300&dpr=2.0&format=webp

모바일 반응형 이미지

?w=375&dpr=1.5&format=auto&fit=cover

회전과 뒤집기 조합

?rotation=45&flip=true&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}?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 플러그인 사용 - 디자인 워크플로우에서 직접 이미지 최적화
성능 최적화 팁 - 웹사이트 로딩 속도 개선 전략