Kuvan optimointi

Muunna ja optimoi IPFS:stä toimitettavia kuvia lennossa kyselyparametrien avulla. Tämä on julkinen päätepiste, joka ei vaadi autentikointia.

Optimera bild

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

Palauttaa annetun CID:n kuvan, joka on muunnettu annettujen kyselyparametrien mukaan. Jos muunnosparametreja ei anneta, pyyntö ohjataan 302-uudelleenohjauksella alkuperäiseen kuvaan IPFS-gatewayssa.

Path parameters

Parameter	Type	Required	Description
cid	string	Kyllä	Kuvan IPFS content identifier.

Query parameters

Parameter	Type	Default	Description
w	integer	—	Tulosteen leveys pikseleinä. Alue: 1–4096. Arvot ≤ 0 tai ei-numeeriset jätetään huomiotta.
h	integer	—	Tulosteen korkeus pikseleinä. Alue: 1–4096. Arvot ≤ 0 tai ei-numeeriset jätetään huomiotta.
format	string	—	Tulostemuoto: webp, jpeg, png tai avif. Kirjainkoko huomioidaan (pienet kirjaimet). Tuntemattomat arvot jätetään huomiotta.
quality	integer	80	Pakkauslaatu, 1–100. Koskee vain muotoja webp, jpeg ja avif. png on häviötön ja jättää tämän huomiotta.
fit	string	cover	Miten kuva sovitetaan mittoihin: cover, contain, fill, inside tai outside.

Huomio: parametrin nimi on quality, ei q. Yleisiä lyhenteitä (q, width, height, fmt) ei tunnisteta.

Pyyntö, joka ei sisällä yhtään parametreista w, h tai format, käsitellään no-op-toimintona ja ohjataan 302-uudelleenohjauksella alkuperäiseen kuvaan. quality ja fit yksinään eivät käynnistä muunnosta.

Fit modes

Mode	Behavior
cover	Rajaa kattamaan molemmat mitat (oletus).
contain	Sovita molempien mittojen sisään säilyttäen kuvasuhde. Voi jättää tyhjää tilaa (läpinäkyvä tai musta riippuen muodosta).
fill	Venytä täyttämään molemmat mitat tarkasti. Voi vääristää kuvaa.
inside	Kuten contain, mutta skaalaa vain alaspäin, ei koskaan ylöspäin.
outside	Kuten cover, mutta skaalaa vain alaspäin, ei koskaan ylöspäin.

Ylöspäin skaalaus

Muuntaja ei koskaan suurenna kuvaa sen lähdemittoja suuremmaksi. Jos pyydät w=2000 1200px leveälle lähdekuvalle, tuloste on 1200px leveä. Tämä koskee kaikkia fit-tiloja.

Response

Status	When	Body
200	Muunnos tuotettu tällä pyynnöllä.	Binääriset kuvatavut. Content-Type vastaa pyydettyä muotoa.
302	Muunnosparametreja ei annettu, tai aiemmin muunnettu tulos on jo välimuistissa.	Location-otsikko osoittaa alkuperäiseen kuvaan tai välimuistissa olevaan tulokseen osoitteessa https://ipfs.ninja/image-cache/....
400	cid-polkuparametri puuttuu.	{ "error": "cid required" }
404	CID:tä ei löytynyt gatewaysta.	{ "error": "CID not found" }
500	Odottamaton virhe (vioittunut kuva, muunnoksen epäonnistuminen jne.).	{ "error": "<message>" }

Kaikki 200- ja 302-välimuistivastaukset toimitetaan otsikolla Cache-Control: public, max-age=31536000, immutable. Katso Cachning alta.

Example requests

Skaalaa 400px leveäksi, muunna WebP-muotoon:

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

Skaalaa ja rajaa 200×200 pikkukuvaksi JPEG-muodossa 60 % laadulla:

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

Neliönmuotoinen pikkukuva letterboxing-tekniikalla rajauksen sijaan:

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

Muunna vain muoto, ei kokomuutosta (hyödyllinen vanhojen JPEG-kuvien AVIF/WebP-versioiden tarjoamiseen):

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

Rajoita enimmäisleveyttä pakottamatta korkeutta (säilyttää kuvasuhteen):

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

Using in HTML

Viittaa optimoituihin kuviin suoraan img-tageissa:

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

Tarjoa eri kokoja srcset-attribuutilla:

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

Moderni muotoneuvottelu <picture>-elementillä (AVIF → WebP → JPEG-varamuoto):

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

Käyttö Next.js:n kanssa

Mukautettuna lataajana next/image-komponentille:

// 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}
/>;

Cachning

Vastaukset toimitetaan otsikolla Cache-Control: public, max-age=31536000, immutable. Koska IPFS-sisältö on sisältöosoitteinen, sama CID samoilla parametreilla tuottaa aina saman tulosteen, joten selaimet ja CDN:t voivat välimuistittaa vastauksia rajoituksetta.

Välimuistiin tallennetut muunnokset säilytetään S3:ssa indeksoituna koko parametrijoukolla (cid, w, h, format, quality, fit). Seuraavat pyynnöt samoilla parametreilla palauttavat 302-uudelleenohjauksen CloudFront-välimuistiin (https://ipfs.ninja/image-cache/...) sen sijaan, että muunnos suoritettaisiin uudelleen. Eri parametriyhdistelmät tuottavat eri välimuistimerkinnät.

Tillganglighet

Kuvan optimointi on saatavilla kaikissa tilauksissa, mukaan lukien ilmainen Dharma-tilaus.