Kompatibilitas S3

Gunakan AWS SDK untuk mengunggah, mengunduh, dan mengelola file di IPFS Ninja dengan kode yang sama seperti yang Anda gunakan untuk Amazon S3.

Endpoint

https://s3.ipfs.ninja

Kredensial

API S3 menggunakan kunci API IPFS Ninja Anda untuk autentikasi. Kunci API Anda berfungsi sebagai access key sekaligus secret key.

Cara mendapatkan kredensial Anda

1. Buka Dashboard > API Keys
2. Klik Create API key dan beri nama (misal "S3 access")
3. Salin kunci lengkap segera — kunci hanya ditampilkan sekali dan tidak dapat diambil kembali

Kunci Anda terlihat seperti ini:

bws_628bba35e9e0079d9ff9c392b1b55a7b
├──────────┘└──────────────────────────┘
 prefix (12 chars)    rest of key

Pemetaan ke kredensial AWS

Parameter AWS	Nilai	Contoh
accessKeyId	12 karakter pertama dari kunci API Anda	bws_628bba35
secretAccessKey	Kunci API lengkap (semua 36 karakter)	bws_628bba35e9e0079d9ff9c392b1b55a7b
region	Selalu us-east-1	us-east-1

WARNING

Kunci API lengkap hanya ditampilkan sekali saat Anda membuatnya. Jika Anda kehilangan kunci, hapus kunci tersebut dan buat yang baru dari halaman API Keys.

Mulai Cepat

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

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

// Upload a file
const put = await s3.send(new PutObjectCommand({
  Bucket: "my-project",
  Key: "hello.json",
  Body: JSON.stringify({ hello: "IPFS" }),
  ContentType: "application/json"
}));

console.log("CID:", put.Metadata?.cid);
// CID: QmXnnyufdzAWL5CqZ2RnSNgPbvCc1ALT73s6epPrRnZ1Xy

Bucket = Folder

Bucket S3 dipetakan ke folder IPFS Ninja Anda. Saat Anda mengunggah file ke bucket, file tersebut disimpan di folder yang sesuai. Saat Anda melihat daftar objek di bucket, Anda melihat file-file di folder tersebut.

Operasi S3	Padanan IPFS Ninja
CreateBucket	Membuat folder baru
ListBuckets	Melihat daftar folder Anda
DeleteBucket	Menghapus folder beserta semua file di dalamnya
PutObject ke bucket	Mengunggah file ke dalam folder
ListObjectsV2 pada bucket	Melihat daftar file di folder

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

// Create a bucket (= create a folder)
await s3.send(new CreateBucketCommand({ Bucket: "nft-metadata" }));

// Upload a file into the folder
await s3.send(new PutObjectCommand({
  Bucket: "nft-metadata",      // ← folder name
  Key: "token-42.json",        // ← filename within the folder
  Body: JSON.stringify({ name: "My NFT #42" })
}));

// List buckets (= list your folders)
const { Buckets } = await s3.send(new ListBucketsCommand({}));
console.log(Buckets);
// [{ Name: "nft-metadata", CreationDate: "2026-04-13T..." }]

TIP

Folder yang dibuat melalui API S3 adalah folder yang sama yang terlihat di Dashboard Anda. Anda dapat mengatur file dari API S3, REST API, atau antarmuka web — semuanya berbagi sistem folder yang sama.

INFO

Berbeda dengan Amazon S3, folder IPFS Ninja bersifat datar secara default. Untuk membuat struktur bersarang, gunakan endpoint folder di REST API dengan parentFolderId. Dari API S3, gunakan prefix key (misal images/photo.png) untuk mengatur file di dalam folder.

Operasi yang Didukung

PutObject

Mengunggah file ke IPFS. File akan di-pin, dipindai keamanan, dan CID dikembalikan di header ETag dan x-amz-meta-cid.

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

const result = await s3.send(new PutObjectCommand({
  Bucket: "my-project",
  Key: "photo.png",
  Body: fs.readFileSync("photo.png"),
  ContentType: "image/png"
}));

console.log("CID:", result.ETag);

# curl equivalent
curl -X PUT "https://s3.ipfs.ninja/my-project/photo.png" \
  --data-binary @photo.png \
  -H "Content-Type: image/png" \
  --aws-sigv4 "aws:amz:us-east-1:s3" \
  --user "bws_628bba35:bws_628bba35e9e0079d9ff9c392b1b55a7b"

GetObject

Mengunduh file berdasarkan key (nama file) atau CID.

import { GetObjectCommand } from "@aws-sdk/client-s3";

const result = await s3.send(new GetObjectCommand({
  Bucket: "my-project",
  Key: "photo.png"
}));

const body = await result.Body.transformToByteArray();
console.log("Size:", body.length);
console.log("CID:", result.Metadata?.cid);

HeadObject

Mendapatkan metadata file tanpa mengunduh kontennya.

import { HeadObjectCommand } from "@aws-sdk/client-s3";

const head = await s3.send(new HeadObjectCommand({
  Bucket: "my-project",
  Key: "photo.png"
}));

console.log("Size:", head.ContentLength);
console.log("Type:", head.ContentType);
console.log("CID:", head.Metadata?.cid);

DeleteObject

Melepas pin file dari IPFS dan menghapusnya dari akun Anda.

import { DeleteObjectCommand } from "@aws-sdk/client-s3";

await s3.send(new DeleteObjectCommand({
  Bucket: "my-project",
  Key: "photo.png"
}));

ListObjectsV2

Melihat daftar file di bucket dengan filter prefix opsional dan paginasi.

import { ListObjectsV2Command } from "@aws-sdk/client-s3";

const list = await s3.send(new ListObjectsV2Command({
  Bucket: "my-project",
  Prefix: "images/",
  MaxKeys: 100
}));

for (const obj of list.Contents ?? []) {
  console.log(obj.Key, obj.Size, obj.ETag); // ETag = CID
}

Multipart Upload

Mengunggah file besar (hingga 5 GB) menggunakan multipart upload. AWS SDK menangani ini secara otomatis:

import { Upload } from "@aws-sdk/lib-storage";
import fs from "fs";

const upload = new Upload({
  client: s3,
  params: {
    Bucket: "my-project",
    Key: "large-dataset.tar.gz",
    Body: fs.createReadStream("large-dataset.tar.gz"),
    ContentType: "application/gzip"
  },
  partSize: 10 * 1024 * 1024, // 10 MB per part
});

upload.on("httpUploadProgress", (progress) => {
  console.log(`Uploaded ${progress.loaded} of ${progress.total} bytes`);
});

const result = await upload.done();
console.log("CID:", result.ETag);

Atau kontrol bagian secara manual:

import {
  CreateMultipartUploadCommand,
  UploadPartCommand,
  CompleteMultipartUploadCommand
} from "@aws-sdk/client-s3";

// 1. Start
const { UploadId } = await s3.send(new CreateMultipartUploadCommand({
  Bucket: "my-project",
  Key: "big-file.bin"
}));

// 2. Upload parts
const part1 = await s3.send(new UploadPartCommand({
  Bucket: "my-project",
  Key: "big-file.bin",
  UploadId,
  PartNumber: 1,
  Body: chunk1
}));

// 3. Complete
const result = await s3.send(new CompleteMultipartUploadCommand({
  Bucket: "my-project",
  Key: "big-file.bin",
  UploadId,
  MultipartUpload: {
    Parts: [{ PartNumber: 1, ETag: part1.ETag }]
  }
}));

Contoh Python

import boto3

s3 = boto3.client(
    "s3",
    endpoint_url="https://s3.ipfs.ninja",
    aws_access_key_id="bws_628bba35",
    aws_secret_access_key="bws_628bba35e9e0079d9ff9c392b1b55a7b",
    region_name="us-east-1"
)

# Upload
s3.put_object(
    Bucket="my-project",
    Key="data.json",
    Body=b'{"hello": "IPFS"}',
    ContentType="application/json"
)

# List files
response = s3.list_objects_v2(Bucket="my-project")
for obj in response.get("Contents", []):
    print(obj["Key"], obj["Size"])

# Download
result = s3.get_object(Bucket="my-project", Key="data.json")
print(result["Body"].read())

Contoh Go

package main

import (
    "context"
    "fmt"
    "strings"

    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/credentials"
    "github.com/aws/aws-sdk-go-v2/service/s3"
)

func main() {
    client := s3.New(s3.Options{
        BaseEndpoint: aws.String("https://s3.ipfs.ninja"),
        Region:       "us-east-1",
        Credentials:  credentials.NewStaticCredentialsProvider("bws_628bba35", "bws_628bba35e9e0...", ""),
        UsePathStyle: true,
    })

    _, err := client.PutObject(context.TODO(), &s3.PutObjectInput{
        Bucket:      aws.String("my-project"),
        Key:         aws.String("hello.txt"),
        Body:        strings.NewReader("Hello, IPFS!"),
        ContentType: aws.String("text/plain"),
    })
    if err != nil {
        panic(err)
    }
    fmt.Println("Uploaded!")
}

Perbedaan dengan Amazon S3

Fitur	Amazon S3	IPFS Ninja S3
Model penyimpanan	Objek yang bisa diubah	Content-addressed (CID yang tidak dapat diubah)
Perilaku overwrite	Mengganti objek di tempat	Membuat CID baru, CID lama tetap dapat diakses
Versioning	Didukung	Tidak didukung (gunakan CID untuk versioning)
Enkripsi sisi server	Didukung	Tidak didukung (konten ada di IPFS)
Lifecycle policies	Didukung	Tidak didukung
Bucket policies / ACL	Didukung	Gunakan mode akses gateway
Presigned URL	Didukung	Gunakan signed upload token
Ukuran objek maksimum	5 TB	5 GB (multipart), 100 MB (single PUT)
Region	Multi-region	Hanya us-east-1
Nilai ETag	Hash MD5	IPFS CID
Header tambahan	S3 standar	x-amz-meta-cid (IPFS CID)

Migrasi dari Amazon S3

Ganti konfigurasi klien S3 Anda:

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

Panggilan PutObject, GetObject, ListObjectsV2, dan DeleteObject yang sudah ada tetap berfungsi tanpa perubahan.

Migrasi dari Filebase

Ganti URL endpoint:

 const s3 = new S3Client({
-  endpoint: "https://s3.filebase.com",
+  endpoint: "https://s3.ipfs.ninja",
   credentials: {
-    accessKeyId: "FILEBASE_KEY",
-    secretAccessKey: "FILEBASE_SECRET"
+    accessKeyId: "bws_628bba35",
+    secretAccessKey: "bws_628bba35e9e0..."
   },
   region: "us-east-1",
   forcePathStyle: true
 });