Compatibilidade S3

Use o AWS SDK para fazer upload, download e gerenciar arquivos no IPFS Ninja com o mesmo codigo que voce usa para o Amazon S3.

Endpoint

https://s3.ipfs.ninja

Credenciais

A API S3 usa sua chave de API do IPFS Ninja para autenticacao. Sua chave de API serve tanto como access key quanto como secret key.

Como obter suas credenciais

1. Acesse Dashboard > API Keys
2. Clique em Create API key e de um nome (ex: "S3 access")
3. Copie a chave completa imediatamente — ela e exibida apenas uma vez e nao pode ser recuperada depois

Sua chave tem este formato:

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

Mapeamento para credenciais AWS

Parametro AWS	Valor	Exemplo
accessKeyId	Primeiros 12 caracteres da sua chave de API	bws_628bba35
secretAccessKey	A chave de API completa (todos os 36 caracteres)	bws_628bba35e9e0079d9ff9c392b1b55a7b
region	Sempre us-east-1	us-east-1

WARNING

A chave de API completa e exibida apenas uma vez quando voce a cria. Se voce a perder, exclua a chave e crie uma nova na pagina de API Keys.

Inicio Rapido

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

Buckets = Pastas

Buckets S3 correspondem as suas pastas no IPFS Ninja. Quando voce faz upload de um arquivo para um bucket, ele e armazenado na pasta correspondente. Quando voce lista objetos em um bucket, voce ve os arquivos nessa pasta.

Operacao S3	Equivalente no IPFS Ninja
CreateBucket	Criar uma nova pasta
ListBuckets	Listar suas pastas
DeleteBucket	Excluir uma pasta e todos os arquivos nela
PutObject no bucket	Fazer upload do arquivo na pasta
ListObjectsV2 no bucket	Listar arquivos na pasta

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

As pastas criadas pela API S3 sao as mesmas pastas visiveis no seu Dashboard. Voce pode organizar arquivos tanto pela API S3, quanto pela API REST, ou pela interface web — todos compartilham o mesmo sistema de pastas.

INFO

Diferente do Amazon S3, as pastas do IPFS Ninja sao planas por padrao. Para criar estruturas aninhadas, use os endpoints de pastas da API REST com parentFolderId. Pela API S3, use prefixos nas chaves (ex: images/photo.png) para organizar dentro de uma pasta.

Operacoes Suportadas

PutObject

Faz upload de um arquivo para o IPFS. O arquivo e fixado (pinned), passa por verificacao de seguranca, e o CID e retornado nos headers ETag e 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

Baixa um arquivo pela sua chave (nome do arquivo) ou 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

Obtem os metadados do arquivo sem baixar o conteudo.

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

Remove a fixacao (unpin) de um arquivo do IPFS e o exclui da sua conta.

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

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

ListObjectsV2

Lista arquivos em um bucket com filtragem opcional por prefixo e paginacao.

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

Faca upload de arquivos grandes (ate 5 GB) usando multipart upload. O AWS SDK lida com isso automaticamente:

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

Ou controle as partes manualmente:

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

Exemplo em 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())

Exemplo em 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!")
}

Diferencas em relacao ao Amazon S3

Recurso	Amazon S3	IPFS Ninja S3
Modelo de armazenamento	Objetos mutaveis	Enderecamento por conteudo (CIDs imutaveis)
Comportamento de sobrescrita	Substitui o objeto no lugar	Cria novo CID, o CID antigo continua acessivel
Versionamento	Suportado	Nao suportado (use CIDs para versionamento)
Criptografia no servidor	Suportada	Nao suportada (conteudo esta no IPFS)
Politicas de ciclo de vida	Suportadas	Nao suportadas
Politicas de bucket / ACLs	Suportadas	Use modos de acesso do gateway
URLs pre-assinadas	Suportadas	Use tokens de upload assinados
Tamanho maximo do objeto	5 TB	5 GB (multipart), 100 MB (PUT unico)
Regioes	Multi-regiao	Apenas us-east-1
Valor do ETag	Hash MD5	IPFS CID
Headers extras	S3 padrao	x-amz-meta-cid (IPFS CID)

Migrando do Amazon S3

Substitua a configuracao do seu cliente 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
 });

Suas chamadas existentes de PutObject, GetObject, ListObjectsV2 e DeleteObject funcionam sem alteracoes.

Migrando do Filebase

Substitua a URL do 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
 });