Bắt đầu nhanh

Tải lên tệp đầu tiên của bạn lên IPFS trong vòng chưa đầy hai phút.

1. Lấy khóa API của bạn

Đăng ký tại ipfs.ninja bằng tài khoản Google của bạn. Một khóa API mặc định sẽ được tạo tự động. Truy cập trang Hồ sơ của bạn để xem và quản lý các khóa API.

WARNING

Lưu ý: Khóa API không hết hạn. Bạn có thể tạo nhiều khóa và thu hồi chúng riêng lẻ từ trang Hồ sơ.

2. Tải lên tệp

Gửi yêu cầu POST đến /upload/new với nội dung của bạn. Đây là ví dụ tải lên một đối tượng JSON:

curl

curl -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "name": "My NFT",
      "description": "A permanent file on IPFS",
      "image": "ipfs://bafybeiExampleCID..."
    },
    "description": "NFT metadata"
  }'

JavaScript

const response = await fetch("https://api.ipfs.ninja/upload/new", {
  method: "POST",
  headers: {
    "X-Api-Key": "bws_your_api_key_here",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    content: {
      name: "My NFT",
      description: "A permanent file on IPFS",
      image: "ipfs://bafybeiExampleCID..."
    },
    description: "NFT metadata"
  })
});

const data = await response.json();
console.log(data.cid);       // "bafybeigdyrzt5..."
console.log(data.uris.url);  // "https://ipfs.ninja/ipfs/bafybeigdyrzt5..."

CIDv1 theo mặc định

Các lần tải lên mới tạo ra CIDv1 hiện đại (bafk… cho nội dung nhỏ dạng một khối, bafy… cho các tệp và thư mục lớn hơn) theo IPIP-0499. Các CID Qm… cũ từ các lần tải lên trước đó vẫn phân giải ở mọi nơi — cả hai định dạng đều hoạt động làm đầu vào cho mọi endpoint.

API trả về CID, kích thước tệp và URI truy cập:

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "sizeMB": 0.001,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

3. Truy xuất tệp của bạn

Truy cập tệp của bạn theo hai cách:

Qua gateway IPFS (công khai, không cần xác thực)

curl https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

TIP

Cổng apex https://ipfs.ninja/ipfs/<CID> phục vụ các CID được tải lên hoặc ghim bởi bất kỳ người dùng IPFS Ninja nào. Các CID không xác định đối với nền tảng trả về HTTP 410 Gone — đối với những CID đó, hãy sử dụng cổng công cộng (ipfs.io, dweb.link) hoặc thực hiện POST /pin CID vào tài khoản của bạn trước.

Qua API (trả về siêu dữ liệu tệp)

curl https://api.ipfs.ninja/file/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi \
  -H "X-Api-Key: bws_your_api_key_here"

Phản hồi:

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "fileName": "NFT metadata",
  "fileType": "json",
  "sizeMB": 0.001,
  "createdAt": 1711036800000,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

Lựa chọn khác: Dùng AWS SDK (tương thích S3)

Đã dùng S3? Trỏ AWS SDK hiện có của bạn đến https://s3.ipfs.ninja và dùng khóa API của bạn làm thông tin xác thực:

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";

const s3 = new S3Client({
  endpoint: "https://s3.ipfs.ninja",
  credentials: { accessKeyId: "bws_prefix", secretAccessKey: "bws_fullkey" },
  region: "us-east-1",
  forcePathStyle: true
});

await s3.send(new PutObjectCommand({
  Bucket: "my-project",
  Key: "my-file.json",
  Body: JSON.stringify({ hello: "IPFS" })
}));

Xem Tương thích S3 để biết tài liệu đầy đủ với ví dụ Python, Go và hướng dẫn di chuyển.

Thích thao tác bằng chuột hơn? Dùng Bảng điều khiển

Nếu bạn không muốn viết mã, ipfs.ninja/upload chấp nhận kéo-và-thả cho:

• Bất kỳ tệp nào — thả nó vào vùng tải lên, được ghim + bạn nhận CID
• Một thư mục — được đóng gói thành một thư mục UnixFS ngay trong trình duyệt của bạn, tải lên như một lần nhập duy nhất, phân giải tại /ipfs/{cid}/{subpath} cho mỗi tệp con
• Một kho lưu trữ .car — tự động phát hiện, CID gốc được giữ nguyên chính xác (xem Nhập CAR)

Sau khi tải lên, các tệp xuất hiện trên trang Tệp, nơi bạn có thể đổi tên, di chuyển giữa các thư mục, lấy một CID thư mục IPFS cho toàn bộ thư mục (chụp nhanh), và cấu hình S3 CORS theo từng bucket để tích hợp SDK trình duyệt.

Bước tiếp theo

• Tham chiếu API — Tài liệu đầy đủ cho tất cả các endpoint, tham số và mã lỗi.
• Tương thích S3 — Dùng AWS SDK để tương tác với IPFS Ninja.
• Gateway Chuyên dụng — Nhận gateway riêng tư chỉ phục vụ tệp của bạn.