FAQ

Întrebări frecvente despre IPFS Ninja.

General

Ce este IPFS Ninja?

IPFS Ninja este un serviciu gestionat de fixare IPFS. Încărcați orice fișier printr-un API REST simplu, sau fixați CID-uri existente din rețeaua IPFS. Fiecare fișier primește un identificator de conținut permanent (CID) și este accesibil prin gateway-ul nostru la ipfs.ninja/ipfs/<CID>.

ipfs.ninja/ipfs/<CID> servește orice CID din rețeaua IPFS?

Nu. Gateway-ul apex servește doar CID-uri care au fost încărcate sau fixate de un utilizator IPFS Ninja. Cererile pentru CID-uri necunoscute returnează HTTP 410 Gone cu un indicator către gateway-uri IPFS publice (ipfs.io, dweb.link). Pentru a servi un CID terț prin gateway-ul nostru, executați mai întâi POST /pin pe contul dvs. — odată fixat, CID-ul devine accesibil atât la URL-ul apex, cât și la cel al gateway-ului dvs. dedicat.

Care este diferența dintre gateway-ul apex și gateway-ul dedicat?

Aspect	Apex ipfs.ninja/ipfs/<CID>	Dedicat <slug>.gw.ipfs.ninja/ipfs/<CID>
Domeniu	Partajat între toți utilizatorii	Doar CID-urile dvs.
Autentificare	Niciuna	Token opțional / listă IP / listă origini
SLA	Best-effort	SLA complet
Recomandat pentru	Linkuri ocazionale	Încorporare în producție (NFT, video, site-uri)
Limite de viteză	Partajate per IP + per CID	Per plan, configurabile

Ambele servesc conținut identic. Pentru trafic de producție, folosiți gateway-ul dedicat.

Ce tipuri de fișiere sunt acceptate?

Toate tipurile de fișiere sunt acceptate. Obiectele și array-urile JSON pot fi trimise direct. Toate celelalte fișiere (imagini, PDF-uri, HTML, video, audio, binare) sunt trimise ca conținut codificat base64.

Există o limită de dimensiune a fișierului?

Încărcările individuale sunt limitate de capacitatea de stocare a planului dvs. Nu există o limită de dimensiune per fișier dincolo de spațiul de stocare disponibil.

Pot fixa conținut care există deja pe IPFS?

Da. Folosiți POST /pin cu orice CID valid. Clusterul nostru va prelua conținutul din rețeaua IPFS și îl va fixa în contul dvs. Consultați documentația API de fixare pentru detalii.

Cât durează fixarea?

Depinde de dimensiunea fișierului și de câte noduri IPFS au conținutul. Fișierele mici, bine distribuite, se fixează în câteva secunde. Conținutul mare sau rar fixat poate dura câteva minute. Endpoint-ul de fixare returnează imediat cu starea pinning — interogați GET /pin/:cid pentru a verifica progresul.

Ce se întâmplă dacă un CID nu poate fi găsit?

Starea se schimbă în failed. Aceasta înseamnă că CID-ul este fie invalid, fie conținutul nu mai este disponibil pe niciun nod IPFS accesibil.

Sunt datele încărcate pe IPFS publice?

Da. Tot conținutul fixat pe IPFS este accesibil public prin CID-ul său prin orice gateway IPFS. Dacă aveți nevoie de acces privat, folosiți un gateway dedicat cu modul token obligatoriu — aceasta restricționează accesul prin gateway-ul dvs., deși conținutul rămâne disponibil pe rețeaua IPFS mai largă.

De ce s-au schimbat noile mele CID-uri din Qm... în bafy...?

Încărcările și fixările noi returnează CIDv1 modern (bafk… pentru conținut mic, cu un singur bloc, bafy… pentru fișiere și directoare mai mari) conform profilului IPIP-0499 unixfs-v1-2025: codificare base32 CIDv1, bucăți de 1 MiB, frunze brute. Aceasta corespunde cu ceea ce produc uneltele moderne (Helia, ultimul Kubo, ipfs-car) pentru același conținut, deci un fișier încărcat prin serviciul nostru primește același CID pe care l-ar calcula orice client modern pentru aceiași octeți.

CID-urile vechi Qm… din încărcările anterioare rămân complet rezolvabile — gateway-ul, POST /pin, GET /file, IPNS și fiecare alt endpoint acceptă ambele formate pe termen nelimitat. Nimic din ce aveți deja nu încetează să funcționeze.

Cum fixez conținut care se află pe un nod privat / non-DHT?

POST /pin acceptă opțional multiaddresses[] (până la 5). Dacă sunt furnizate, clusterul nostru execută ipfs swarm connect <multiaddr> pentru fiecare indiciu înainte de a rula fixarea, astfel încât conținutul de pe peer-i care nu se anunță prin DHT-ul public (noduri private, medii de staging, mașini locale VPN) devine accesibil. Consultați ghidul Fixare de pe un nod IPFS privat.

Fișierele mele vor rămâne pe IPFS dacă îmi anulez contul?

Detașăm fișierele dvs. de nodurile noastre atunci când anulați. Dacă alte noduri IPFS au conținutul dvs. în cache, acesta poate rămâne accesibil. Cu toate acestea, fără fixare activă, fișierele vor fi în cele din urmă eliminate prin colectarea gunoiului în întreaga rețea.

Autentificare și API

Cum autentific cererile API?

Transmiteți cheia dvs. API prin antetul X-Api-Key. Generați chei din pagina Chei API din dashboard-ul dvs.

Există limite de rată pentru API?

Nu. IPFS Ninja nu impune limite de rată pentru cererile API. Puteți face câte cereri aveți nevoie cu orice plan.

Cheile API expiră?

Nu. Cheile API sunt valide până când le ștergeți. Puteți crea mai multe chei și le puteți revoca individual.

Care este diferența dintre cheile API și tokenurile gateway?

Cheile API (bws_) au acces complet — încărcare, ștergere, listare fișiere. Tokenurile gateway (gwt_) sunt doar pentru citire și pot accesa fișiere doar prin gateway-ul dvs. dedicat. Tokenurile gateway sunt sigure pentru a fi încorporate în aplicații frontend.

Gateway-uri dedicate

Ce este un gateway dedicat?

Un gateway IPFS privat pe propriul subdomeniu (de ex. abc123.gw.ipfs.ninja) care servește doar fișierele fixate în contul dvs. Spre deosebire de gateway-ul public, nu va rezolva CID-uri de la alți utilizatori.

Ce planuri includ un gateway dedicat?

Gateway-urile dedicate sunt disponibile în toate planurile plătite (Bodhi 5 $/lună, Karma 19 $/lună, Nirvana 59 $/lună). Cota lunară de lățime de bandă a fiecărui plan acoperă traficul atât de la gateway-ul apex, cât și de la cel dedicat. Consultați „Există taxe de lățime de bandă?" mai jos pentru cotele per plan.

Pot restricționa cine accesează gateway-ul meu?

Da. Puteți activa modul token obligatoriu (necesită un token gwt_ la fiecare cerere) și/sau puteți seta o listă albă de IP-uri (până la 100 de adrese).

Pot restricționa gateway-ul meu după origine/domeniu?

Da. Configurați allowedOrigins în setările gateway cu o listă de origini HTTPS. Doar cererile din browser de la acele origini vor fi permise. Cererile non-browser (fără antet Origin) trec fără restricție. O listă goală permite toate originile.

Ce sunt tokenurile de încărcare semnate?

Tokenurile de încărcare semnate sunt credențiale cu durată limitată pentru încărcări pe partea de client. Le generați pe serverul dvs. folosind POST /upload/signed-url și le transmiteți browserelor sau aplicațiilor mobile. Clientul se autentifică cu Authorization: Signed <token> în loc să expună cheia dvs. API. Fiecare token urmărește utilizarea și expiră automat. Consultați documentația Tokenuri semnate pentru detalii.

Pot optimiza imaginile servite din IPFS?

Da. Folosiți GET /image/:cid cu parametri de interogare precum w, h, format și quality pentru redimensionare, conversie și comprimare a imaginilor din mers. Răspunsurile sunt stocate în cache pe baza CID-ului adresat prin conținut. Funcționează pe toate planurile. Consultați Optimizarea imaginilor.

Pot atașa metadate fișierelor?

Da. Includeți un obiect metadata cu până la 10 perechi cheie-valoare la încărcare prin POST /upload/new sau la fixare prin POST /pin. Metadatele sunt returnate în listele de fișiere și la endpoint-ul de detalii al fișierului. Consultați documentația Fișiere și Fixare.

Facturare și planuri

Există un plan gratuit?

Da. Planul Dharma este gratuit pentru totdeauna — 1 GB de stocare, cereri API nelimitate, fără card de credit necesar.

Există taxe de lățime de bandă?

Nicio taxă de lățime de bandă măsurată pe niciun plan. Fiecare plan include o cotă lunară de lățime de bandă gateway care este o limită strictă — conținutul dvs. încetează să mai fie servit pe gateway-ul apex și pe cel dedicat odată atinsă cota, și reia pe data de 1 a lunii următoare sau după un upgrade:

Plan	Lățime de bandă lunară
Dharma	2 GB
Bodhi	20 GB
Karma	100 GB
Nirvana	500 GB

Veți primi emailuri de avertizare la 80% și 100% din cota dvs.

Se resetează stocarea?

Stocarea nu se resetează. Planul dvs. include o capacitate totală de stocare (Dharma 1 GB / Bodhi 10 GB / Karma 100 GB / Nirvana 1 TB). Pentru a elibera spațiu, ștergeți fișierele de care nu mai aveți nevoie. Actualizarea planului dvs. crește capacitatea totală.

Pot anula oricând?

Da. Anulați abonamentul prin portalul de facturare — fără angajamente. Contul dvs. revine la nivelul gratuit, iar fișierele fixate existente rămân accesibile.

Ce se întâmplă cu fișierele mele dacă fac downgrade?

Fișierele dvs. rămân fixate pe IPFS, dar nu puteți încărca mai multe dacă utilizarea dvs. curentă depășește limita de stocare a noului plan. Ștergeți fișiere pentru a reveni sub limită.

Securitate

Sunt datele mele criptate?

Toate datele sunt criptate în tranzit prin TLS/HTTPS. Autentificarea folosește tokenuri JWT (Cognito) și chei API stocate securizat. Conținutul fișierelor pe IPFS nu este criptat în repaus — IPFS este o rețea publică prin design.

Este sigur să folosesc chei API în codul meu server-side?

Da. Cheile API sunt concepute pentru utilizare server-side. Nu le expuneți niciodată în codul client-side. Pentru accesul la fișiere pe partea de client, folosiți tokenuri gateway (gwt_) care sunt doar pentru citire.

Suport

Cum pot obține ajutor?

Trimiteți un email la info@ipfs.ninja sau consultați documentația Referința API.

Există un SLA?

Ne străduim pentru disponibilitate ridicată, dar nu oferim un SLA formal în acest moment. Serviciul este furnizat pe bază „ca atare".