图片优化

使用查询参数实时变换和优化从 IPFS 提供的图片。这是一个无需认证的公共端点。

优化图片

GET /image/:cid

返回给定 CID 的图片，根据提供的查询参数进行变换。如果未提供参数，请求将重定向到原始图片。

路径参数

参数	类型	必填	描述
cid	string	是	图片的 IPFS 内容标识符。

查询参数

参数	类型	默认值	描述
w	number	—	输出宽度（像素）。最大 4096。
h	number	—	输出高度（像素）。最大 4096。
format	string	—	输出格式：webp、jpeg、png 或 avif。
quality	number	80	压缩质量，1-100。仅在设置 format 时生效。
fit	string	cover	图片适应尺寸的方式：cover、contain、fill、inside 或 outside。

适应模式

模式	行为
cover	裁剪以覆盖两个尺寸（默认）。
contain	适应两个尺寸内，保持宽高比。可能留有空白。
fill	拉伸以完全填充两个尺寸。可能导致图片变形。
inside	类似 contain，但只缩小不放大。
outside	类似 cover，但只缩小不放大。

请求示例

调整宽度为 400px，转换为 WebP：

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

调整并裁剪为 200x200 缩略图，JPEG 格式 60% 质量：

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

在 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"
/>

缓存

响应带有不可变缓存头。由于 IPFS 内容是内容寻址的，相同的 CID 和相同的参数总是产生相同的输出。浏览器和 CDN 可以无限期缓存这些响应。

可用性

图片优化在所有计划中可用，包括免费的 Dharma 计划。