Tệp

Tải lên, liệt kê và truy xuất tệp trên IPFS. Xem xác thực để thiết lập khóa API, và xử lý lỗi để biết các mã trạng thái HTTP.

Tải file lên IPFS: 3 bước

POST /upload/new

1. Mã hóa tệp của bạn dạng base64 (đối với hình ảnh/PDF) hoặc truyền trực tiếp một đối tượng JSON.
2. Gửi POST đến /upload/new với khóa API của bạn trong tiêu đề X-Api-Key.
3. Lưu lại cid được trả về -- đây là mã định danh vĩnh viễn cho tệp của bạn trên IPFS.

Tải lên bất kỳ tệp nào lên IPFS. Tệp được ghim và một CID vĩnh viễn được trả về.

Nội dung yêu cầu

Tham số	Kiểu	Bắt buộc	Mô tả
content	string | object	Có	Đối tượng/mảng JSON, hoặc dữ liệu tệp mã hóa base64 (hình ảnh, PDF, HTML, hoặc bất kỳ loại tệp nào). Đối với nhập CAR, dữ liệu tệp CAR mã hóa base64.
car	boolean	Không	Đặt thành true để nhập một tệp CAR (nhập DAG). Giữ nguyên chính xác các CID.
description	string	Không	Mô tả ngắn về nội dung đã tải lên.
metadata	object	Không	Cặp khóa-giá trị tùy chỉnh để đính kèm vào tệp. 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ự mỗi giá trị. Tổng kích thước siêu dữ liệu không được vượt quá 4 KB.

Ví dụ yêu cầu

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": "example", "value": 42 },
    "description": "Test upload",
    "metadata": {
      "project": "my-app",
      "environment": "production"
    }
  }'

Tải lên hình ảnh (base64)

const fs = require("fs");
const image = fs.readFileSync("photo.png").toString("base64");

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: image,
    description: "Profile photo"
  })
});

Phản hồi 200 OK

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

CIDv1 theo mặc định

Các lần tải lên mới trả về 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 hồ sơ IPIP-0499 unixfs-v1-2025 — các khối 1 MiB với raw leaves. Các CID Qm… cũ từ các lần tải lên trước đó vẫn hoàn toàn có thể phân giải và tiếp tục hoạt động với mọi endpoint.

Lựa chọn thay thế trên bảng điều khiển

Trang /upload của bảng điều khiển chấp nhận kéo-và-thả cho tệp, thư mục (được đóng gói thành một thư mục UnixFS ngay trong trình duyệt), và kho lưu trữ .car — tất cả đều đi qua cùng endpoint này. Xem Nhập CAR để biết chi tiết về luồng CAR.

Các loại tệp được hỗ trợ

API chấp nhận trực tiếp đối tượng và mảng JSON, cùng với dữ liệu nhị phân mã hóa base64: hình ảnh (JPEG, PNG, GIF, WebP), PDF, HTML và bất kỳ loại tệp nào khác. Máy chủ tự động phát hiện loại nội dung từ dữ liệu gửi lên.

Các trường trong phản hồi

cid trong phản hồi là mã định danh nội dung IPFS vĩnh viễn. sizeMB là kích thước lưu trữ tính bằng megabyte. Đối tượng uris chứa cả URI gốc ipfs:// và URL gateway HTTPS để truy cập qua trình duyệt.

Đổi tên một Tệp

PUT /files/:cid/name

Cập nhật tên hiển thị của một tệp. CID không thay đổi — nó là một hàm băm của nội dung — chỉ nhãn bạn thấy trong danh sách tệp thay đổi.

Nội dung yêu cầu

Tham số	Kiểu	Bắt buộc	Mô tả
name	string	Có	Tên hiển thị mới. 1-200 ký tự. Không được chứa ký tự phân tách đường dẫn (/, \). Tên chỉ chứa khoảng trắng sẽ bị từ chối.

Ví dụ yêu cầu

curl -X PUT https://api.ipfs.ninja/files/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/name \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Season 1 promo art" }'

Phản hồi 200 OK

{
  "success": true,
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "name": "Season 1 promo art"
}

Bảng điều khiển

Trang Tệp có mục Đổi tên trong menu hành động của mỗi hàng tệp (nút ba chấm). Cùng hiệu quả, không cần viết mã.

Liệt kê Tệp

GET /upload/list

Truy xuất danh sách các tệp IPFS đã tải lên trong khoảng thời gian.

Tham số truy vấn

Tham số	Kiểu	Bắt buộc	Mô tả
from	number	Có	Bắt đầu khoảng thời gian, dấu thời gian Unix tính bằng mili giây.
to	number	Có	Kết thúc khoảng thời gian, dấu thời gian Unix tính bằng mili giây.

Ví dụ yêu cầu

curl "https://api.ipfs.ninja/upload/list?from=1704067200000&to=1735689600000" \
  -H "X-Api-Key: bws_your_api_key_here"

Phản hồi 200 OK

[
  {
    "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "fileName": "Test upload",
    "fileType": "json",
    "sizeMB": 0.001,
    "createdAt": 1711036800000,
    "metadata": {
      "project": "my-app",
      "environment": "production"
    },
    "uris": {
      "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
      "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
    }
  }
]

Lấy Tệp

GET /file/:cid

Truy xuất siêu dữ liệu cho một tệp đã tải lên cụ thể theo CID.

Tham số đường dẫn

Tham số	Kiểu	Bắt buộc	Mô tả
cid	string	Có	Mã định danh nội dung IPFS của tệp.

Ví dụ yêu cầu

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

Phản hồi 200 OK

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