Tối ưu hóa Hình ảnh

Chuyển đổi và tối ưu hóa hình ảnh được phục vụ từ IPFS trực tiếp bằng tham số truy vấn. Đây là endpoint công khai không yêu cầu xác thực.

Tối ưu hóa Hình ảnh

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

Trả về hình ảnh tại CID đã cho, được chuyển đổi theo tham số truy vấn được cung cấp. Nếu không có tham số chuyển đổi nào được cung cấp, yêu cầu sẽ chuyển hướng 302 đến hình ảnh gốc trên cổng IPFS.

Tham số đường dẫn

Tham số	Kiểu	Bắt buộc	Mô tả
cid	string	Có	Mã định danh nội dung IPFS của hình ảnh.

Tham số truy vấn

Tham số	Kiểu	Mặc định	Mô tả
w	integer	—	Chiều rộng đầu ra tính bằng pixel. Phạm vi: 1–4096. Giá trị ≤ 0 hoặc không phải số bị bỏ qua.
h	integer	—	Chiều cao đầu ra tính bằng pixel. Phạm vi: 1–4096. Giá trị ≤ 0 hoặc không phải số bị bỏ qua.
format	string	—	Định dạng đầu ra: webp, jpeg, png, hoặc avif. Phân biệt chữ hoa chữ thường (chữ thường). Giá trị không xác định bị bỏ qua.
quality	integer	80	Chất lượng nén, 1–100. Chỉ áp dụng cho webp, jpeg và avif. png là không mất dữ liệu và bỏ qua tham số này.
fit	string	cover	Cách hình ảnh phù hợp với kích thước: cover, contain, fill, inside, hoặc outside.

Lưu ý: tham số là quality, không phải q. Các bí danh viết tắt phổ biến (q, width, height, fmt) không được nhận diện.

Một yêu cầu không cung cấp w, h hoặc format được coi là không hành động (no-op) và chuyển hướng 302 đến hình ảnh gốc. Chỉ có quality và fit không kích hoạt chuyển đổi.

Chế độ phù hợp

Chế độ	Hành vi
cover	Cắt để bao phủ cả hai chiều (mặc định).
contain	Vừa vặn trong cả hai chiều, giữ tỷ lệ khung hình. Có thể để trống không gian (trong suốt hoặc đen tùy theo định dạng).
fill	Kéo giãn để lấp đầy cả hai chiều chính xác. Có thể làm méo hình ảnh.
inside	Giống contain, nhưng chỉ thu nhỏ, không phóng to.
outside	Giống cover, nhưng chỉ thu nhỏ, không phóng to.

Phóng to

Bộ chuyển đổi không bao giờ phóng to hình ảnh vượt quá kích thước nguồn. Nếu bạn yêu cầu w=2000 cho nguồn rộng 1200px, đầu ra sẽ rộng 1200px. Điều này áp dụng cho tất cả các chế độ fit.

Phản hồi

Status	When	Body
200	Chuyển đổi được tạo trong yêu cầu này.	Byte hình ảnh nhị phân. Content-Type khớp với định dạng được yêu cầu.
302	Không có tham số chuyển đổi được cung cấp, hoặc kết quả đã chuyển đổi trước đó đã được lưu trong bộ nhớ đệm.	Tiêu đề Location trỏ đến hình ảnh gốc hoặc kết quả được lưu trong bộ nhớ đệm trên https://ipfs.ninja/image-cache/....
400	Thiếu tham số đường dẫn cid.	{ "error": "cid required" }
404	Không tìm thấy CID trên cổng.	{ "error": "CID not found" }
500	Lỗi không mong muốn (hình ảnh bị hỏng, chuyển đổi thất bại, v.v.).	{ "error": "<message>" }

Tất cả phản hồi 200 và 302 từ bộ nhớ đệm được phục vụ với Cache-Control: public, max-age=31536000, immutable. Xem Bộ nhớ đệm bên dưới.

Ví dụ yêu cầu

Thay đổi kích thước thành 400px rộng, chuyển đổi sang WebP:

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

Thay đổi kích thước và cắt thành hình thu nhỏ 200×200 dạng JPEG với chất lượng 60%:

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

Hình thu nhỏ vuông với letterboxing thay vì cắt:

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

Chỉ chuyển đổi định dạng, không thay đổi kích thước (hữu ích để phục vụ phiên bản AVIF/WebP của các JPEG cũ):

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

Giới hạn chiều rộng tối đa mà không bắt buộc chiều cao (giữ tỷ lệ khung hình):

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

Sử dụng trong HTML

Tham chiếu hình ảnh đã tối ưu trực tiếp trong thẻ img:

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

Phục vụ kích thước khác nhau với 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"
/>

Đàm phán định dạng hiện đại với <picture> (AVIF → WebP → JPEG dự phòng):

<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");
}

Sử dụng với Next.js

Như một loader tùy chỉnh cho 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}
/>;

Bộ nhớ đệm

Phản hồi được phục vụ với Cache-Control: public, max-age=31536000, immutable. Vì nội dung IPFS được định địa chỉ theo nội dung, cùng CID với cùng tham số luôn tạo ra cùng đầu ra, do đó trình duyệt và CDN có thể lưu các phản hồi vào bộ nhớ đệm vô thời hạn.

Các chuyển đổi đã lưu trong bộ nhớ đệm được lưu trữ trong S3 với khóa là toàn bộ tập tham số (cid, w, h, format, quality, fit). Các yêu cầu sau đó với cùng tham số trả về chuyển hướng 302 đến bộ nhớ đệm phía sau CloudFront (https://ipfs.ninja/image-cache/...) thay vì chạy lại chuyển đổi. Các tổ hợp tham số khác nhau tạo ra các mục bộ nhớ đệm khác nhau.

Khả dụng

Tối ưu hóa hình ảnh có sẵn trên tất cả các gói, bao gồm gói miễn phí Dharma.