파일

IPFS에서 파일을 업로드, 목록 조회, 검색하세요.

파일 업로드

POST /upload/new

모든 파일을 IPFS에 업로드합니다. 파일은 피닝되며 영구 CID가 반환됩니다.

요청 본문

매개변수	유형	필수	설명
content	string | object	예	JSON 객체/배열, 또는 base64 인코딩된 파일 데이터 (이미지, PDF, HTML 또는 모든 파일 유형). CAR 가져오기의 경우 base64 인코딩된 CAR 파일.
car	boolean	아니요	CAR 파일(DAG 가져오기)을 가져오려면 true로 설정하세요. 정확한 CID를 보존합니다.
description	string	아니요	업로드된 콘텐츠에 대한 간단한 설명.
metadata	object	아니요	파일에 첨부할 사용자 정의 키-값 쌍. 최대 10개 키. 키는 영숫자 또는 밑줄이어야 하며 1-64자. 값은 문자열이어야 하며 각 최대 256자. 메타데이터 총 크기는 4 KB를 초과할 수 없습니다.

요청 예시

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

이미지 업로드 (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"
  })
});

응답 200 OK

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

기본값은 CIDv1

새 업로드는 IPIP-0499 unixfs-v1-2025 프로필에 따라 최신 CIDv1(작은 단일 블록 콘텐츠는 bafk…, 더 큰 파일 및 디렉터리는 bafy…)을 반환합니다 — raw leaves를 사용하는 1 MiB 청크. 이전 업로드의 레거시 Qm… CID는 계속 완전히 해석 가능하며 모든 엔드포인트에서 계속 작동합니다.

대시보드 대안

대시보드의 /upload 페이지는 파일, 폴더(브라우저에서 UnixFS 디렉터리로 패키징됨), .car 아카이브에 대한 드래그 앤 드롭을 지원하며 — 모두 동일한 엔드포인트를 통해 라우팅됩니다. CAR 경로에 대한 자세한 내용은 CAR 가져오기를 참조하세요.

파일 이름 변경

PUT /files/:cid/name

파일에 표시되는 이름을 업데이트합니다. CID는 변경되지 않습니다 — 콘텐츠의 해시이기 때문입니다 — 파일 목록에 표시되는 라벨만 변경됩니다.

요청 본문

매개변수	유형	필수	설명
name	string	예	새 표시 이름. 1-200자. 경로 구분자(/, \)를 포함할 수 없습니다. 공백만으로 구성된 이름은 거부됩니다.

요청 예시

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

응답 200 OK

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

대시보드

파일 페이지에는 각 파일 행의 작업 메뉴(점 세 개 버튼)에 이름 변경 항목이 있습니다. 동일한 효과를 코드 없이 얻을 수 있습니다.

파일 목록 조회

GET /upload/list

지정된 시간 범위 내의 업로드된 IPFS 파일 목록을 조회합니다.

쿼리 매개변수

매개변수	유형	필수	설명
from	number	예	시간 범위 시작, Unix 타임스탬프 (밀리초).
to	number	예	시간 범위 종료, Unix 타임스탬프 (밀리초).

요청 예시

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

응답 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"
    }
  }
]

파일 조회

GET /file/:cid

CID로 특정 업로드된 파일의 메타데이터를 조회합니다.

경로 매개변수

매개변수	유형	필수	설명
cid	string	예	파일의 IPFS 콘텐츠 식별자.

요청 예시

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

응답 200 OK

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