图片优化

使用查询参数实时变换和优化从 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 中任何一个的请求将被视为空操作，并通过 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 计划。