FAQ

Často kladené otázky o IPFS Ninja.

Všeobecné

Čo je IPFS Ninja?

IPFS Ninja je spravovaná služba na pripínanie v IPFS. Nahrávate akýkoľvek súbor cez jednoduché REST API, alebo pripínate existujúce CID zo siete IPFS. Každý súbor získa trvalý identifikátor obsahu (CID) a je prístupný cez našu gateway na ipfs.ninja/ipfs/<CID>.

Obsluhuje ipfs.ninja/ipfs/<CID> ľubovoľný CID v sieti IPFS?

Nie. Apex brána obsluhuje iba CID, ktoré boli nahrané alebo pripnuté používateľom IPFS Ninja. Požiadavky na neznáme CID vracajú HTTP 410 Gone s odkazom na verejné IPFS brány (ipfs.io, dweb.link). Pre obsluhu CID tretej strany cez našu bránu vykonajte najprv POST /pin na svoj účet — po pripnutí je CID dostupný tak na apex, ako aj na URL vašej dedikovanej gateway.

Aký je rozdiel medzi apex bránou a dedikovanou bránou?

Aspekt	Apex ipfs.ninja/ipfs/<CID>	Dedikovaná <slug>.gw.ipfs.ninja/ipfs/<CID>
Rozsah	Zdieľaná medzi všetkými používateľmi	Iba vaše CID
Autentifikácia	Žiadna	Voliteľný token / IP allowlist / origin allowlist
SLA	Best-effort	Plné SLA
Odporúčané pre	Príležitostné odkazy	Produkčné vkladanie (NFT, video, weby)
Limity rýchlosti	Zdieľané per-IP + per-CID	Podľa plánu, konfigurovateľné

Obe obsluhujú identický obsah. Pre produkčnú prevádzku použite dedikovanú bránu.

Aké typy súborov sú podporované?

Všetky typy súborov sú podporované. JSON objekty a polia môžu byť odoslané priamo. Všetky ostatné súbory (obrázky, PDF, HTML, video, audio, binárne súbory) sa odosielajú ako obsah kódovaný v base64.

Existuje limit veľkosti súboru?

Jednotlivé nahrávania sú obmedzené úložným limitom vášho plánu. Neexistuje žiadny limit na veľkosť jednotlivého súboru mimo vaše dostupné úložisko.

Môžem pripnúť obsah, ktorý už existuje na IPFS?

Áno. Použite POST /pin s akýmkoľvek platným CID. Náš cluster načíta obsah zo siete IPFS a pripne ho k vášmu účtu. Podrobnosti nájdete v dokumentácii Pinning API.

Ako dlho trvá pripnutie?

Závisí to od veľkosti súboru a počtu IPFS uzlov, ktoré majú obsah. Malé, dobre distribuované súbory sa pripnú za sekundy. Veľký alebo zriedka pripínaný obsah môže trvať niekoľko minút. Endpoint pre pripnutie vráti okamžite stav pinning — dopytujte sa na GET /pin/:cid, aby ste skontrolovali priebeh.

Čo sa stane, keď CID nemožno nájsť?

Stav sa zmení na failed. To znamená, že CID je buď neplatný, alebo obsah už nie je dostupný na žiadnom dosiahnuteľnom IPFS uzle.

Sú dáta nahrané na IPFS verejné?

Áno. Všetok obsah pripnutý na IPFS je verejne prístupný cez jeho CID prostredníctvom akejkoľvek IPFS gateway. Ak potrebujete súkromný prístup, použite dedikovanú gateway s režimom vyžadujúcim token — tým obmedzíte prístup cez vašu gateway, hoci obsah zostane dostupný na širšej sieti IPFS.

Prečo sa moje nové CID zmenili z Qm... na bafy...?

Nové nahrávania a pripnutia vracajú moderné CIDv1 (bafk… pre malý jednoblokový obsah, bafy… pre väčšie súbory a priečinky) podľa profilu IPIP-0499 unixfs-v1-2025: kódovanie CIDv1 base32, 1 MiB chunky, raw leaves. Toto zodpovedá tomu, čo produkujú moderné nástroje (Helia, najnovší Kubo, ipfs-car) pre rovnaký obsah, takže súbor nahraný cez nás dostane rovnaký CID, aký by pre rovnaké bajty vypočítal akýkoľvek moderný klient.

Staršie CID Qm… z predchádzajúcich nahrávaní zostávajú plne rozpoznateľné — gateway, POST /pin, GET /file, IPNS a každý ďalší endpoint prijímajú oba formáty natrvalo. Nič, čo už máte, prestáva fungovať.

Ako pripnem obsah, ktorý sa nachádza na súkromnom / non-DHT uzle?

POST /pin prijíma voliteľné multiaddresses[] (do 5). Ak sú zadané, náš cluster vykoná ipfs swarm connect <multiaddr> pre každý tip pred začatím pripínania, takže obsah na uzloch, ktoré sa neinzerujú cez verejné DHT (súkromné uzly, staging prostredia, VPN-lokálne stroje), je dosiahnuteľný. Pozrite si sprievodcu Pripnutie zo súkromného IPFS uzla.

Zostanú moje súbory na IPFS, ak zruším účet?

Pri zrušení odpneme vaše súbory z našich uzlov. Ak iné IPFS uzly majú váš obsah v medzipamäti, môže zostať prístupný. Bez aktívneho pripnutia však budú súbory postupne odstránené zberom odpadu v celej sieti.

Autentifikácia & API

Ako autentifikujem API požiadavky?

Odošlite svoj API kľúč cez hlavičku X-Api-Key. Kľúče generujte zo stránky API kľúče vo vašom ovládacom paneli.

Existujú limity rýchlosti API?

Nie. IPFS Ninja neukladá žiadne limity rýchlosti na API požiadavky. Na akomkoľvek pláne môžete vykonávať toľko požiadaviek, koľko potrebujete.

Majú API kľúče expiráciu?

Nie. API kľúče sú platné, kým ich nezmažete. Môžete vytvoriť viacero kľúčov a jednotlivo ich odvolať.

Aký je rozdiel medzi API kľúčmi a tokenmi gateway?

API kľúče (bws_) majú plný prístup — nahrávanie, mazanie, zoznam súborov. Tokeny gateway (gwt_) sú len na čítanie a môžu pristupovať k súborom iba cez vašu dedikovanú gateway. Tokeny gateway je bezpečné vkladať do frontendových aplikácií.

Dedikované gateway

Čo je dedikovaná gateway?

Súkromná IPFS gateway na vašej vlastnej subdoméne (napr. abc123.gw.ipfs.ninja), ktorá obsluhuje iba súbory pripnuté k vášmu účtu. Na rozdiel od verejnej gateway nebude prekladať CID od iných používateľov.

Ktoré plány zahŕňajú dedikovanú gateway?

Dedikované gateway sú dostupné vo všetkých platených plánoch (Bodhi 5 $/mes., Karma 19 $/mes., Nirvana 59 $/mes.). Mesačný limit šírky pásma každého plánu pokrýva prevádzku z apex aj dedikovanej gateway. Konkrétne limity podľa plánu nájdete nižšie v otázke „Sú poplatky za šírku pásma?".

Môžem obmedziť, kto pristupuje k mojej gateway?

Áno. Môžete povoliť režim vyžadujúci token (vyžaduje token gwt_ pri každej požiadavke) a/alebo nastaviť whitelist IP adries (až 100 adries).

Môžem obmedziť moju gateway podľa pôvodu/domény?

Áno. Nakonfigurujte allowedOrigins vo vašich nastaveniach gateway so zoznamom HTTPS pôvodov. Povolené budú iba požiadavky z prehliadačov z týchto pôvodov. Požiadavky mimo prehliadač (bez hlavičky Origin) prechádzajú bez obmedzenia. Prázdny zoznam povoľuje všetky pôvody.

Čo sú podpísané tokeny na nahrávanie?

Podpísané tokeny na nahrávanie sú časovo obmedzené prihlasovacie údaje pre nahrávanie na strane klienta. Generujete ich na svojom serveri pomocou POST /upload/signed-url a predávate ich prehliadačom alebo mobilným aplikáciám. Klient sa autentifikuje pomocou Authorization: Signed <token> namiesto odhalenia vášho API kľúča. Každý token sleduje využitie a automaticky expiruje. Podrobnosti nájdete v dokumentácii Podpísaných tokenov.

Môžem optimalizovať obrázky servírované z IPFS?

Áno. Použite GET /image/:cid s parametrami dopytu ako w, h, format a quality na zmenu veľkosti, prevod a kompresiu obrázkov za behu. Odpovede sú ukladané do medzipamäte na základe CID adresovaného obsahom. Funguje to na všetkých plánoch. Pozrite si Optimalizácia obrázkov.

Môžem pripojiť metadáta k súborom?

Áno. Zahrňte objekt metadata s až 10 pármi kľúč-hodnota pri nahrávaní cez POST /upload/new alebo pripínaní cez POST /pin. Metadáta sú vrátené v zoznamoch súborov a v endpointe detailu súboru. Pozrite si dokumentáciu Súbory a Pripínanie.

Fakturácia & plány

Existuje bezplatný plán?

Áno. Plán Dharma je zadarmo navždy — 1 GB úložiska, neobmedzené API požiadavky, bez nutnosti kreditnej karty.

Sú poplatky za šírku pásma?

Žiadne poplatky za meranú šírku pásma na žiadnom pláne. Každý plán zahŕňa mesačný limit šírky pásma gateway, ktorý je tvrdým stropom — obsluha vášho obsahu na apex aj dedikovanej gateway sa zastaví po dosiahnutí limitu a obnoví sa 1. deň nasledujúceho mesiaca alebo po upgrade:

Plán	Mesačná šírka pásma
Dharma	2 GB
Bodhi	20 GB
Karma	100 GB
Nirvana	500 GB

Pri dosiahnutí 80 % a 100 % limitu dostanete upozorňujúce e-maily.

Obnovuje sa úložisko?

Úložisko sa neobnovuje. Váš plán zahŕňa celkový úložný limit (Dharma 1 GB / Bodhi 10 GB / Karma 100 GB / Nirvana 1 TB). Pre uvoľnenie miesta zmažte súbory, ktoré už nepotrebujete. Upgrade plánu zvýši váš celkový limit.

Môžem kedykoľvek zrušiť?

Áno. Zrušte predplatné cez fakturačný portál — bez záväzku. Váš účet sa vráti na bezplatnú úroveň a existujúce pripnuté súbory zostanú prístupné.

Čo sa stane s mojimi súbormi, ak downgradnem?

Vaše súbory zostanú pripnuté na IPFS, ale nemôžete nahrávať ďalšie, ak vaše aktuálne využitie presahuje úložný limit nového plánu. Zmažte súbory, aby ste sa vrátili pod limit.

Bezpečnosť

Sú moje dáta šifrované?

Všetky dáta sú šifrované pri prenose cez TLS/HTTPS. Autentifikácia používa JWT tokeny (Cognito) a bezpečne uložené API kľúče. Obsah súborov na IPFS nie je šifrovaný v kľudovom stave — IPFS je zo svojej podstaty verejná sieť.

Je bezpečné používať API kľúče v mojom serverovom kóde?

Áno. API kľúče sú navrhnuté na použitie na strane servera. Nikdy ich nevystavujte v kóde na strane klienta. Pre prístup k súborom na strane klienta používajte tokeny gateway (gwt_), ktoré sú len na čítanie.

Podpora

Ako získam pomoc?

Napíšte na info@ipfs.ninja alebo si pozrite dokumentáciu Referenčná príručka API.

Existuje SLA?

Usilujeme sa o vysokú dostupnosť, ale v súčasnosti neponúkame formálnu SLA. Služba je poskytovaná na základe „tak, ako je".