Optimasi Gambar

Transformasi dan optimasi gambar yang disajikan dari IPFS secara on-the-fly menggunakan parameter kueri. Ini adalah endpoint publik yang tidak memerlukan autentikasi.

Optimasi Gambar

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

Mengembalikan gambar pada CID yang diberikan, ditransformasikan sesuai dengan parameter kueri yang disediakan. Jika tidak ada parameter transformasi yang disediakan, permintaan akan dialihkan dengan 302 ke gambar asli pada gateway IPFS.

Parameter path

Parameter	Tipe	Wajib	Deskripsi
cid	string	Ya	Pengidentifikasi konten IPFS dari gambar.

Parameter kueri

Parameter	Tipe	Default	Deskripsi
w	integer	—	Lebar output dalam piksel. Rentang: 1–4096. Nilai ≤ 0 atau non-numerik diabaikan.
h	integer	—	Tinggi output dalam piksel. Rentang: 1–4096. Nilai ≤ 0 atau non-numerik diabaikan.
format	string	—	Format output: webp, jpeg, png, atau avif. Sensitif huruf besar-kecil (huruf kecil). Nilai yang tidak dikenal diabaikan.
quality	integer	80	Kualitas kompresi, 1–100. Hanya berlaku untuk webp, jpeg, dan avif. png bersifat lossless dan mengabaikan ini.
fit	string	cover	Bagaimana gambar harus muat dengan dimensi: cover, contain, fill, inside, atau outside.

Catatan: parameternya adalah quality, bukan q. Alias singkatan umum (q, width, height, fmt) tidak dikenali.

Permintaan yang tidak menyediakan salah satu dari w, h, atau format diperlakukan sebagai no-op dan dialihkan dengan 302 ke gambar asli. quality dan fit saja tidak memicu transformasi.

Mode fit

Mode	Perilaku
cover	Memotong untuk menutupi kedua dimensi (default).
contain	Muat dalam kedua dimensi, mempertahankan rasio aspek. Mungkin meninggalkan ruang kosong (transparan atau hitam tergantung format).
fill	Meregang untuk mengisi kedua dimensi secara tepat. Dapat mendistorsi gambar.
inside	Seperti contain, tetapi hanya memperkecil, tidak pernah memperbesar.
outside	Seperti cover, tetapi hanya memperkecil, tidak pernah memperbesar.

Pembesaran

Transformer tidak pernah memperbesar gambar melebihi dimensi sumbernya. Jika Anda meminta w=2000 untuk sumber selebar 1200px, output akan menjadi 1200px lebar. Ini berlaku untuk semua mode fit.

Respons

Status	When	Body
200	Transformasi dihasilkan pada permintaan ini.	Byte gambar biner. Content-Type cocok dengan format yang diminta.
302	Tidak ada parameter transformasi yang disediakan, atau hasil yang sebelumnya ditransformasi sudah di-cache.	Header Location menunjuk ke gambar asli atau hasil yang di-cache di https://ipfs.ninja/image-cache/....
400	Parameter path cid hilang.	{ "error": "cid required" }
404	CID tidak ditemukan di gateway.	{ "error": "CID not found" }
500	Kesalahan tak terduga (gambar rusak, 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 ukuran menjadi 400px lebar, konversi ke WebP:

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

Ubah ukuran dan potong menjadi thumbnail 200×200 sebagai JPEG dengan kualitas 60%:

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

Thumbnail persegi dengan letterboxing alih-alih pemotongan:

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

Konversi format saja, tanpa mengubah ukuran (berguna untuk menyajikan versi AVIF/WebP dari JPEG lama):

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

Batasi lebar maksimum tanpa memaksa tinggi (mempertahankan rasio aspek):

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

Penggunaan di HTML

Referensikan gambar yang dioptimasi langsung dalam tag img:

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

Sajikan ukuran yang berbeda 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"
/>

Negosiasi format modern 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 kustom 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. Karena konten IPFS dialamati berdasarkan konten, CID yang sama dengan parameter yang sama selalu menghasilkan output yang sama, sehingga browser dan CDN dapat meng-cache respons tanpa batas waktu.

Transformasi yang di-cache disimpan di S3 dengan kunci berdasarkan kumpulan parameter lengkap (cid, w, h, format, quality, fit). Permintaan berikutnya dengan parameter yang sama mengembalikan pengalihan 302 ke cache yang difrontasi CloudFront (https://ipfs.ninja/image-cache/...) daripada menjalankan kembali transformasi. Kombinasi parameter yang berbeda menghasilkan entri cache yang berbeda.

Ketersediaan

Optimasi gambar tersedia di semua paket, termasuk paket Dharma gratis.