[Documentation] cdn 썸네일 이미지 요청 양식 #39
Description
이미지 리사이징 API 사용 가이드
기본 사용법
원본 이미지 URL에 쿼리 파라미터를 추가하여 원하는 크기로 리사이징된 이미지를 요청할 수 있습니다.
기본 형식: https://cdn.chalpu.com/원본이미지경로?s=크기&t=타입&q=품질&f=포맷
필수 파라미터
s (size) - 크기
이미지 크기를 가로x세로 형식으로 지정합니다.
?s=200x200 # 200x200 픽셀
?s=400x300 # 400x300 픽셀
?s=1920x1080 # 1920x1080 픽셀
t (type) - 리사이징 타입
이미지를 어떻게 크기 조정할지 지정합니다.
crop - 정확한 크기로 자르기 (기본값)
원본 이미지를 정확히 요청한 크기로 맞춘 후, 넘치는 부분은 잘라냅니다.
원본 이미지: 1000x600 (가로가 김)
요청 크기: 200x200 (정사각형)
결과: 200x200 정사각형 이미지 (양쪽 끝이 잘림)
[원본: ████████████████] → [결과: ████]
긴 직사각형 정사각형
언제 사용하나요?
- 썸네일 (정확한 크기 필요)
- 프로필 사진 (정사각형 필수)
- 카드형 레이아웃 (일정한 크기)
inside - 비율 유지하며 안에 맞추기
원본 이미지 비율을 유지하면서 요청한 크기 안에 들어가도록 축소합니다.
원본 이미지: 1000x600 (가로가 김)
요청 크기: 200x200 (정사각형)
결과: 200x120 (비율 유지, 위아래 여백)
[원본: ████████████████] → [결과: ████████]
긴 직사각형
언제 사용하나요?
- 상세 이미지 (전체 내용 보여줘야 할 때)
- 갤러리 (원본 비율 유지)
- 로고 이미지 (찌그러지면 안 됨)
outside - 비율 유지하며 채우기
원본 이미지 비율을 유지하면서 요청한 크기를 완전히 채웁니다.
원본 이미지: 1000x600 (가로가 김)
요청 크기: 200x200 (정사각형)
결과: 200x200 (비율 유지하되 위아래가 잘림)
[원본: ████████████████] → [결과: ████]
긴 직사각형
언제 사용하나요?
- 배경 이미지 (전체 영역 채우기)
- 히어로 배너 (빈 공간 없이)
- 카드 배경 (영역 완전히 채우기)
실제 예시:
<!-- 썸네일: 정확한 정사각형 -->
<img src="https://cdn.chalpu.com/food.jpg?s=200x200&t=crop&q=80" alt="썸네일">
<!-- 상세 이미지: 전체 내용 보이게 -->
<img src="https://cdn.chalpu.com/food.jpg?s=400x300&t=inside&q=85" alt="상세">
<!-- 배경 이미지: 영역 완전히 채우기 -->
<img src="https://cdn.chalpu.com/food.jpg?s=800x400&t=outside&q=80" alt="배경">q (quality) - 품질
이미지 압축 품질을 1-100 사이로 지정합니다.
?q=90 # 고품질 (파일 크기 큼)
?q=80 # 일반 품질 (권장)
?q=60 # 저품질 (파일 크기 작음)
선택 파라미터
f (format) - 포맷
출력 이미지 포맷을 지정합니다. (기본값: 원본과 동일)
?f=webp # WebP 포맷 (용량 작음, 최신 브라우저)
?f=jpeg # JPEG 포맷 (호환성 좋음)
?f=png # PNG 포맷 (투명도 지원)
사용 예시
1썸네일 생성
<!-- 200x200 썸네일, 정사각형으로 자르기 -->
<img src="https://cdn.chalpu.com/foodPhoto/pizza.jpg?s=200x200&t=crop&q=80" alt="피자 썸네일">
<!-- 150x150 썸네일, WebP 포맷 -->
<img src="https://cdn.chalpu.com/foodPhoto/pasta.jpg?s=150x150&t=crop&q=80&f=webp" alt="파스타 썸네일">성능 최적화 팁
1. 적절한 품질 설정
// 용도별 권장 품질
const qualitySettings = {
thumbnail: 70, // 썸네일: 저품질로도 충분
menu: 80, // 메뉴 이미지: 일반 품질
hero: 90, // 메인 이미지: 고품질
detail: 85 // 상세 이미지: 중간 품질
};2. 캐시 활용
동일한 URL은 CDN에서 캐시되므로, 파라미터 순서를 일정하게 유지해야함.
// 좋은 예: 항상 같은 순서
const url1 = 'https://cdn.chalpu.com/image.jpg?s=200x200&t=crop&q=80&f=webp';
const url2 = 'https://cdn.chalpu.com/image.jpg?s=200x200&t=crop&q=80&f=webp'; // 캐시 히트
// 나쁜 예: 순서가 다름
const url3 = 'https://cdn.chalpu.com/image.jpg?t=crop&s=200x200&q=80&f=webp'; // 캐시 미스무조건 같은 이미지면 쿼리 파라미터 순서 맞춰줘야함.
에러 처리
지원되지 않는 이미지 포맷
지원되지 않는 이미지 파일 요청 시 403 에러가 반환됨.
1MB 응답 제한 초과
너무 큰 이미지 요청 시 413 에러가 반환될 수 있음. 용량 낮춰야함.
// 에러 처리 예시
function handleImageError(img) {
// 품질을 낮춰서 재시도
const originalSrc = img.src;
const newSrc = originalSrc.replace(/q=\d+/, 'q=60');
if (originalSrc !== newSrc) {
img.src = newSrc;
} else {
// 기본 이미지로 대체
img.src = 'https://cdn.chalpu.com/default-image.jpg';
}
}지원 이미지 포맷
입력 포맷
- JPG, JPEG
- PNG
- GIF
- WebP
- SVG
- TIFF
출력 포맷
- JPEG (기본값)
- PNG
- WebP
- TIFF