Otimização de Imagens

Transforme e otimize imagens servidas a partir do IPFS em tempo real usando parâmetros de consulta. Este é um endpoint público que não requer autenticação.

Otimizar Imagem

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

Devolve a imagem no CID indicado, transformada de acordo com os parâmetros de consulta fornecidos. Se não forem fornecidos parâmetros de transformação, o pedido devolve um redireccionamento 302 para a imagem original no gateway IPFS.

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
cid	string	Sim	O identificador de conteúdo IPFS da imagem.

Parâmetros de consulta

Parâmetro	Tipo	Predefinição	Descrição
w	integer	—	Largura de saida em pixels. Intervalo: 1–4096. Valores ≤ 0 ou não numéricos são ignorados.
h	integer	—	Altura de saida em pixels. Intervalo: 1–4096. Valores ≤ 0 ou não numéricos são ignorados.
format	string	—	Formato de saida: webp, jpeg, png ou avif. Sensível a maiúsculas e minúsculas (em minúsculas). Valores desconhecidos são ignorados.
quality	integer	80	Qualidade de compressão, 1–100. Aplica-se apenas a webp, jpeg e avif. png é sem perdas e ignora-o.
fit	string	cover	Como a imagem se deve ajustar às dimensoes: cover, contain, fill, inside ou outside.

Nota: o parâmetro é quality, não q. Os alias abreviados habituais (q, width, height, fmt) não são reconhecidos.

Um pedido que não forneça nenhum de w, h ou format é tratado como uma operação nula e devolve um redireccionamento 302 para a imagem original. quality e fit por si só não desencadeiam uma transformação.

Modos de ajuste

Modo	Comportamento
cover	Recortar para cobrir ambas as dimensoes (predefinição).
contain	Ajustar dentro de ambas as dimensoes, preservando a proporção. Pode deixar espaço vazio (transparente ou preto consoante o formato).
fill	Esticar para preencher exactamente ambas as dimensoes. Pode distorcer a imagem.
inside	Como contain, mas só reduz, nunca aumenta.
outside	Como cover, mas só reduz, nunca aumenta.

Ampliação

O transformador nunca amplia uma imagem para além das dimensoes da origem. Se pedir w=2000 para uma origem com 1200px de largura, a saida terá 1200px de largura. Isto aplica-se a todos os modos fit.

Resposta

Estado	Quando	Corpo
200	Foi produzida uma transformação neste pedido.	Bytes binários da imagem. Content-Type corresponde ao formato solicitado.
302	Não foram fornecidos parâmetros de transformação, ou um resultado anteriormente transformado já se encontra em cache.	O cabeçalho Location aponta para a imagem original ou para o resultado em cache em https://ipfs.ninja/image-cache/....
400	Parâmetro de caminho cid em falta.	{ "error": "cid required" }
404	CID não encontrado no gateway.	{ "error": "CID not found" }
500	Erro inesperado (imagem corrompida, falha na transformação, etc.).	{ "error": "<message>" }

Todas as respostas 200 e as respostas 302 em cache são servidas com Cache-Control: public, max-age=31536000, immutable. Veja Cache abaixo.

Exemplos de pedidos

Redimensionar para 400px de largura, converter para WebP:

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

Redimensionar e recortar para miniatura 200×200 como JPEG a 60% de qualidade:

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

Miniatura quadrada com margens em vez de recorte:

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

Apenas conversão de formato, sem redimensionar (útil para servir versões AVIF/WebP de JPEGs antigos):

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

Limitar a largura máxima sem forçar a altura (preserva a proporção):

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

Utilização em HTML

Referencie imagens otimizadas directamente nas etiquetas img:

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

Sirva diferentes tamanhos com 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"
/>

Negociação de formatos modernos com <picture> (AVIF → WebP → recurso JPEG):

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

Imagem de fundo em CSS:

.hero {
  background-image: url("https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=1600&format=webp&quality=70");
}

Utilização com Next.js

Como loader personalizado para 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}
/>;

Cache

As respostas são servidas com Cache-Control: public, max-age=31536000, immutable. Uma vez que o conteúdo IPFS é endereçado por conteúdo, o mesmo CID com os mesmos parâmetros produz sempre a mesma saida, pelo que os navegadores e CDNs podem manter as respostas em cache indefinidamente.

As transformações em cache são armazenadas no S3 indexadas pelo conjunto completo de parâmetros (cid, w, h, format, quality, fit). Pedidos subsequentes com os mesmos parâmetros devolvem um redireccionamento 302 para a cache servida pelo CloudFront (https://ipfs.ninja/image-cache/...) em vez de voltar a executar a transformação. Combinações diferentes de parâmetros produzem entradas de cache diferentes.

Disponibilidade

A otimização de imagens está disponível em todos os planos, incluindo o plano gratuito Dharma.