빠른 시작

2분 이내에 첫 번째 파일을 IPFS에 업로드하세요.

1. API 키 받기

Google 계정으로 ipfs.ninja에 가입하세요. 기본 API 키가 자동으로 생성됩니다. 프로필 페이지에서 API 키를 확인하고 관리하세요.

WARNING

참고: API 키는 만료되지 않습니다. 여러 개의 키를 생성하고 프로필 페이지에서 개별적으로 폐기할 수 있습니다.

2. 파일 업로드

/upload/new에 콘텐츠를 포함하여 POST 요청을 보내세요. 다음은 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

새 업로드는 IPIP-0499에 따라 최신 CIDv1(작은 단일 블록 콘텐츠는 bafk…, 더 큰 파일 및 디렉터리는 bafy…)을 생성합니다. 이전 업로드의 레거시 Qm… CID도 어디서든 계속 해석됩니다 — 두 형식 모두 모든 엔드포인트의 입력값으로 작동합니다.

API는 CID, 파일 크기, 접근 URI를 반환합니다:

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

3. 파일 조회

두 가지 방법으로 파일에 접근할 수 있습니다:

IPFS 게이트웨이를 통해 (인증 불필요)

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

TIP

apex 게이트웨이 https://ipfs.ninja/ipfs/<CID>는 모든 IPFS Ninja 사용자가 업로드하거나 고정한 CID를 제공합니다. 플랫폼에 알려지지 않은 CID는 HTTP 410 Gone을 반환합니다 — 이러한 경우 공개 게이트웨이(ipfs.io, dweb.link)를 사용하거나 먼저 CID를 계정에 POST /pin하세요.

API를 통해 (파일 메타데이터 반환)

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

응답:

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

대안: AWS SDK 사용 (S3 호환)

이미 S3를 사용 중이신가요? 기존 AWS SDK를 https://s3.ipfs.ninja로 지정하고 API 키를 자격 증명으로 사용하세요:

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" })
}));

Python, Go 및 마이그레이션 예제를 포함한 전체 문서는 S3 호환성을 참조하세요.

클릭으로 하고 싶으신가요? 대시보드를 사용하세요

코드를 작성하고 싶지 않다면, ipfs.ninja/upload에서 다음을 위한 드래그 앤 드롭을 지원합니다:

• 모든 파일 — 업로드 영역에 드롭하면 피닝되고 CID를 받습니다
• 폴더 — 브라우저에서 UnixFS 디렉터리로 패키징되어 단일 가져오기로 업로드되며, 모든 자식 파일에 대해 /ipfs/{cid}/{subpath}에서 해석됩니다
• .car 아카이브 — 자동 감지되며, 루트 CID가 정확히 보존됩니다 (CAR 가져오기 참조)

업로드 후 파일은 파일 페이지에 표시되며, 여기서 이름 변경, 폴더 간 이동, 폴더 전체에 대한 IPFS 디렉터리 CID 얻기(스냅샷), 브라우저 SDK 접근을 위한 버킷별 S3 CORS 구성을 할 수 있습니다.

다음 단계

• API 레퍼런스 — 모든 엔드포인트, 매개변수, 오류 코드에 대한 전체 문서입니다.
• S3 호환성 — AWS SDK를 사용하여 IPFS Ninja와 상호작용하세요.
• 전용 게이트웨이 — 자신의 파일만 제공하는 프라이빗 게이트웨이를 받으세요.