Guida rapida

Carica il tuo primo file su IPFS in meno di due minuti.

1. Ottieni la tua API key

Registrati su ipfs.ninja con il tuo account Google. Una API key predefinita viene creata automaticamente. Vai alla tua pagina Profilo per visualizzare e gestire le tue API key.

WARNING

Nota: Le API key non scadono. Puoi creare più chiavi e revocarle singolarmente dalla pagina Profilo.

2. Carica un file

Invia una richiesta POST a /upload/new con il tuo contenuto. Ecco un esempio di caricamento di un oggetto 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 come impostazione predefinita

I nuovi upload producono CID moderni in CIDv1 (bafk… per contenuti di piccole dimensioni a blocco singolo, bafy… per file e directory più grandi) secondo IPIP-0499. I CID legacy Qm… provenienti da upload precedenti continuano a risolversi ovunque — entrambi i formati funzionano come input per ogni endpoint.

L'API restituisce il CID, la dimensione del file e gli URI di accesso:

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

3. Recupera il tuo file

Accedi al tuo file in due modi:

Tramite il gateway IPFS (nessuna autenticazione necessaria)

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

TIP

Il gateway apex https://ipfs.ninja/ipfs/<CID> serve i CID caricati o pinnati da qualsiasi utente di IPFS Ninja. I CID sconosciuti alla piattaforma restituiscono HTTP 410 Gone — per quelli, usa un gateway pubblico (ipfs.io, dweb.link) oppure fai prima POST /pin del CID sul tuo account.

Tramite l'API (restituisce i metadati del file)

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

Risposta:

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

Alternativa: usa l'AWS SDK (compatibile con S3)

Usi già S3? Punta il tuo AWS SDK esistente su https://s3.ipfs.ninja e usa la tua API key come credenziali:

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

Consulta Compatibilità S3 per la documentazione completa con esempi in Python, Go e per la migrazione.

Preferisci cliccare? Usa la Dashboard

Se preferisci non scrivere codice, ipfs.ninja/upload accetta il drag-and-drop per:

• Qualsiasi file — trascinalo sull'area di upload, viene pinnato e ottieni il CID
• Una cartella — viene impacchettata in una directory UnixFS nel tuo browser, caricata come un unico import, e si risolve su /ipfs/{cid}/{subpath} per ogni file figlio
• Un archivio .car — rilevato automaticamente, il CID radice viene preservato esattamente (vedi Import CAR)

Una volta caricati, i file compaiono nella pagina Files, dove puoi rinominarli, spostarli tra cartelle, ottenere un CID di directory IPFS per un'intera cartella (snapshot) e configurare il CORS S3 per bucket per l'accesso tramite SDK dal browser.

Passi successivi

• Riferimento API — Documentazione completa per tutti gli endpoint, parametri e codici di errore.
• Compatibilità S3 — Usa l'AWS SDK per interagire con IPFS Ninja.
• Gateway dedicati — Ottieni un gateway privato che serve solo i tuoi file.