画像最適化

クエリパラメータを使用して、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 のいずれも指定されないリクエストはノーオペレーションとして扱われ、元の画像へ 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 に変換：

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

200×200 サムネイルにリサイズ＆クロップ、JPEG で品質 60%：

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

クロップの代わりにレターボックスを使用した正方形のサムネイル：

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

リサイズせずにフォーマットのみ変換（レガシーな JPEG の AVIF/WebP 版を配信するのに便利）：

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

高さを強制せずに最大幅を制限（アスペクト比を保持）：

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

HTML での使用

最適化された画像を img タグで直接参照：

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

srcset で異なるサイズを提供：

<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 フォールバック）：

<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：

.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}`;
}

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 プランを含むすべてのプランで利用可能です。