Skip to content
smallPict
무료로 시작

이미지 최적화 API 엔드포인트

핵심 이미지 처리 엔드포인트 POST /v1/optimize에 대한 공식 기술 명세 리퍼런스.

이미지 최적화, 포맷 변환, 다운스케일 및 리사이징을 처리하는 핵심 엔드포인트는 다음과 같습니다:

POST https://api.smallpict.app/v1/optimize
(별칭: POST https://api.smallpict.app/v1/convert)

요청 형식 (JSON 페이로드)

HTTP
POST /v1/optimize HTTP/1.1Host: api.smallpict.appX-API-Key: sp_sdk_9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0bX-Timestamp: 1716301234X-Signature: 3a9f8b2c4d6e8a0f1b3c5d7e9f2a4b6c8d0e1f3a5b7c9d1e3f5a7b9c1d3e5f7aContent-Type: application/jsonIdempotency-Key: c9b8a7f6-e5d4-4c3b-2a1f-0e9d8c7b6a5f

요청 본문 스키마

JSON
{  "filename": "hero-banner.jpg",  "mime_type": "image/jpeg",  "filesize": 1654200,  "options": {    "format": "avif",    "quality": 80,    "max_dimension": 1600,    "max_width": 1920,    "max_height": 1080,    "lossless": false,    "strip_metadata": true  }}
필드타입필수 여부설명
filenamestring필수이미지 에셋의 원본 파일명 (예: banner.png)
mime_typestring필수MIME 타입 (예: image/jpeg, image/png, image/webp)
filesizeinteger필수파일 총 크기(바이트 단위, > 0)
options.formatstring선택변환 대상 포맷: avif, webp, original / keep, jpg, png (기본값: webp)
options.qualityinteger선택압축 품질 (1 ~ 100, 기본값: 80)
options.max_dimensioninteger선택긴 변 기준 비례 축소 최대 픽셀 제한 (예: 1600, 1920, 2048, 2560)
options.max_widthinteger선택최대 너비 픽셀 제한
options.max_heightinteger선택최대 높이 픽셀 제한
options.losslessboolean선택픽셀 무손실 압축 활성화 (기본값: false)
options.strip_metadataboolean선택카메라 EXIF 정보 및 색상 프로필 메타데이터 제거 (기본값: true)

실시간 이미지 변환 쿼리 파라미터

클라우드 변환 경로에서는 URL 쿼리 파라미터를 통해 실시간 리사이징 및 포맷 변환을 직접 실행할 수 있습니다:

GET https://api.smallpict.app/v1/transform?url=...&format=webp&quality=80&max_dimension=1600

  • ?format=avif|webp|original
  • ?quality=1..100
  • ?max_dimension=1600
  • ?max_width=1920
  • ?max_height=1080

응답 데이터 (200 OK)

요청이 성공적으로 초기화되면 SmallPict는 보안 업로드 URL과 비동기 작업 추적 ID를 반환합니다:

Response · 200 OK
{  "upload_url": "https://upload.smallpict.app/uploads/a1b2c3d4/hero-banner.jpg?signature=...",  "job_id": "job-a1b2c3d4",  "object_key": "uploads/a1b2c3d4/hero-banner.jpg",  "status": "queued"}

이미지 바이트를 HTTP PUT 요청으로 upload_url에 업로드한 뒤 작업 상태를 확인하세요. 보안 업로드 링크는 응답에 반환된 그대로 사용해야 하며, 짧은 시간 후 만료되고 이 업로드에만 유효합니다.

작업 처리 상태 확인

다음 엔드포인트를 통해 이미지 변환 진행 상태를 조회할 수 있습니다:

GET https://api.smallpict.app/v1/optimize/status?job_id=job-a1b2c3d4

처리 완료 응답 (200 OK)

Response · 200 OK
{  "job_id": "job-a1b2c3d4",  "status": "completed",  "url": "https://cdn.smallpict.app/opt/hero-banner.avif",  "format": "avif",  "bytes_saved": 1456200,  "savings_percentage": 88.03,  "created_at": "2026-08-23T08:00:00Z",  "updated_at": "2026-08-23T08:00:01Z"}