Pengoptimuman Imej

Transformasi dan optimumkan imej yang disajikan dari IPFS secara on-the-fly menggunakan parameter pertanyaan. Ini ialah endpoint awam yang tidak memerlukan pengesahan.

Optimumkan Imej

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

Mengembalikan imej pada CID yang diberikan, ditransformasikan mengikut parameter pertanyaan yang disediakan. Jika tiada parameter transformasi disediakan, permintaan akan dilencongkan dengan 302 ke imej asal pada gateway IPFS.

Parameter laluan

Parameter	Jenis	Diperlukan	Penerangan
cid	string	Ya	Pengecam kandungan IPFS bagi imej.

Parameter pertanyaan

Parameter	Jenis	Lalai	Penerangan
w	integer	—	Lebar output dalam piksel. Julat: 1–4096. Nilai ≤ 0 atau bukan angka diabaikan.
h	integer	—	Tinggi output dalam piksel. Julat: 1–4096. Nilai ≤ 0 atau bukan angka diabaikan.
format	string	—	Format output: webp, jpeg, png, atau avif. Sensitif huruf besar-kecil (huruf kecil). Nilai yang tidak dikenali diabaikan.
quality	integer	80	Kualiti pemampatan, 1–100. Hanya berkenaan untuk webp, jpeg, dan avif. png adalah tanpa kehilangan dan mengabaikan ini.
fit	string	cover	Cara imej harus muat dengan dimensi: cover, contain, fill, inside, atau outside.

Nota: parameter ialah quality, bukan q. Alias singkatan biasa (q, width, height, fmt) tidak dikenali.

Permintaan yang tidak menyediakan mana-mana daripada w, h, atau format dianggap sebagai no-op dan dilencongkan dengan 302 ke imej asal. quality dan fit sahaja tidak mencetuskan transformasi.

Mod fit

Mod	Tingkah laku
cover	Potong untuk meliputi kedua-dua dimensi (lalai).
contain	Muat dalam kedua-dua dimensi, mengekalkan nisbah aspek. Mungkin meninggalkan ruang kosong (lutsinar atau hitam bergantung pada format).
fill	Regangkan untuk mengisi kedua-dua dimensi dengan tepat. Boleh memesongkan imej.
inside	Seperti contain, tetapi hanya mengecilkan, tidak pernah membesarkan.
outside	Seperti cover, tetapi hanya mengecilkan, tidak pernah membesarkan.

Pembesaran skala

Transformer tidak pernah membesarkan imej melebihi dimensi sumbernya. Jika anda meminta w=2000 untuk sumber selebar 1200px, output akan menjadi 1200px lebar. Ini berkenaan untuk semua mod fit.

Respons

Status	When	Body
200	Transformasi dihasilkan pada permintaan ini.	Bait imej binari. Content-Type sepadan dengan format yang diminta.
302	Tiada parameter transformasi disediakan, atau hasil yang ditransformasikan sebelum ini sudah di-cache.	Header Location menunjuk ke imej asal atau hasil yang di-cache pada https://ipfs.ninja/image-cache/....
400	Parameter laluan cid hilang.	{ "error": "cid required" }
404	CID tidak dijumpai pada gateway.	{ "error": "CID not found" }
500	Ralat tidak dijangka (imej rosak, kegagalan transformasi, dll.).	{ "error": "<message>" }

Semua respons cache 200 dan 302 disajikan dengan Cache-Control: public, max-age=31536000, immutable. Lihat Caching di bawah.

Contoh permintaan

Ubah saiz kepada 400px lebar, tukar kepada WebP:

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

Ubah saiz dan potong kepada thumbnail 200×200 sebagai JPEG pada kualiti 60%:

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

Thumbnail segi empat sama dengan letterboxing dan bukannya pemotongan:

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

Tukar format sahaja, tiada perubahan saiz (berguna untuk menyajikan versi AVIF/WebP daripada JPEG lama):

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

Hadkan lebar maksimum tanpa memaksa tinggi (mengekalkan nisbah aspek):

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

Penggunaan dalam HTML

Rujuk imej yang dioptimumkan secara langsung dalam tag img:

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

Sajikan saiz berbeza dengan 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"
/>

Rundingan format moden dengan <picture> (AVIF → WebP → JPEG fallback):

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

Penggunaan dengan Next.js

Sebagai loader tersuai untuk 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}
/>;

Caching

Respons disajikan dengan Cache-Control: public, max-age=31536000, immutable. Memandangkan kandungan IPFS dialamatkan berdasarkan kandungan, CID yang sama dengan parameter yang sama sentiasa menghasilkan output yang sama, jadi pelayar dan CDN boleh menyimpan respons dalam cache tanpa had masa.

Transformasi yang di-cache disimpan di S3 berkunci pada set parameter penuh (cid, w, h, format, quality, fit). Permintaan seterusnya dengan parameter yang sama mengembalikan pelencongan 302 ke cache yang dihadapi CloudFront (https://ipfs.ninja/image-cache/...) dan bukan menjalankan semula transformasi. Kombinasi parameter yang berbeza menghasilkan entri cache yang berbeza.

Ketersediaan

Pengoptimuman imej tersedia pada semua pelan, termasuk pelan Dharma percuma.