이미지 최적화

쿼리 매개변수를 사용하여 IPFS에서 제공되는 이미지를 실시간으로 변환하고 최적화하세요. 인증이 필요 없는 공개 엔드포인트입니다.

이미지 최적화

GET https://api.ipfs.ninja/image/:cid

주어진 CID의 이미지를 제공된 쿼리 매개변수에 따라 변환하여 반환합니다. 변환 매개변수가 제공되지 않으면 요청은 IPFS 게이트웨이의 원본 이미지로 302 리다이렉트됩니다.

경로 매개변수

매개변수	유형	필수	설명
`cid`	string	예	이미지의 IPFS 콘텐츠 식별자.

쿼리 매개변수

매개변수	유형	기본값	설명
`w`	integer	—	출력 너비(픽셀). 범위: 1–4096. 0 이하 또는 숫자가 아닌 값은 무시됩니다.
`h`	integer	—	출력 높이(픽셀). 범위: 1–4096. 0 이하 또는 숫자가 아닌 값은 무시됩니다.
`format`	string	—	출력 형식: `webp`, `jpeg`, `png` 또는 `avif`. 대소문자 구분(소문자). 알 수 없는 값은 무시됩니다.
`quality`	integer	`80`	압축 품질, 1–100. `webp`, `jpeg`, `avif`에만 적용됩니다. `png`는 무손실이며 이를 무시합니다.
`fit`	string	`cover`	이미지가 치수에 맞는 방식: `cover`, `contain`, `fill`, `inside` 또는 `outside`.

참고: 매개변수 이름은 quality이며, q가 아닙니다. 일반적인 약어(q, width, height, fmt)는 인식되지 않습니다.

w, h, format 중 어느 것도 제공하지 않은 요청은 무동작(no-op)으로 처리되어 원본 이미지로 302 리다이렉트됩니다. quality와 fit만으로는 변환이 발생하지 않습니다.

적합 모드

모드	동작
`cover`	두 치수를 모두 덮도록 자릅니다(기본).
`contain`	종횡비를 유지하면서 두 치수 안에 맞춥니다. 빈 공간이 남을 수 있습니다(형식에 따라 투명 또는 검정).
`fill`	두 치수를 정확히 채우도록 늘립니다. 이미지가 왜곡될 수 있습니다.
`inside`	`contain`과 유사하지만 축소만 하고 확대하지 않습니다.
`outside`	`cover`와 유사하지만 축소만 하고 확대하지 않습니다.

업스케일링

변환기는 이미지를 원본 치수 이상으로 확대하지 않습니다. 1200px 너비의 원본에 대해 w=2000을 요청하면 출력은 1200px 너비가 됩니다. 이는 모든 fit 모드에 적용됩니다.

응답

Status	When	Body
`200`	이번 요청에서 변환이 생성된 경우.	바이너리 이미지 바이트. `Content-Type`은 요청한 형식과 일치합니다.
`302`	변환 매개변수가 제공되지 않았거나, 이전에 변환된 결과가 이미 캐시된 경우.	`Location` 헤더는 원본 이미지 또는 `https://ipfs.ninja/image-cache/...`의 캐시된 결과를 가리킵니다.
`400`	`cid` 경로 매개변수가 누락된 경우.	`{ "error": "cid required" }`
`404`	CID를 게이트웨이에서 찾을 수 없는 경우.	`{ "error": "CID not found" }`
`500`	예기치 않은 오류(손상된 이미지, 변환 실패 등).	`{ "error": "<message>" }`

모든 200 및 302 캐시 응답은 Cache-Control: public, max-age=31536000, immutable로 제공됩니다. 아래의 캐싱을 참조하세요.

요청 예시

너비 400px로 리사이즈, WebP로 변환:

bash

curl "https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=400&format=webp"

200×200 썸네일로 리사이즈 및 자르기, JPEG 60% 품질:

bash

curl "https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=200&h=200&format=jpeg&quality=60&fit=cover"

자르기 대신 레터박스를 사용한 정사각형 썸네일:

bash

curl "https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=200&h=200&format=png&fit=contain"

리사이즈 없이 형식만 변환(레거시 JPEG의 AVIF/WebP 버전 제공에 유용):

bash

curl "https://api.ipfs.ninja/image/QmXmCX9S6ANV...?format=avif&quality=70"

높이를 강제하지 않고 최대 너비 제한(종횡비 유지):

bash

curl "https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=1200&format=webp"

HTML에서 사용

최적화된 이미지를 img 태그에서 직접 참조하세요:

html

<img
  src="https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=800&format=webp&quality=75"
  alt="Optimized IPFS image"
/>

srcset으로 다양한 크기 제공:

html

<img
  srcset="
    https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=400&format=webp 400w,
    https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=800&format=webp 800w,
    https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=1200&format=webp 1200w
  "
  sizes="(max-width: 600px) 400px, (max-width: 1000px) 800px, 1200px"
  src="https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=800&format=webp"
  alt="Responsive IPFS image"
/>

<picture>를 사용한 최신 형식 협상(AVIF → WebP → JPEG 폴백):

html

<picture>
  <source
    type="image/avif"
    srcset="https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=800&format=avif&quality=60"
  />
  <source
    type="image/webp"
    srcset="https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=800&format=webp&quality=75"
  />
  <img
    src="https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=800&format=jpeg&quality=80"
    alt="IPFS image with format fallback"
  />
</picture>

CSS background-image:

css

.hero {
  background-image: url("https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=1600&format=webp&quality=70");
}

Next.js와 함께 사용

next/image의 사용자 정의 로더로:

// loaders/ipfs.js
export default function ipfsLoader({ src, width, quality }) {
  return `https://api.ipfs.ninja/image/${src}?w=${width}&format=webp&quality=${quality || 75}`;
}

jsx

import Image from "next/image";
import ipfsLoader from "@/loaders/ipfs";

<Image
  loader={ipfsLoader}
  src="QmXmCX9S6ANV..."
  alt="IPFS image"
  width={800}
  height={600}
/>;

캐싱

응답은 Cache-Control: public, max-age=31536000, immutable로 제공됩니다. IPFS 콘텐츠는 콘텐츠 주소 지정 방식이므로 동일한 CID와 동일한 매개변수는 항상 동일한 출력을 생성하며, 브라우저와 CDN은 응답을 무기한 캐시할 수 있습니다.

캐시된 변환은 전체 매개변수 세트(cid, w, h, format, quality, fit)로 키를 지정하여 S3에 저장됩니다. 동일한 매개변수로 후속 요청 시 변환을 재실행하는 대신 CloudFront 기반 캐시(https://ipfs.ninja/image-cache/...)로 302 리다이렉트를 반환합니다. 다른 매개변수 조합은 다른 캐시 항목을 생성합니다.

가용성

이미지 최적화는 무료 Dharma 플랜을 포함한 모든 플랜에서 사용할 수 있습니다.

이미지 최적화 ​