Image Optimization

Mag-transform at mag-optimize ng mga imahe na served mula sa IPFS on-the-fly gamit ang mga query parameter. Ito ay public endpoint na hindi nangangailangan ng authentication.

I-optimize ang Imahe

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

Ibinabalik ang imahe sa ibinigay na CID, na-transform ayon sa mga query parameter na ibinigay. Kung walang ibinigay na transform parameter, ang request ay magre-redirect ng 302 sa orihinal na imahe sa IPFS gateway.

Path parameters

Parameter	Uri	Kinakailangan	Paglalarawan
cid	string	Oo	Ang IPFS content identifier ng imahe.

Query parameters

Parameter	Uri	Default	Paglalarawan
w	integer	—	Output width sa pixels. Range: 1–4096. Mga value na ≤ 0 o hindi numeric ay hindi pinapansin.
h	integer	—	Output height sa pixels. Range: 1–4096. Mga value na ≤ 0 o hindi numeric ay hindi pinapansin.
format	string	—	Output format: webp, jpeg, png, o avif. Case-sensitive (lowercase). Hindi pinapansin ang hindi kilalang values.
quality	integer	80	Compression quality, 1–100. Naa-apply lamang sa webp, jpeg, at avif. Ang png ay lossless at hindi pinapansin ito.
fit	string	cover	Paano dapat mag-fit ang imahe sa dimensions: cover, contain, fill, inside, o outside.

Note: ang parameter ay quality, hindi q. Hindi kinikilala ang mga karaniwang shorthand alias (q, width, height, fmt).

Ang request na hindi nagbibigay ng w, h, o format ay itinuturing na no-op at nagre-redirect ng 302 sa orihinal na imahe. Ang quality at fit lamang ay hindi nagti-trigger ng transform.

Fit modes

Mode	Behavior
cover	Mag-crop upang sakupin ang parehong dimensions (default).
contain	Mag-fit sa loob ng parehong dimensions, pinapanatili ang aspect ratio. Maaaring magkaroon ng walang lamang espasyo (transparent o itim depende sa format).
fill	Mag-stretch upang punuin nang eksakto ang parehong dimensions. Maaaring mag-distort ng imahe.
inside	Tulad ng contain, ngunit nagliit lamang, hindi naman lumalaki.
outside	Tulad ng cover, ngunit nagliit lamang, hindi naman lumalaki.

Upscaling

Hindi kailanman nilalaki ng transformer ang imahe nang lampas sa source dimensions nito. Kung humihingi ka ng w=2000 para sa source na 1200px ang lapad, ang output ay magiging 1200px ang lapad. Ito ay naa-apply sa lahat ng fit modes.

Response

Status	When	Body
200	May ginawang transform sa request na ito.	Binary image bytes. Tumutugma ang Content-Type sa hiniling na format.
302	Walang ibinigay na transform params, o naka-cache na ang dating na-transform na resulta.	Itinuturo ng Location header ang orihinal na imahe o ang naka-cache na resulta sa https://ipfs.ninja/image-cache/....
400	Nawawala ang cid path parameter.	{ "error": "cid required" }
404	Hindi nakita ang CID sa gateway.	{ "error": "CID not found" }
500	Hindi inaasahang error (sirang imahe, transform failure, atbp.).	{ "error": "<message>" }

Ang lahat ng 200 at 302-cache na response ay sineserve gamit ang Cache-Control: public, max-age=31536000, immutable. Tingnan ang Caching sa ibaba.

Mga halimbawang request

I-resize sa 400px ang lapad, i-convert sa WebP:

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

I-resize at i-crop sa 200×200 thumbnail bilang JPEG sa 60% quality:

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

Square thumbnail na may letterboxing sa halip na cropping:

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

I-convert lang ang format, walang resize (kapaki-pakinabang para mag-serve ng AVIF/WebP versions ng mga lumang JPEG):

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

I-cap ang maximum width nang hindi pinipilit ang height (pinapanatili ang aspect ratio):

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

Paggamit sa HTML

Tukuyin ang mga na-optimize na imahe nang direkta sa mga img tag:

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

Maghain ng iba't ibang sukat gamit ang 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"
/>

Modernong format negotiation gamit ang <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");
}

Paggamit kasama ang Next.js

Bilang custom loader para sa 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

Ang mga response ay sineserve gamit ang Cache-Control: public, max-age=31536000, immutable. Dahil ang IPFS content ay content-addressed, ang parehong CID na may parehong parameter ay laging gumagawa ng parehong output, kaya maaaring i-cache ng mga browser at CDN ang mga response nang walang taning.

Ang mga naka-cache na transform ay naka-store sa S3 na naka-key sa kumpletong parameter set (cid, w, h, format, quality, fit). Ang mga sumunod na request na may parehong parameter ay nagbabalik ng 302 redirect sa CloudFront-fronted cache (https://ipfs.ninja/image-cache/...) sa halip na patakbuhin muli ang transform. Ang iba't ibang kumbinasyon ng parameter ay gumagawa ng iba't ibang cache entries.

Availability

Available ang image optimization sa lahat ng plan, kabilang ang libreng Dharma plan.