Ghim

Ghim nội dung IPFS hiện có vào tài khoản của bạn. Khi bạn ghim một CID, cụm của chúng tôi tìm nạp nội dung từ mạng IPFS và giữ nó khả dụng vĩnh viễn.

Ghim theo CID

POST /pin

Tham số	Kiểu	Bắt buộc	Mô tả
cid	string	Có	Mã định danh nội dung IPFS. Chấp nhận mọi dạng: CIDv0 (Qm…), CIDv1 base32 (bafk…, bafy…, và các codec khác).
description	string	Không	Mô tả ngắn để bạn tham khảo.
metadata	object	Không	Cặp khóa-giá trị tùy chỉnh để đính kèm vào pin. Tối đa 10 khóa. Khóa phải là chữ và số hoặc dấu gạch dưới, 1-64 ký tự. Giá trị phải là chuỗi, tối đa 256 ký tự. Tổng kích thước siêu dữ liệu không được vượt quá 4 KB.
multiaddresses	string[]	Không	Gợi ý swarm-connect tùy chọn. Tối đa 5 multiaddress libp2p của các peer đang lưu trữ CID. Cụm của chúng tôi chạy swarm connect với từng địa chỉ song song trước khi ghim, để nội dung trên các peer riêng tư / không thuộc DHT vẫn có thể truy cập được mà không cần chờ khám phá qua DHT. Nỗ lực tối đa — kết nối thất bại không làm ghim thất bại. Xem Ghim từ một node riêng tư.

Ví dụ yêu cầu

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"
    }
  }'

Phản hồi 202 Accepted

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

Đối với DAG lớn (>500 khối hoặc >50 MB), phản hồi bao gồm cờ async: true:

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

Ghim từ một node riêng tư

Nếu CID bạn muốn ghim nằm trên một peer không tham gia vào DHT công khai — một node staging riêng tư, một máy tự lưu trữ trên VPN, hoặc một máy trạm sau NAT — luồng ghim mặc định sẽ không tìm thấy nó. Truyền một hoặc nhiều multiaddresses cho cụm của chúng tôi biết chính xác nơi cần tìm.

Chúng tôi chạy ipfs swarm connect <multiaddr> cho từng gợi ý song song trước khi ghim chạy. Nếu kết nối thành công, việc tìm nạp DAG của pin có thể nói chuyện trực tiếp với peer của bạn thay vì tìm kiếm qua DHT. Nếu thất bại, pin vẫn tiếp tục với mạng công khai (theo cơ chế nỗ lực tối đa).

Ví dụ: ghim từ một peer cụ thể

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"
    ]
  }'

Phản hồi bao gồm trạng thái cho từng gợi ý

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

Các dạng multiaddress được chấp nhận

Các dạng phổ biến được hỗ trợ: các giao vận /ip4, /ip6, /dns4, /dns6, /dns, /dnsaddr; giao thức /tcp hoặc /udp; nâng cấp tùy chọn /quic-v1, /quic, /ws, /wss, /http, /https, /webtransport, /webrtc-direct. Multiaddress phải kết thúc bằng /p2p/<peerId>. Giới hạn: tối đa 5 gợi ý mỗi lần ghim.

Lấy multiaddress của node bạn

Trên peer bạn muốn ghim từ đó, chạy ipfs id và sao chép bất kỳ mục nào trong Addresses kết thúc bằng /p2p/<PeerID>. Ưu tiên các địa chỉ có thể định tuyến công khai (/ip4/YOUR_PUBLIC_IP/…) hoặc dựa trên DNS (/dnsaddr/your.domain/…) để cụm của chúng tôi có thể tiếp cận peer từ AWS.

Ghim các thư mục rất lớn

POST /pin dành cho nội dung đã tồn tại sẵn trên mạng IPFS — cụm tìm nạp DAG theo từng khối từ các peer, có thể mất vài phút đối với các thư mục có 1.000+ tệp. Trong cửa sổ tìm nạp đó, một số tệp con có thể chưa khả dụng cục bộ và các yêu cầu gateway đến chúng có thể bị hết thời gian chờ. Khi status của thư mục cha chuyển sang pinned, mọi tệp con đều khả dụng cục bộ và có thể truy cập qua gateway của bạn.

Nếu bạn có các tệp cục bộ (thay vì chỉ có CID), hãy ưu tiên nhập CAR cho các bộ sưu tập NFT hoặc tập dữ liệu lớn — nó tải toàn bộ DAG lên IPFS Ninja trong một yêu cầu nguyên tử duy nhất, nên không có cửa sổ tìm nạp và không có trạng thái ghim một phần. Tạo một CAR bằng:

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

Sau đó nhập nó qua POST /upload/new với car: true.

TIP

Ghim là bất đồng bộ. Phản hồi trả về ngay lập tức với trạng thái pinning. Thăm dò endpoint trạng thái để kiểm tra khi ghim hoàn tất.

Kiểm tra Trạng thái Ghim

GET /pin/:cid

Tham số	Kiểu	Bắt buộc	Mô tả
cid	string	Có	CID bạn đang kiểm tra.

Phản hồi 200 OK

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

Giá trị trạng thái

Trạng thái	Ý nghĩa
pinning	Nội dung đang được tìm nạp từ mạng IPFS. Thăm dò lại sau vài giây.
pinned	Nội dung đã được ghim và khả dụng qua tài khoản và gateway.
failed	Không tìm thấy nội dung trên mạng IPFS. CID có thể không hợp lệ hoặc nội dung không còn khả dụng.

Cách ghim hoạt động

1. Bạn gửi CID qua POST /pin
2. Cụm IPFS tìm kiếm trên mạng các nút có nội dung
3. Cụm tải xuống và ghim nội dung cục bộ
4. Sau khi ghim, tệp xuất hiện trong danh sách tệp và có thể truy cập qua gateway
5. Mức sử dụng dung lượng được ghi nhận khi ghim hoàn tất

WARNING

Thời gian ghim phụ thuộc vào kích thước tệp và tính khả dụng trên mạng. Các tệp nhỏ thường được ghim trong vài giây. Tệp lớn hoặc nội dung hiếm khi được ghim có thể mất vài phút.

Dung lượng lưu trữ

Nội dung đã ghim được tính vào giới hạn lưu trữ của gói. Kích thước tệp được ghi nhận khi ghim hoàn tất. Nếu bạn tiến gần đến giới hạn lưu trữ, bạn có thể giải phóng dung lượng bằng cách xóa các tệp không dùng đến hoặc nâng cấp để có thêm dung lượng.