Сумісність з S3

Використовуйте AWS SDK для завантаження, скачування та керування файлами на IPFS Ninja з тим самим кодом, який ви використовуєте для Amazon S3.

Endpoint

https://s3.ipfs.ninja

Облікові дані

S3 API використовує ваш API-ключ IPFS Ninja для автентифікації. Ваш API-ключ слугує одночасно ключем доступу та секретним ключем.

Як отримати облікові дані

1. Перейдіть до Dashboard > API Keys
2. Натисніть Create API key та задайте назву (наприклад, "S3 доступ")
3. Негайно скопіюйте повний ключ — він показується лише один раз і не може бути відновлений пізніше

Ваш ключ виглядає так:

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

Відповідність параметрам AWS

Параметр AWS	Значення	Приклад
accessKeyId	Перші 12 символів вашого API-ключа	bws_628bba35
secretAccessKey	Повний API-ключ (усі 36 символів)	bws_628bba35e9e0079d9ff9c392b1b55a7b
region	Завжди us-east-1	us-east-1

WARNING

Повний API-ключ показується лише один раз під час створення. Якщо ви його втратите, видаліть ключ і створіть новий на сторінці API Keys.

Швидкий старт

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'и = Папки

S3 bucket'и відповідають вашим папкам IPFS Ninja. Коли ви завантажуєте файл у bucket, він зберігається у відповідній папці. Коли ви переглядаєте об'єкти в bucket'і, ви бачите файли в цій папці.

Операція S3	Еквівалент IPFS Ninja
CreateBucket	Створити нову папку
ListBuckets	Показати ваші папки
DeleteBucket	Видалити папку та всі файли в ній
PutObject у bucket	Завантажити файл у папку
ListObjectsV2 у bucket'і	Показати файли в папці

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

Папки, створені через S3 API, є тими самими папками, що відображаються у вашому Dashboard. Ви можете організовувати файли через S3 API, REST API або веб-інтерфейс — усі вони використовують одну й ту саму систему папок.

INFO

На відміну від Amazon S3, папки IPFS Ninja за замовчуванням плоскі. Для створення вкладених структур використовуйте endpoint'и папок REST API з parentFolderId. Через S3 API використовуйте префікси ключів (наприклад, images/photo.png) для організації всередині папки.

Підтримувані операції

PutObject

Завантажте файл в IPFS. Файл закріплюється, проходить перевірку безпеки, а CID повертається у заголовках ETag та 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

Скачайте файл за його ключем (ім'ям файлу) або 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

Отримайте метадані файлу без скачування вмісту.

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

Відкріпіть файл з IPFS та видаліть його з вашого облікового запису.

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

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

ListObjectsV2

Перегляньте файли в bucket'і з необов'язковою фільтрацією за префіксом та пагінацією.

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

Завантажуйте великі файли (до 5 ГБ) за допомогою multipart upload. AWS SDK обробляє це автоматично:

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

Або керуйте частинами вручну:

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

Приклад 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())

Приклад 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!")
}

Відмінності від Amazon S3

Функція	Amazon S3	IPFS Ninja S3
Модель зберігання	Змінювані об'єкти	Адресація за вмістом (незмінні CID)
Поведінка перезапису	Замінює об'єкт на місці	Створює новий CID, старий CID залишається доступним
Версіонування	Підтримується	Не підтримується (використовуйте CID для версіонування)
Шифрування на стороні сервера	Підтримується	Не підтримується (вміст знаходиться в IPFS)
Політики життєвого циклу	Підтримуються	Не підтримуються
Політики bucket'ів / ACL	Підтримуються	Використовуйте режими доступу gateway
Попередньо підписані URL	Підтримуються	Використовуйте підписані токени завантаження
Максимальний розмір об'єкта	5 ТБ	5 ГБ (multipart), 100 МБ (одиночний PUT)
Регіони	Мультирегіональний	Лише us-east-1
Значення ETag	MD5 hash	IPFS CID
Додаткові заголовки	Стандартні S3	x-amz-meta-cid (IPFS CID)

Міграція з Amazon S3

Замініть конфігурацію вашого S3-клієнта:

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

Ваші існуючі виклики PutObject, GetObject, ListObjectsV2 та DeleteObject працюють без змін.

Міграція з Filebase

Замініть 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
 });