FAQ

Често постављана питања о IPFS Ninja.

Опште

Шта је IPFS Ninja?

IPFS Ninja је управљана услуга качења на IPFS. Отпремате било који фајл преко једноставног REST API-ја, или качите постојеће CID-ове са IPFS мреже. Сваки фајл добија трајни идентификатор садржаја (CID) и доступан је преко нашег gateway-а на ipfs.ninja/ipfs/<CID>.

Да ли ipfs.ninja/ipfs/<CID> сервира било који CID на IPFS мрежи?

Не. Apex gateway сервира само CID-ове које је отпремио или закачио корисник IPFS Ninja. Захтеви за непознате CID-ове враћају HTTP 410 Gone са показивачем на јавне IPFS gateway-е (ipfs.io, dweb.link). Да бисте сервирали CID треће стране преко нашег gateway-а, прво извршите POST /pin на свој налог — једном закачен, CID постаје доступан и на apex-у и на URL-у вашег наменског gateway-а.

Која је разлика између apex gateway-а и наменског gateway-а?

Аспект	Apex ipfs.ninja/ipfs/<CID>	Наменски <slug>.gw.ipfs.ninja/ipfs/<CID>
Опсег	Дељен код свих корисника	Само ваши CID-ови
Аутентификација	Нема	Опциони токен / IP allowlist / origin allowlist
SLA	Best-effort	Пуни SLA
Препоручује се за	Повремене линкове	Продукцијску уградњу (NFT, видео, сајтови)
Ограничења брзине	Дељена по IP-у + по CID-у	По плану, подесиво

Оба сервирају идентичан садржај. За продукцијски саобраћај користите наменски gateway.

Који типови фајлова су подржани?

Сви типови фајлова су подржани. JSON објекти и низови могу се слати директно. Сви остали фајлови (слике, PDF, HTML, видео, аудио, бинарни фајлови) шаљу се као base64-кодирани садржај.

Постоји ли ограничење величине фајла?

Појединачна отпремања су ограничена капацитетом складиштења вашег плана. Нема ограничења величине по фајлу осим доступног складиштења.

Могу ли да закачим садржај који већ постоји на IPFS-у?

Да. Користите POST /pin са било којим важећим CID-ом. Наш кластер ће преузети садржај са IPFS мреже и закачити га на ваш налог. Погледајте документацију Pinning API-ја за детаље.

Колико дуго траје качење?

Зависи од величине фајла и броја IPFS чворова који имају садржај. Мали, добро дистрибуирани фајлови се закаче за секунде. Велики или ретко качени садржај може трајати неколико минута. Крајња тачка за качење одмах враћа статус pinning — проверавајте GET /pin/:cid за праћење напретка.

Шта се дешава ако CID не може бити пронађен?

Статус се мења у failed. То значи да је CID или неважећи или да садржај више није доступан на ниједном доступном IPFS чвору.

Да ли су подаци отпремљени на IPFS јавни?

Да. Сав садржај закачен на IPFS је јавно доступан преко свог CID-а кроз било који IPFS gateway. Ако вам је потребан приватни приступ, користите наменски gateway са режимом обавезног токена — ово ограничава приступ преко вашег gateway-а, иако садржај остаје доступан на широј IPFS мрежи.

Зашто су се моји нови CID-ови променили из Qm... у bafy...?

Нова отпремања и качења враћају модерни CIDv1 (bafk… за мали садржај у једном блоку, bafy… за веће фајлове и директоријуме) у складу са профилом IPIP-0499 unixfs-v1-2025: CIDv1 base32 кодирање, делови од 1 MiB, сирови листови (raw leaves). Ово одговара ономе што производе модерни алати (Helia, најновији Kubo, ipfs-car) за исти садржај, тако да фајл отпремљен преко нас добија исти CID који би сваки модерни клијент израчунао за исте бајтове.

Стари Qm… CID-ови са ранијих отпремања остају потпуно разрешиви — gateway, POST /pin, GET /file, IPNS и свака друга крајња тачка прихватају оба формата неограничено. Ништа што већ имате не престаје да ради.

Како качим садржај који живи на приватном / не-DHT чвору?

POST /pin прихвата опционе multiaddresses[] (до 5). Ако су прослеђене, наш кластер извршава ipfs swarm connect <multiaddr> за сваки наговештај пре него што качење почне, тако да је садржај на чворовима који се не оглашавају преко јавног DHT-а (приватни чворови, staging окружења, VPN-локалне машине) доступан. Погледајте водич Качење са приватног IPFS чвора.

Да ли ће моји фајлови остати на IPFS-у ако откажем налог?

При отказивању откачујемо ваше фајлове са наших чворова. Ако су други IPFS чворови кеширали ваш садржај, може остати доступан. Међутим, без активног качења, фајлови ће временом бити уклоњени сакупљањем отпадака у целој мрежи.

Аутентификација и API

Како аутентификујем API захтеве?

Проследите свој API кључ преко заглавља X-Api-Key. Кључеве генеришите са странице API кључеви на вашој контролној табли.

Постоје ли ограничења брзине API-ја?

Не. IPFS Ninja не намеће ограничења брзине на API захтеве. Можете слати колико год захтева вам је потребно на било ком плану.

Да ли API кључеви истичу?

Не. API кључеви важе док их не обришете. Можете креирати више кључева и појединачно их опозвати.

Која је разлика између API кључева и токена gateway-а?

API кључеви (bws_) имају потпуни приступ — отпремање, брисање, листа фајлова. Токени gateway-а (gwt_) су само за читање и могу приступити фајловима само преко вашег наменског gateway-а. Токене gateway-а безбедно је уградити у frontend апликације.

Наменски gateway-и

Шта је наменски gateway?

Приватни IPFS gateway на вашем сопственом поддомену (нпр. abc123.gw.ipfs.ninja) који сервира само фајлове закачене на ваш налог. За разлику од јавног gateway-а, неће разрешавати CID-ове других корисника.

Који планови укључују наменски gateway?

Наменски gateway-и доступни су у свим плаћеним плановима (Bodhi $5/мес, Karma $19/мес, Nirvana $59/мес). Месечна квота пропусног опсега сваког плана покрива саобраћај и са apex-а и са наменског gateway-а. Погледајте „Постоје ли накнаде за пропусни опсег?" испод за квоте по плану.

Могу ли да ограничим ко приступа мом gateway-у?

Да. Можете омогућити режим обавезног токена (захтева gwt_ токен при сваком захтеву) и/или поставити белу листу IP адреса (до 100 адреса).

Могу ли да ограничим свој gateway по пореклу/домену?

Да. Конфигуришите allowedOrigins у вашим подешавањима gateway-а са листом HTTPS порекла. Само захтеви из прегледача са тих порекла ће бити дозвољени. Захтеви ван прегледача (без заглавља Origin) пролазе без ограничења. Празна листа дозвољава сва порекла.

Шта су потписани токени за отпремање?

Потписани токени за отпремање су временски ограничени акредитиви за отпремање на страни клијента. Генеришете их на свом серверу користећи POST /upload/signed-url и прослеђујете их прегледачима или мобилним апликацијама. Клијент се аутентификује са Authorization: Signed <token> уместо откривања вашег API кључа. Сваки токен прати коришћење и аутоматски истиче. Погледајте документацију Потписаних токена за детаље.

Могу ли да оптимизујем слике сервиране са IPFS-а?

Да. Користите GET /image/:cid са параметрима упита као w, h, format и quality за промену величине, конверзију и компресију слика у ходу. Одговори се кеширају на основу CID-а адресираног садржајем. Ради на свим плановима. Погледајте Оптимизација слика.

Могу ли да прикачим метаподатке фајловима?

Да. Укључите објекат metadata са до 10 парова кључ-вредност при отпремању преко POST /upload/new или качењу преко POST /pin. Метаподаци се враћају у листама фајлова и на крајњој тачки детаља фајла. Погледајте документацију Фајлови и Качење.

Наплата и планови

Постоји ли бесплатан план?

Да. План Dharma је бесплатан заувек — 1 GB складиштења, неограничени API захтеви, без потребе за кредитном картицом.

Постоје ли накнаде за пропусни опсег?

Нема мерених накнада за пропусни опсег ни на једном плану. Сваки план укључује месечну квоту пропусног опсега gateway-а која представља тврду границу — ваш садржај престаје да се сервира на apex и наменском gateway-у када се квота достигне, а наставља 1. дана следећег месеца или после надоградње:

План	Месечни пропусни опсег
Dharma	2 GB
Bodhi	20 GB
Karma	100 GB
Nirvana	500 GB

Примићете упозорења путем имејла на 80% и 100% ваше квоте.

Да ли се складиштење ресетује?

Складиштење се не ресетује. Ваш план укључује укупни лимит складиштења (Dharma 1 GB / Bodhi 10 GB / Karma 100 GB / Nirvana 1 TB). За ослобађање простора обришите фајлове који вам више нису потребни. Надоградња плана повећава ваш укупни лимит.

Могу ли да откажем било кад?

Да. Откажите претплату преко портала за наплату — без обавеза. Ваш налог се враћа на бесплатни ниво, а постојећи закачени фајлови остају доступни.

Шта се дешава са мојим фајловима ако снизим план?

Ваши фајлови остају закачени на IPFS-у, али не можете отпремати више ако ваше тренутно коришћење премашује лимит складиштења новог плана. Обришите фајлове да бисте се вратили испод ограничења.

Безбедност

Да ли су моји подаци шифровани?

Сви подаци су шифровани у транзиту преко TLS/HTTPS. Аутентификација користи JWT токене (Cognito) и безбедно складиштене API кључеве. Садржај фајлова на IPFS-у није шифрован у стању мировања — IPFS је по дизајну јавна мрежа.

Да ли је безбедно користити API кључеве у мом серверском коду?

Да. API кључеви су дизајнирани за коришћење на страни сервера. Никада их не излажите у коду на страни клијента. За приступ фајловима на страни клијента користите токене gateway-а (gwt_), који су само за читање.

Подршка

Како могу добити помоћ?

Пошаљите имејл на info@ipfs.ninja или погледајте документацију Референца API-ја.

Постоји ли SLA?

Тежимо високој доступности, али тренутно не нудимо формални SLA. Услуга се пружа на основу „таква каква јесте".