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-шлюз обслуговує лише CID, які були завантажені або закріплені користувачем IPFS Ninja. Запити для невідомих CID повертають HTTP 410 Gone з вказівником на публічні IPFS-шлюзи (ipfs.io, dweb.link). Щоб обслуговувати CID третьої сторони через наш шлюз, спочатку виконайте POST /pin для свого облікового запису — після закріплення CID стає доступним як на apex URL, так і на URL вашого виділеного шлюзу.

Яка різниця між apex-шлюзом і виділеним шлюзом?

Аспект	Apex ipfs.ninja/ipfs/<CID>	Виділений <slug>.gw.ipfs.ninja/ipfs/<CID>
Область	Спільна для всіх користувачів	Тільки ваші CID
Автентифікація	Немає	Опціональний токен / IP allowlist / origin allowlist
SLA	Best-effort	Повний SLA
Рекомендовано для	Випадкових посилань	Продакшн-вбудовування (NFT, відео, сайти)
Ліміти швидкості	Спільні по IP + по CID	За планом, налаштовувані

Обидва обслуговують ідентичний вміст. Для продакшн-трафіку використовуйте виділений шлюз.

Які типи файлів підтримуються?

Підтримуються всі типи файлів. JSON-об'єкти та масиви можна надсилати безпосередньо. Усі інші файли (зображення, PDF, HTML, відео, аудіо, бінарні) надсилаються як контент, закодований у base64.

Чи є обмеження на розмір файлу?

Окремі завантаження обмежені обсягом сховища вашого плану. Немає обмеження розміру окремого файлу, крім вашого доступного сховища.

Чи можу я закріпити контент, який вже існує на IPFS?

Так. Використовуйте POST /pin з будь-яким валідним CID. Наш кластер завантажить контент з мережі IPFS і закріпить його до вашого акаунту. Деталі в документації API Pinning.

Скільки часу займає пінінг?

Залежить від розміру файлу та кількості вузлів IPFS, що мають контент. Малі, добре розподілені файли закріплюються за секунди. Великий або рідко закріплений контент може зайняти кілька хвилин. Ендпоінт пін повертає відповідь негайно зі статусом pinning — опитуйте GET /pin/:cid, щоб перевірити прогрес.

Що відбувається, якщо CID не вдається знайти?

Статус змінюється на failed. Це означає, що CID недійсний або контент більше недоступний на жодному досяжному вузлі IPFS.

Чи є дані, завантажені на IPFS, публічними?

Так. Весь контент, закріплений на IPFS, публічно доступний через його CID через будь-який gateway IPFS. Якщо вам потрібен приватний доступ, використовуйте виділений gateway з режимом token-required — це обмежує доступ через ваш gateway, хоча контент залишається доступним у ширшій мережі IPFS.

Чому мої нові CID змінилися з Qm... на bafy...?

Нові завантаження та піни повертають сучасні CIDv1 (bafk… для малого одноблокового контенту, bafy… для більших файлів і директорій) відповідно до профілю IPIP-0499 unixfs-v1-2025: base32-кодування CIDv1, блоки по 1 MiB, raw leaves. Це збігається з тим, що виробляють сучасні інструменти (Helia, найновіший Kubo, ipfs-car) для того самого контенту, тож файл, завантажений через нас, отримує той самий CID, який обчислив би будь-який сучасний клієнт для тих самих байтів.

Застарілі CID Qm… з попередніх завантажень залишаються повністю розв'язуваними — gateway, POST /pin, GET /file, IPNS та кожен інший ендпоінт приймають обидва формати необмежено довго. Ніщо з того, що у вас вже є, не перестає працювати.

Як мені закріпити контент, що знаходиться на приватному / не-DHT вузлі?

POST /pin приймає опціональні multiaddresses[] (до 5). Якщо вони передані, наш кластер виконує ipfs swarm connect <multiaddr> для кожної підказки перед запуском пінінгу, тому контент на пірах, що не анонсують себе через публічний DHT (приватні вузли, staging-середовища, машини у VPN), стає доступним. Див. посібник Закріплення з приватного вузла IPFS.

Чи залишаться мої файли на IPFS, якщо я скасую свій акаунт?

Ми відкріплюємо ваші файли від наших вузлів при скасуванні. Якщо інші вузли IPFS зберегли ваш контент у кеші, він може залишатися доступним. Однак без активного пінінгу файли з часом будуть видалені збиранням сміття в мережі.

Автентифікація та API

Як автентифікувати API-запити?

Передайте свій API key через заголовок X-Api-Key. Генеруйте ключі на сторінці API Keys у вашій dashboard.

Чи є обмеження частоти API?

Ні. IPFS Ninja не накладає обмежень частоти на API-запити. Ви можете робити стільки запитів, скільки потрібно, на будь-якому плані.

Чи закінчується термін дії API key?

Ні. API key дійсні, поки ви їх не видалите. Ви можете створити кілька ключів і відкликати їх окремо.

У чому різниця між API key і токенами gateway?

API key (bws_) мають повний доступ — завантаження, видалення, перегляд файлів. Токени gateway (gwt_) мають доступ тільки для читання і можуть отримувати файли лише через ваш виділений gateway. Токени gateway безпечно вбудовувати у фронтенд-додатки.

Виділені gateway

Що таке виділений gateway?

Приватний IPFS gateway на вашому власному піддомені (напр. abc123.gw.ipfs.ninja), який обслуговує тільки файли, закріплені до вашого акаунту. На відміну від публічного gateway, він не буде розв'язувати CID інших користувачів.

Які плани включають виділений gateway?

Виділені gateway доступні на всіх платних планах (Bodhi $5/міс., Karma $19/міс., Nirvana $59/міс.). Місячна квота пропускної здатності кожного плану охоплює трафік як з apex, так і з виділеного gateway. Див. "Чи є плата за пропускну здатність?" нижче для квот за планами.

Чи можу я обмежити, хто має доступ до мого gateway?

Так. Ви можете увімкнути режим token-required (вимагає токен gwt_ для кожного запиту) та/або налаштувати білий список IP (до 100 адрес).

Чи можу я обмежити мій gateway за джерелом/доменом?

Так. Налаштуйте allowedOrigins у налаштуваннях gateway зі списком HTTPS-джерел. Тільки запити браузера з цих джерел будуть дозволені. Небраузерні запити (без заголовка Origin) проходять без обмежень. Порожній список дозволяє всі джерела.

Що таке підписані токени завантаження?

Підписані токени завантаження — це облікові дані з обмеженим терміном для завантажень на стороні клієнта. Ви генеруєте їх на своєму сервері за допомогою POST /upload/signed-url і передаєте браузерам або мобільним додаткам. Клієнт автентифікується через Authorization: Signed <token> замість розкриття вашого API key. Кожен токен відстежує використання та закінчується автоматично. Деталі в документації підписаних токенів.

Чи можу я оптимізувати зображення з IPFS?

Так. Використовуйте GET /image/:cid з параметрами запиту, такими як w, h, format і quality, щоб змінювати розмір, конвертувати та стискати зображення на льоту. Відповіді кешуються на основі CID. Працює на всіх планах. Див. Оптимізація зображень.

Чи можу я додавати метадані до файлів?

Так. Додайте об'єкт metadata з до 10 пар ключ-значення при завантаженні через POST /upload/new або закріпленні через POST /pin. Метадані повертаються у списках файлів та ендпоінті деталей файлу. Див. документацію Файли та Pinning.

Оплата та плани

Чи є безкоштовний план?

Так. План Dharma безкоштовний назавжди — 1 ГБ сховища, необмежені API-запити, кредитна картка не потрібна.

Чи є плата за пропускну здатність?

Немає плати за виміряну пропускну здатність на жодному плані. Кожен план включає місячну квоту пропускної здатності gateway, яка є жорстким обмеженням — обслуговування вашого контенту через apex та виділений gateway зупиняється після досягнення квоти і відновлюється 1-го числа наступного місяця або після оновлення плану:

План	Місячна пропускна здатність
Dharma	2 ГБ
Bodhi	20 ГБ
Karma	100 ГБ
Nirvana	500 ГБ

Ви отримаєте попереджувальні листи на 80% та 100% вашої квоти.

Чи скидається сховище?

Сховище не скидається. Ваш план включає загальний обсяг сховища (Dharma 1 ГБ / Bodhi 10 ГБ / Karma 100 ГБ / Nirvana 1 ТБ). Щоб звільнити місце, видаліть файли, які вам більше не потрібні. Оновлення плану збільшує ваш загальний обсяг.

Чи можу я скасувати в будь-який час?

Так. Скасуйте підписку через портал оплати — без зобов'язань. Ваш акаунт повертається до безкоштовного рівня, а існуючі закріплені файли залишаються доступними.

Що відбувається з моїми файлами, якщо я понижу план?

Ваші файли залишаються закріпленими на IPFS, але ви не зможете завантажувати більше, якщо ваше поточне використання перевищує ліміт сховища нового плану. Видаліть файли, щоб повернутися нижче ліміту.

Безпека

Чи зашифровані мої дані?

Усі дані зашифровані при передачі через TLS/HTTPS. Автентифікація використовує JWT-токени (Cognito) та безпечно збережені API key. Вміст файлів на IPFS не зашифрований у стані спокою — IPFS за своєю природою є публічною мережею.

Чи безпечно використовувати API key в моєму серверному коді?

Так. API key призначені для серверного використання. Ніколи не розкривайте їх у клієнтському коді. Для клієнтського доступу до файлів використовуйте токени gateway (gwt_), які мають доступ тільки для читання.

Підтримка

Як отримати допомогу?

Напишіть на info@ipfs.ninja або перевірте документацію Довідник API.

Чи є SLA?

Ми прагнемо до високої доступності, але наразі не пропонуємо формального SLA. Сервіс надається на умовах "як є".