Preguntes Freqüents

Preguntes freqüents sobre IPFS Ninja.

General

Què és IPFS Ninja?

IPFS Ninja és un servei gestionat de pinning IPFS. Pugeu qualsevol fitxer mitjançant una REST API senzilla, o fixeu CID existents de la xarxa IPFS. Cada fitxer obté un identificador de contingut permanent (CID) i és accessible a través del nostre gateway a ipfs.ninja/ipfs/<CID>.

Serveix ipfs.ninja/ipfs/<CID> qualsevol CID de la xarxa IPFS?

No. La passarel·la apex només serveix CID que han estat pujats o fixats per un usuari d'IPFS Ninja. Les sol·licituds per a CID desconeguts retornen HTTP 410 Gone amb un punter a gateways IPFS públics (ipfs.io, dweb.link). Per servir un CID de tercers a través del nostre gateway, feu primer POST /pin al vostre compte — un cop fixat, el CID serà accessible tant a l'URL apex com a la del vostre gateway dedicat.

Quina és la diferència entre la passarel·la apex i el gateway dedicat?

Aspecte	Apex ipfs.ninja/ipfs/<CID>	Dedicat <slug>.gw.ipfs.ninja/ipfs/<CID>
Abast	Compartit entre tots els usuaris	Només els vostres CID
Autenticació	Cap	Token opcional / llista d'IP / llista d'orígens
SLA	Millor esforç	SLA complet
Recomanat per a	Enllaços ocasionals	Incrustació en producció (NFT, vídeo, llocs web)
Límits de taxa	Compartit per IP + per CID	Per pla, configurable

Ambdós serveixen contingut idèntic. Per a trànsit de producció, feu servir el gateway dedicat.

Quins tipus de fitxers estan suportats?

Tots els tipus de fitxers estan suportats. Els objectes i matrius JSON es poden enviar directament. Tots els altres fitxers (imatges, PDF, HTML, vídeo, àudio, binaris) s'envien com a contingut codificat en base64.

Hi ha un límit de mida de fitxer?

Les pujades individuals estan limitades per l'assignació d'emmagatzematge del vostre pla. No hi ha límit de mida per fitxer més enllà del vostre emmagatzematge disponible.

Puc fixar contingut que ja existeix a IPFS?

Sí. Utilitzeu POST /pin amb qualsevol CID vàlid. El nostre clúster obtindrà el contingut de la xarxa IPFS i el fixarà al vostre compte. Consulteu la documentació de l'API de Pinning per a més detalls.

Quant de temps triga la fixació?

Depèn de la mida del fitxer i de quants nodes IPFS tenen el contingut. Fitxers petits i ben distribuïts es fixen en segons. Contingut gran o rarament fixat pot trigar uns minuts. L'endpoint de pin retorna immediatament amb estat pinning — feu polling a GET /pin/:cid per comprovar el progrés.

Què passa si no es pot trobar un CID?

L'estat canvia a failed. Això significa que el CID és invàlid o que el contingut ja no està disponible a cap node IPFS accessible.

Les dades pujades a IPFS són públiques?

Sí. Tot el contingut fixat a IPFS és públicament accessible mitjançant el seu CID a través de qualsevol IPFS gateway. Si necessiteu accés privat, utilitzeu un gateway dedicat amb mode de token requerit — això restringeix l'accés a través del vostre gateway, encara que el contingut segueix disponible a la xarxa IPFS més àmplia.

Per què els meus nous CID han canviat de Qm... a bafy...?

Les pujades i fixacions noves retornen CIDv1 modern (bafk… per a contingut petit d'un sol bloc, bafy… per a fitxers i directoris més grans) seguint el perfil IPIP-0499 unixfs-v1-2025: codificació CIDv1 en base32, blocs d'1 MiB, fulles en cru (raw leaves). Això coincideix amb el que produeixen les eines modernes (Helia, la darrera versió de Kubo, ipfs-car) per al mateix contingut, així que un fitxer pujat a través nostre obté el mateix CID que qualsevol eina moderna calcularia per als mateixos bytes.

Els CID Qm… heretats de pujades anteriors continuen sent completament resolubles — el gateway, POST /pin, GET /file, IPNS, i tots els altres endpoints accepten ambdós formats indefinidament. Res del que ja teniu deixa de funcionar.

Com fixo contingut que viu en un node privat / que no és DHT?

POST /pin accepta opcionalment multiaddresses[] (fins a 5). Si es proporcionen, el nostre clúster executa ipfs swarm connect <multiaddr> per a cada pista abans que s'executi la fixació, de manera que el contingut en peers que no s'anuncien via la DHT pública (nodes privats, entorns de staging, màquines locals de VPN) sigui accessible. Consulteu la guia Fixar des d'un node IPFS privat.

Els meus fitxers es mantindran a IPFS si cancel·lo el meu compte?

Desfixem els vostres fitxers dels nostres nodes quan cancel·leu. Si altres nodes IPFS han emmagatzemat en memòria cau el vostre contingut, pot seguir sent accessible. No obstant això, sense fixació activa, els fitxers acabaran sent eliminats per la recollida d'escombraries a tota la xarxa.

Autenticació & API

Com autentifico les sol·licituds API?

Passeu la vostra API key mitjançant la capçalera X-Api-Key. Genereu claus des de la pàgina API Keys al vostre tauler de control.

Hi ha límits de taxa d'API?

No. IPFS Ninja no imposa límits de taxa a les sol·licituds API. Podeu fer tantes sol·licituds com necessiteu en qualsevol pla.

Les API key caduquen?

No. Les API key són vàlides fins que les elimineu. Podeu crear múltiples claus i revocar-les individualment.

Quina és la diferència entre API key i gateway token?

Les API key (bws_) tenen accés complet — pujar, eliminar, llistar fitxers. Els gateway token (gwt_) són de només lectura i només poden accedir a fitxers a través del vostre gateway dedicat. Els gateway token són segurs per incrustar en aplicacions frontend.

Gateways Dedicats

Què és un gateway dedicat?

Un gateway IPFS privat al vostre propi subdomini (p. ex. abc123.gw.ipfs.ninja) que només serveix fitxers fixats al vostre compte. A diferència del gateway públic, no resoldrà CID d'altres usuaris.

Quins plans inclouen un gateway dedicat?

Els gateways dedicats estan disponibles a tots els plans de pagament (Bodhi $5/mes, Karma $19/mes, Nirvana $59/mes). La quota mensual d'amplada de banda de cada pla cobreix el trànsit tant de la passarel·la apex com del gateway dedicat. Consulteu "Hi ha tarifes d'amplada de banda?" més avall per a les quotes per pla.

Puc restringir qui accedeix al meu gateway?

Sí. Podeu activar el mode de token requerit (requereix un token gwt_ a cada sol·licitud) i/o establir una llista blanca d'IP (fins a 100 adreces).

Puc restringir el meu gateway per origin/domini?

Sí. Configureu allowedOrigins a la vostra configuració del gateway amb una llista d'origins HTTPS. Només les sol·licituds de navegador des d'aquells orígens seran permeses. Les sol·licituds que no són de navegador (sense capçalera Origin) passen sense restricció. Una llista buida permet tots els orígens.

Què són els tokens de pujada signats?

Els tokens de pujada signats són credencials amb temps limitat per a pujades del costat del client. Els genereu al vostre servidor utilitzant POST /upload/signed-url i els passeu a navegadors o aplicacions mòbils. El client s'autentica amb Authorization: Signed <token> en lloc d'exposar la vostra API key. Cada token fa seguiment de l'ús i caduca automàticament. Consulteu la documentació de Signed Tokens per a més detalls.

Puc optimitzar imatges servides des d'IPFS?

Sí. Utilitzeu GET /image/:cid amb paràmetres de consulta com w, h, format i quality per redimensionar, convertir i comprimir imatges sobre la marxa. Les respostes s'emmagatzemen en memòria cau basant-se en el CID de contingut. Això funciona en tots els plans. Consulteu Optimització d'Imatge.

Puc adjuntar metadata als fitxers?

Sí. Incloeu un objecte metadata amb fins a 10 parells clau-valor quan pugeu mitjançant POST /upload/new o fixeu mitjançant POST /pin. Les metadata es retornen als llistats de fitxers i a l'endpoint de detall del fitxer. Consulteu la documentació de Fitxers i Fixació.

Facturació & Plans

Hi ha un pla gratuït?

Sí. El pla Dharma és gratuït per sempre — 1 GB d'emmagatzematge, sol·licituds API il·limitades, no cal targeta de crèdit.

Hi ha tarifes d'amplada de banda?

Sense tarifes d'amplada de banda mesurada en cap pla. Cada pla inclou una quota mensual d'amplada de banda del gateway que és un límit estricte — el vostre contingut deixa de servir-se a la passarel·la apex i al gateway dedicat un cop s'assoleix la quota, i es reprèn l'1 del mes següent o després d'una actualització:

Pla	Amplada de banda mensual
Dharma	2 GB
Bodhi	20 GB
Karma	100 GB
Nirvana	500 GB

Rebreu correus electrònics d'avís al 80% i al 100% de la vostra quota.

L'emmagatzematge es reinicia?

L'emmagatzematge no es reinicia. El vostre pla inclou una assignació total d'emmagatzematge (Dharma 1 GB / Bodhi 10 GB / Karma 100 GB / Nirvana 1 TB). Per alliberar espai, elimineu fitxers que ja no necessiteu. Actualitzar el vostre pla augmenta la vostra assignació total.

Puc cancel·lar en qualsevol moment?

Sí. Cancel·leu la vostra subscripció a través del portal de facturació — sense vinculació. El vostre compte torna al nivell gratuït, i els fitxers fixats existents segueixen sent accessibles.

Què passa amb els meus fitxers si faig un downgrade?

Els vostres fitxers es mantenen fixats a IPFS, però no podeu pujar més si el vostre ús actual supera el límit d'emmagatzematge del nou pla. Elimineu fitxers per tornar per sota del límit.

Seguretat

Les meves dades estan xifrades?

Totes les dades es xifren en trànsit mitjançant TLS/HTTPS. L'autenticació utilitza JWT tokens (Cognito) i API keys emmagatzemades de forma segura. El contingut dels fitxers a IPFS no es xifra en repòs — IPFS és una xarxa pública per disseny.

És segur utilitzar API keys al meu codi del servidor?

Sí. Les API keys estan dissenyades per a ús del costat del servidor. No les exposeu mai en codi del costat del client. Per a l'accés a fitxers del costat del client, utilitzeu gateway tokens (gwt_) que són de només lectura.

Suport

Com puc obtenir ajuda?

Envieu un correu electrònic a info@ipfs.ninja o consulteu la documentació de Referència de l'API.

Hi ha SLA?

Ens esforcem per una alta disponibilitat però no oferim un SLA formal en aquest moment. El servei es proporciona "tal qual".