圖片最佳化

使用查詢參數即時變換和最佳化從 IPFS 提供的圖片。這是一個無需驗證的公共端點。

最佳化圖片

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

傳回給定 CID 的圖片，根據提供的查詢參數進行變換。若未提供任何變換參數，請求會以 302 重新導向至 IPFS 閘道上的原始圖片。

路徑參數

參數	類型	必填	描述
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：

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"

以信箱模式（letterboxing）取代裁切的方形縮圖：

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。後續使用相同參數的請求會傳回 302 重新導向至 CloudFront 前置的快取（https://ipfs.ninja/image-cache/...），而不會重新執行變換。不同的參數組合會產生不同的快取項目。

可用性

圖片最佳化在所有方案中皆可使用，包括免費的 Dharma 方案。