FAQ

Domande frequenti su IPFS Ninja.

Generale

Cos'è IPFS Ninja?

IPFS Ninja è un servizio gestito di pinning IPFS. Carichi qualsiasi file tramite una semplice API REST, oppure pinni CID esistenti dalla rete IPFS. Ogni file riceve un identificatore di contenuto permanente (CID) ed è accessibile tramite il nostro gateway su ipfs.ninja/ipfs/<CID>.

ipfs.ninja/ipfs/<CID> serve qualsiasi CID della rete IPFS?

No. Il gateway apex serve solo i CID che sono stati caricati o pinnati da un utente di IPFS Ninja. Le richieste per CID sconosciuti restituiscono HTTP 410 Gone con un puntatore a gateway IPFS pubblici (ipfs.io, dweb.link). Per servire un CID di terze parti tramite il nostro gateway, fai prima POST /pin sul tuo account — una volta pinnato, il CID diventa accessibile sia all'URL apex sia al tuo gateway dedicato.

Qual è la differenza tra il gateway apex e il gateway dedicato?

Aspetto	Apex ipfs.ninja/ipfs/<CID>	Dedicato <slug>.gw.ipfs.ninja/ipfs/<CID>
Ambito	Condiviso tra tutti gli utenti	Solo i tuoi CID
Autenticazione	Nessuna	Token opzionale / allowlist IP / allowlist origini
SLA	Best-effort	SLA completo
Consigliato per	Link occasionali	Incorporamento in produzione (NFT, video, siti)
Limiti di frequenza	Condiviso per IP + per CID	Per piano, configurabile

Entrambi servono contenuti identici. Per il traffico di produzione, usa il gateway dedicato.

Quali tipi di file sono supportati?

Tutti i tipi di file sono supportati. Oggetti e array JSON possono essere inviati direttamente. Tutti gli altri file (immagini, PDF, HTML, video, audio, binari) vengono inviati come contenuto codificato in base64.

C'è un limite di dimensione del file?

I singoli upload sono limitati dall'allocazione di spazio del tuo piano. Non c'è un limite di dimensione per singolo file oltre lo spazio disponibile.

Posso pinnare contenuti già esistenti su IPFS?

Sì. Usa POST /pin con qualsiasi CID valido. Il nostro cluster recupererà il contenuto dalla rete IPFS e lo pinnerà al tuo account. Consulta la documentazione dell'API Pinning per i dettagli.

Quanto tempo richiede il pinning?

Dipende dalla dimensione del file e da quanti nodi IPFS hanno il contenuto. File piccoli e ben distribuiti vengono pinnati in pochi secondi. Contenuti grandi o raramente pinnati possono richiedere alcuni minuti. L'endpoint di pin risponde immediatamente con stato pinning — interroga GET /pin/:cid per verificare l'avanzamento.

Cosa succede se un CID non viene trovato?

Lo stato diventa failed. Ciò significa che il CID è invalido oppure il contenuto non è più disponibile su nessun nodo IPFS raggiungibile.

I dati caricati su IPFS sono pubblici?

Sì. Tutto il contenuto pinnato su IPFS è pubblicamente accessibile tramite il suo CID attraverso qualsiasi gateway IPFS. Se hai bisogno di accesso privato, usa un gateway dedicato con modalità token-required — questo limita l'accesso attraverso il tuo gateway, anche se il contenuto rimane disponibile sulla rete IPFS più ampia.

Perché i miei nuovi CID sono cambiati da Qm... a bafy...?

I nuovi upload e pin restituiscono ora CIDv1 moderni (bafk… per i contenuti piccoli a blocco singolo, bafy… per file e directory più grandi) secondo il profilo IPIP-0499 unixfs-v1-2025: codifica CIDv1 in base32, chunk da 1 MiB, raw leaves. Questo corrisponde a ciò che gli strumenti moderni (Helia, Kubo più recente, ipfs-car) producono per lo stesso contenuto, quindi un file caricato tramite noi ottiene lo stesso CID che qualsiasi client moderno calcolerebbe per gli stessi byte.

I CID Qm… legacy dei caricamenti precedenti restano completamente risolvibili — il gateway, POST /pin, GET /file, IPNS e ogni altro endpoint accettano entrambi i formati a tempo indeterminato. Nulla di ciò che hai già smette di funzionare.

Come pinno contenuti che si trovano su un nodo privato / non-DHT?

POST /pin accetta il parametro opzionale multiaddresses[] (fino a 5). Se fornito, il nostro cluster esegue ipfs swarm connect <multiaddr> per ogni indicazione prima che il pin venga eseguito, così i contenuti su peer che non si annunciano tramite la DHT pubblica (nodi privati, ambienti di staging, macchine VPN-local) diventano raggiungibili. Consulta la guida Pinnare da un nodo IPFS privato.

I miei file rimarranno su IPFS se cancello il mio account?

Rimuoviamo il pin dei tuoi file dai nostri nodi quando cancelli. Se altri nodi IPFS hanno memorizzato nella cache il tuo contenuto, potrebbe rimanere accessibile. Tuttavia, senza pinning attivo, i file verranno eventualmente rimossi dalla garbage collection attraverso la rete.

Autenticazione e API

Come autentico le richieste API?

Passa la tua API key tramite l'header X-Api-Key. Genera le chiavi dalla pagina API Keys nella tua dashboard.

Ci sono limiti di frequenza sulle API?

No. IPFS Ninja non impone limiti di frequenza sulle richieste API. Puoi fare tutte le richieste necessarie con qualsiasi piano.

Le API key scadono?

No. Le API key sono valide finché non le elimini. Puoi creare più chiavi e revocarle singolarmente.

Qual è la differenza tra API key e token gateway?

Le API key (bws_) hanno accesso completo — caricamento, eliminazione, elenco file. I token gateway (gwt_) sono in sola lettura e possono accedere ai file solo tramite il tuo gateway dedicato. I token gateway sono sicuri da incorporare nelle app frontend.

Gateway dedicati

Cos'è un gateway dedicato?

Un gateway IPFS privato sul tuo sottodominio (es. abc123.gw.ipfs.ninja) che serve solo i file pinnati al tuo account. A differenza del gateway pubblico, non risolverà CID di altri utenti.

Quali piani includono un gateway dedicato?

I gateway dedicati sono disponibili su tutti i piani a pagamento (Bodhi $5/mese, Karma $19/mese, Nirvana $59/mese). La quota mensile di larghezza di banda di ciascun piano copre il traffico sia del gateway apex sia del gateway dedicato. Vedi "Ci sono costi di larghezza di banda?" qui sotto per le quote per piano.

Posso limitare chi accede al mio gateway?

Sì. Puoi abilitare la modalità token-required (richiede un token gwt_ per ogni richiesta) e/o impostare una whitelist IP (fino a 100 indirizzi).

Posso limitare il mio gateway per origine/dominio?

Sì. Configura allowedOrigins nelle impostazioni del gateway con un elenco di origini HTTPS. Solo le richieste del browser provenienti da quelle origini saranno consentite. Le richieste non-browser (senza header Origin) passano senza restrizioni. Un elenco vuoto consente tutte le origini.

Cosa sono i token di caricamento firmati?

I token di caricamento firmati sono credenziali a tempo limitato per caricamenti lato client. Li generi sul tuo server usando POST /upload/signed-url e li passi ai browser o app mobile. Il client si autentica con Authorization: Signed <token> invece di esporre la tua API key. Ogni token traccia l'utilizzo e scade automaticamente. Consulta la documentazione sui Token firmati per i dettagli.

Posso ottimizzare le immagini servite da IPFS?

Sì. Usa GET /image/:cid con parametri di query come w, h, format e quality per ridimensionare, convertire e comprimere le immagini al volo. Le risposte vengono memorizzate nella cache in base al CID a contenuto indirizzato. Funziona su tutti i piani. Vedi Ottimizzazione immagini.

Posso allegare metadati ai file?

Sì. Includi un oggetto metadata con fino a 10 coppie chiave-valore durante il caricamento tramite POST /upload/new o il pinning tramite POST /pin. I metadati vengono restituiti nell'elenco dei file e nell'endpoint di dettaglio del file. Consulta la documentazione su File e Pinning.

Fatturazione e piani

C'è un piano gratuito?

Sì. Il piano Dharma è gratuito per sempre — 1 GB di spazio di archiviazione, richieste API illimitate, nessuna carta di credito richiesta.

Ci sono costi di larghezza di banda?

Nessun costo di larghezza di banda a consumo su nessun piano. Ogni piano include una quota mensile di larghezza di banda del gateway che è un limite rigido — i tuoi contenuti smettono di essere serviti sul gateway apex e sul gateway dedicato una volta raggiunta la quota, e riprendono il 1° del mese successivo o dopo un upgrade:

Piano	Larghezza di banda mensile
Dharma	2 GB
Bodhi	20 GB
Karma	100 GB
Nirvana	500 GB

Riceverai email di avviso all'80% e al 100% della tua quota.

Lo spazio di archiviazione si azzera?

Lo spazio di archiviazione non si azzera. Il tuo piano include un'allocazione totale di archiviazione (Dharma 1 GB / Bodhi 10 GB / Karma 100 GB / Nirvana 1 TB). Per liberare spazio, elimina i file che non ti servono più. L'upgrade del piano aumenta la tua allocazione totale.

Posso cancellare in qualsiasi momento?

Sì. Cancella il tuo abbonamento tramite il portale di fatturazione — senza vincoli. Il tuo account torna al livello gratuito e i file pinnati esistenti rimangono accessibili.

Cosa succede ai miei file se faccio il downgrade?

I tuoi file rimangono pinnati su IPFS, ma non puoi caricare altro se il tuo utilizzo attuale supera il limite di archiviazione del nuovo piano. Elimina file per tornare sotto il limite.

Sicurezza

I miei dati sono crittografati?

Tutti i dati sono crittografati in transito tramite TLS/HTTPS. L'autenticazione usa token JWT (Cognito) e API key archiviate in modo sicuro. Il contenuto dei file su IPFS non è crittografato a riposo — IPFS è una rete pubblica per progettazione.

È sicuro usare le API key nel mio codice lato server?

Sì. Le API key sono progettate per l'uso lato server. Non esporle mai nel codice lato client. Per l'accesso ai file lato client, usa i token gateway (gwt_) che sono in sola lettura.

Supporto

Come posso ottenere aiuto?

Invia un'email a info@ipfs.ninja o consulta la documentazione del Riferimento API.

C'è un SLA?

Ci impegniamo per un'alta disponibilità ma al momento non offriamo un SLA formale. Il servizio è fornito "così com'è".