Закачане

Закачете съществуващо 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 multiaddress-а на пиъри, които съхраняват 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"
    }
  }'

Response 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": { … }
}

Приети форми на multiaddress

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

Получаване на multiaddress на вашия възел

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

Закачане на много големи директории

POST /pin е за съдържание, което вече живее в IPFS мрежата — клъстерът извлича DAG-а блок по блок от пиъри, което може да отнеме няколко минути за директории с 1000+ файла. По време на този прозорец на извличане някои дъщерни файлове може все още да не са локално налични и заявките към gateway за тях може да изтекат по време. След като статусът на родителя се промени на pinned, всяко дете е локално налично и достъпно чрез вашия gateway.

Ако имате файловете локално (вместо само CID), предпочетете CAR импорт за големи NFT колекции или набори от данни — той качва целия 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-ът, който проверявате.

Response 200 OK

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

Стойности на статуса

Status	Значение
pinning	Съдържанието се извлича от IPFS мрежата. Проверете отново след няколко секунди.
pinned	Съдържанието е закачено и достъпно чрез вашия акаунт и gateway.
failed	Съдържанието не може да бъде намерено в IPFS мрежата. CID-ът може да е невалиден или съдържанието вече не е достъпно.

Как работи закачането

1. Изпращате CID чрез POST /pin
2. Нашият IPFS клъстер търси в мрежата възли, които имат съдържанието
3. Клъстерът изтегля и закача съдържанието локално
4. След закачане файлът се появява в списъка ви с файлове и е достъпен чрез gateway
5. Използването на съхранение се записва при завършване на закачането

WARNING

Времето за закачане зависи от размера на файла и наличността в мрежата. Малки файлове обикновено се закачат за секунди. Големи файлове или рядко закачано съдържание може да отнеме минути.

Съхранение

Закаченото съдържание се отчита в лимита за съхранение на вашия план. Размерът на файла се записва при завършване на закачането. Ако наближите лимита си за съхранение, можете да освободите място, като изтриете неизползвани файлове, или да надградите за повече капацитет.