Otimização de Imagens

Transforme e otimize imagens servidas 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

Retorna a imagem no CID fornecido, transformada de acordo com os parâmetros de consulta fornecidos. Se nenhum parâmetro de transformação for fornecido, a requisição retorna um redirecionamento 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	Padrã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. Diferencia maiúsculas de 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 isso.
fit	string	cover	Como a imagem deve se ajustar as dimensoes: cover, contain, fill, inside ou outside.

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

Uma requisição que não forneça nenhum de w, h ou format é tratada como uma operação nula e retorna um redirecionamento 302 para a imagem original. quality e fit sozinhos não acionam uma transformação.

Modos de ajuste

Modo	Comportamento
cover	Recortar para cobrir ambas as dimensoes (padrão).
contain	Ajustar dentro de ambas as dimensoes, preservando a proporção. Pode deixar espaço vazio (transparente ou preto dependendo do formato).
fill	Esticar para preencher ambas as dimensoes exatamente. 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 além das dimensoes da origem. Se você solicitar w=2000 para uma origem de 1200px de largura, a saida terá 1200px de largura. Isso se aplica a todos os modos fit.

Resposta

Status	Quando	Corpo
200	Uma transformação foi produzida nesta requisição.	Bytes binários da imagem. Content-Type corresponde ao formato solicitado.
302	Nenhum parâmetro de transformação fornecido, ou um resultado previamente transformado já está 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 ausente.	{ "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 de cache são servidas com Cache-Control: public, max-age=31536000, immutable. Veja Cache abaixo.

Exemplos de requisições

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 com 60% de qualidade:

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

Miniatura quadrada com bordas 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 legados):

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"

Uso em HTML

Referencie imagens otimizadas diretamente em tags 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 → fallback 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");
}

Uso com Next.js

Como um 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. Como o conteúdo IPFS é endereçado por conteúdo, o mesmo CID com os mesmos parâmetros sempre produz a mesma saida, então navegadores e CDNs podem armazenar as respostas em cache indefinidamente.

Transformações em cache são armazenadas no S3 indexadas pelo conjunto completo de parâmetros (cid, w, h, format, quality, fit). Requisições subsequentes com os mesmos parâmetros retornam um redirecionamento 302 para o cache servido pelo CloudFront (https://ipfs.ninja/image-cache/...) em vez de reexecutar a transformação. Combinações de parâmetros diferentes produzem entradas de cache diferentes.

Disponibilidade

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