Закрепление

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

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

POST /pin

Параметр	Тип	Обязательный	Описание
cid	string	Да	Идентификатор содержимого IPFS (начинается с Qm или bafy).
description	string	Нет	Краткое описание для вашего удобства.
metadata	object	Нет	Пользовательские пары ключ-значение для прикрепления к закреплению. Максимум 10 ключей. Ключи должны быть буквенно-цифровыми или содержать символ подчёркивания, 1-64 символа. Значения должны быть строками, максимум 256 символов каждое. Общий размер метаданных не должен превышать 4 КБ.

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

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

Ответ 202 Accepted

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

TIP

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

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

GET /pin/:cid

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

Ответ 200 OK

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

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

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

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

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

WARNING

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

Хранилище

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