Início Rápido

Envie seu primeiro arquivo para o IPFS em menos de dois minutos.

1. Obtenha sua chave de API

Cadastre-se em ipfs.ninja com sua conta do Google. Uma chave de API padrão é criada automaticamente. Acesse sua página de Perfil para visualizar e gerenciar suas chaves de API.

WARNING

Nota: as chaves de API não expiram. Você pode criar múltiplas chaves e revogá-las individualmente na sua página de Perfil.

2. Envie um arquivo

Envie uma requisição POST para /upload/new com seu conteúdo. Aqui está um exemplo de envio de um objeto JSON:

curl

curl -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "name": "My NFT",
      "description": "A permanent file on IPFS",
      "image": "ipfs://bafybeiExampleCID..."
    },
    "description": "NFT metadata"
  }'

JavaScript

const response = await fetch("https://api.ipfs.ninja/upload/new", {
  method: "POST",
  headers: {
    "X-Api-Key": "bws_your_api_key_here",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    content: {
      name: "My NFT",
      description: "A permanent file on IPFS",
      image: "ipfs://bafybeiExampleCID..."
    },
    description: "NFT metadata"
  })
});

const data = await response.json();
console.log(data.cid);       // "bafybeigdyrzt5..."
console.log(data.uris.url);  // "https://ipfs.ninja/ipfs/bafybeigdyrzt5..."

CIDv1 por padrão

Novos uploads produzem CIDv1 moderno (bafk… para conteúdo pequeno de bloco único, bafy… para arquivos e diretórios maiores) conforme o IPIP-0499. CIDs Qm… legados de uploads anteriores continuam resolvendo em todo lugar — ambos os formatos funcionam como entrada em todos os endpoints.

A API retorna o CID, o tamanho do arquivo e as URIs de acesso:

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "sizeMB": 0.001,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

3. Recupere seu arquivo

Acesse seu arquivo de duas formas:

Pelo gateway IPFS (sem necessidade de autenticação)

curl https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

TIP

O gateway apex https://ipfs.ninja/ipfs/<CID> serve CIDs enviados ou fixados por qualquer usuário do IPFS Ninja. CIDs desconhecidos pela plataforma retornam HTTP 410 Gone — para esses casos, use um gateway público (ipfs.io, dweb.link) ou faça primeiro POST /pin do CID para sua conta.

Pela API (retorna metadados do arquivo)

curl https://api.ipfs.ninja/file/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi \
  -H "X-Api-Key: bws_your_api_key_here"

Resposta:

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "fileName": "NFT metadata",
  "fileType": "json",
  "sizeMB": 0.001,
  "createdAt": 1711036800000,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

Alternativa: use o AWS SDK (compatível com S3)

Já usa S3? Aponte seu AWS SDK existente para https://s3.ipfs.ninja e use sua chave de API como credenciais:

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";

const s3 = new S3Client({
  endpoint: "https://s3.ipfs.ninja",
  credentials: { accessKeyId: "bws_prefix", secretAccessKey: "bws_fullkey" },
  region: "us-east-1",
  forcePathStyle: true
});

await s3.send(new PutObjectCommand({
  Bucket: "my-project",
  Key: "my-file.json",
  Body: JSON.stringify({ hello: "IPFS" })
}));

Veja Compatibilidade S3 para a documentação completa com exemplos em Python, Go e guias de migração.

Prefere clicar? Use o painel

Se preferir não escrever código, ipfs.ninja/upload aceita arrastar e soltar para:

• Qualquer arquivo — solte na zona de upload, ele é fixado e você recebe o CID
• Uma pasta — empacotada em um diretório UnixFS no seu navegador, enviada como uma única importação, resolve em /ipfs/{cid}/{subpath} para cada arquivo filho
• Um arquivo .car — detectado automaticamente, com o CID raiz preservado exatamente (veja Importação de CAR)

Depois de enviados, os arquivos aparecem na página Arquivos, onde você pode renomear, mover entre pastas, obter um CID de diretório IPFS para uma pasta inteira (snapshot), e configurar S3 CORS por bucket para acesso via SDK no navegador.

Próximos passos

• Referência da API — Documentação completa de todos os endpoints, parâmetros e códigos de erro.
• Compatibilidade S3 — Use o AWS SDK para interagir com o IPFS Ninja.
• Gateways Dedicados — Obtenha um gateway privado que serve apenas seus arquivos.