Закрепление

Закрепите существующий контент IPFS в своём аккаунте. При закреплении CID наш кластер получает контент из сети IPFS и хранит его постоянно доступным.

Закрепить по CID

POST /pin

Параметр	Тип	Обязательный	Описание
cid	string	Да	Идентификатор содержимого IPFS. Принимается в любой форме: CIDv0 (Qm…), CIDv1 base32 (bafk…, bafy… и другие кодеки).
description	string	Нет	Краткое описание для вашего удобства.
metadata	object	Нет	Пользовательские пары ключ-значение для прикрепления к закреплению. Максимум 10 ключей. Ключи должны быть буквенно-цифровыми или содержать символ подчёркивания, 1-64 символа. Значения должны быть строками, максимум 256 символов каждое. Общий размер метаданных не должен превышать 4 KB.
multiaddresses	string[]	Нет	Необязательные подсказки для swarm-connect. До 5 мультиадресов libp2p узлов, у которых хранится этот CID. Наш кластер параллельно выполняет swarm connect для каждого адреса до начала закрепления, поэтому контент на приватных / не-DHT узлах становится доступен без ожидания обнаружения через DHT. Работает по принципу best-effort — неудачное подключение не приводит к сбою закрепления. См. Закрепление с приватного узла.

Пример запроса

curl -X POST https://api.ipfs.ninja/pin \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "description": "NFT metadata",
    "metadata": {
      "collection": "my-nfts",
      "token_id": "42"
    }
  }'

Ответ 202 Accepted

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinning",
  "description": "NFT metadata",
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

Для больших DAG (>500 блоков или >50 MB) ответ включает флаг async: true:

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinning",
  "async": true,
  "note": "Large DAG detected — pin running in background. Check status via GET /pin/bafybei…",
  "uris": { ... }
}

Закрепление с приватного узла

Если CID, который вы хотите закрепить, находится на узле, не участвующем в публичной DHT — приватный staging-узел, самостоятельно размещённая машина в VPN или рабочая станция за NAT — стандартный процесс закрепления его не найдёт. Передача одного или нескольких multiaddresses точно сообщает нашему кластеру, где искать.

Мы выполняем ipfs swarm connect <multiaddr> для каждой подсказки параллельно до запуска закрепления. Если подключение успешно, получение DAG для закрепления может обращаться напрямую к вашему узлу вместо поиска по DHT. Если оно неудачно, закрепление всё равно продолжается через публичную сеть (семантика best-effort).

Пример: закрепление с конкретного узла

curl -X POST https://api.ipfs.ninja/pin \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "description": "internal staging build",
    "multiaddresses": [
      "/ip4/203.0.113.42/tcp/4001/p2p/12D3KooWH3uVF6wv47WnArKHk5p6cvgCJEb74UTmxztmQDc298L3",
      "/dns4/node.internal.example/tcp/443/wss/p2p/12D3KooWH3uVF6wv47WnArKHk5p6cvgCJEb74UTmxztmQDc298L3"
    ]
  }'

Ответ включает статус по каждой подсказке

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinning",
  "swarmConnected": [
    { "multiaddr": "/ip4/203.0.113.42/tcp/4001/p2p/12D3KooW…", "ok": true,  "strings": ["connect 12D3KooW… success"] },
    { "multiaddr": "/dns4/node.internal.example/tcp/443/…",   "ok": false, "error": "dial to peer: no route" }
  ],
  "uris": { … }
}

Поддерживаемые формы мультиадресов

Поддерживаются распространённые формы: транспорты /ip4, /ip6, /dns4, /dns6, /dns, /dnsaddr; протоколы /tcp или /udp; опциональные надстройки /quic-v1, /quic, /ws, /wss, /http, /https, /webtransport, /webrtc-direct. Мультиадрес должен заканчиваться на /p2p/<peerId>. Лимит: до 5 подсказок на одно закрепление.

Как получить мультиадрес вашего узла

На узле, с которого вы хотите закрепить контент, выполните ipfs id и скопируйте любую из записей Addresses, заканчивающуюся на /p2p/<PeerID>. Предпочитайте публично маршрутизируемые адреса (/ip4/YOUR_PUBLIC_IP/…) или адреса на основе DNS (/dnsaddr/your.domain/…), чтобы наш кластер мог достучаться до узла из AWS.

Закрепление очень больших директорий

POST /pin предназначен для контента, который уже находится в сети IPFS — кластер получает DAG блок за блоком от узлов сети, что для директорий с 1000+ файлами может занять несколько минут. В течение этого окна получения некоторые дочерние файлы могут быть ещё недоступны локально, и запросы к шлюзу для них могут завершаться по таймауту. Как только status родительского элемента переключается на pinned, каждый дочерний элемент доступен локально и через ваш шлюз.

Если файлы уже есть у вас локально (а не только CID), для больших коллекций NFT или датасетов предпочтительнее использовать импорт CAR — он загружает весь DAG в IPFS Ninja одним атомарным запросом, поэтому окна получения нет и нет состояния частичного закрепления. Создайте CAR с помощью:

npx ipfs-car pack ./my-collection -o collection.car

Затем импортируйте его через POST /upload/new с car: true.

TIP

Закрепление выполняется асинхронно. Ответ возвращается немедленно со статусом pinning. Опрашивайте конечную точку статуса, чтобы проверить, когда закрепление завершится.

Проверить статус закрепления

GET /pin/:cid

Параметр	Тип	Обязательный	Описание
cid	string	Да	CID, который вы проверяете.

Ответ 200 OK

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinned",
  "sizeMB": 0.042,
  "fileName": "NFT metadata",
  "pinnedAt": 1711036800000,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

Значения статуса

Статус	Значение
pinning	Контент получается из сети IPFS. Повторите запрос через несколько секунд.
pinned	Контент закреплён и доступен через ваш аккаунт и шлюз.
failed	Контент не найден в сети IPFS. CID может быть недействительным или контент больше недоступен.

Как работает закрепление

1. Вы отправляете CID через POST /pin
2. Наш кластер IPFS ищет в сети узлы, имеющие контент
3. Кластер скачивает контент и закрепляет его локально
4. После закрепления файл появляется в вашем списке файлов и доступен через шлюз
5. Использование хранилища фиксируется после завершения закрепления

WARNING

Время закрепления зависит от размера файла и доступности в сети. Небольшие файлы обычно закрепляются за секунды. Большие файлы или редко закреплённый контент может потребовать нескольких минут.

Хранилище

Закреплённый контент учитывается в лимите хранилища вашего плана. Размер файла фиксируется при завершении закрепления. Если вы приближаетесь к лимиту хранилища, вы можете освободить место, удалив неиспользуемые файлы, или обновить план для большей ёмкости.