Compatibilidade com S3

O Blob Storage fala a API S3 em https://s3-blob.squarecloud.app. Qualquer ferramenta que permita definir um endpoint personalizado funciona: aws-cli, boto3, o AWS SDK para JavaScript, rclone, Cyberduck e a maioria das ferramentas de backup.

Credenciais

Ferramentas S3 assinam as requisições com um par de chaves de acesso. Obtenha-o em Credenciais S3:

curl https://blob.squarecloud.app/v1/s3/credentials \
  --header 'Authorization: YOUR_API_KEY'

O par é derivado da sua chave de API. Ele não precisa de gerenciamento separado: revogar ou regenerar a chave faz o mesmo com o par, e o par recebe os mesmos escopos. Uma chave com apenas blob:read gera um par somente leitura. O par não muda enquanto a chave de API não mudar, então busque-o uma vez e guarde-o no seu gerenciador de segredos ou em uma variável de ambiente. Não chame a rota a cada inicialização: ela aceita 10 requisições por hora.

Configuração	Valor
Endpoint	`https://s3-blob.squarecloud.app`
Região	`auto`
Endereçamento	Path-style (`https://s3-blob.squarecloud.app/<bucket>/<key>`)
Assinatura	AWS Signature Version 4

Buckets

A sua conta enxerga três buckets fixos. Não é possível criar nem excluir buckets.

Bucket	Conteúdo	Acesso
`public`	Arquivos públicos, servidos em `https://blob.squarecloud.dev/pub/<user_id>/<key>`	Leitura e escrita
`private`	Arquivos privados, sem URL pública	Leitura e escrita
`legacy`	Arquivos legados, enviados antes da atualização de setembro de 2026	Leitura, listagem e exclusão

Uma chave no bucket public ou private é o caminho do objeto sem o seu ID de usuário: images/logo.png no bucket public é o objeto pub/<user_id>/images/logo.png na API REST. Arquivos gravados pelo S3 aparecem na API REST e no dashboard, e vice-versa.

Configuração

aws configure set aws_access_key_id SQ2_...
aws configure set aws_secret_access_key ...
aws configure set region auto

aws s3 cp ./logo.png s3://public/images/logo.png \
  --endpoint-url https://s3-blob.squarecloud.app
aws s3 ls s3://public/images/ --endpoint-url https://s3-blob.squarecloud.app

import boto3
from botocore.config import Config

s3 = boto3.client(
    "s3",
    endpoint_url="https://s3-blob.squarecloud.app",
    aws_access_key_id="SQ2_...",
    aws_secret_access_key="...",
    region_name="auto",
    config=Config(signature_version="s3v4", s3={"addressing_style": "path"}),
)

s3.upload_file("report.pdf", "private", "reports/2026/report.pdf")
url = s3.generate_presigned_url(
    "get_object",
    Params={"Bucket": "private", "Key": "reports/2026/report.pdf"},
    ExpiresIn=3600,
)

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

const s3 = new S3Client({
  endpoint: "https://s3-blob.squarecloud.app",
  region: "auto",
  forcePathStyle: true,
  credentials: { accessKeyId: "SQ2_...", secretAccessKey: "..." },
});

await s3.send(new PutObjectCommand({
  Bucket: "public",
  Key: "images/logo.png",
  Body: buffer,
  ContentType: "image/png",
}));

[squarecloud]
type = s3
provider = Other
access_key_id = SQ2_...
secret_access_key = ...
endpoint = https://s3-blob.squarecloud.app
region = auto
force_path_style = true

O boto3 precisa de signature_version="s3v4" para URLs pré-assinadas: sem isso, o generate_presigned_url assina com o SigV2 antigo, que o gateway não aceita. URLs pré-assinadas duram até 7 dias (604800 segundos).

As respostas do gateway nunca ficam em cache no edge. Uma URL pré-assinada deixa de funcionar exatamente quando expira, quando a chave de API é revogada ou quando o objeto é excluído.

Operações suportadas

Área	Operações
Buckets	`ListBuckets`, `HeadBucket`, `GetBucketLocation`. `CreateBucket` em um bucket existente tem sucesso; `DeleteBucket` responde `BucketNotEmpty` enquanto o bucket tiver arquivos.
Listagem	`ListObjects` e `ListObjectsV2`, com `delimiter`, `prefix` e `encoding-type=url`.
Objetos	`HeadObject`, `GetObject` (com `Range`, `If-Match`, `If-None-Match`, `If-Modified-Since`), `PutObject` (até 100 MB em uma única requisição), `CopyObject` (diretivas de metadados `COPY` e `REPLACE`), `DeleteObject`, `DeleteObjects` (até 1000 chaves).
Multipart	`CreateMultipartUpload`, `UploadPart` (de 5 MB a 80 MB por parte, exceto a última), `UploadPartCopy`, `CompleteMultipartUpload`, `AbortMultipartUpload`, `ListParts`, `ListMultipartUploads`. Objetos de até 10 GiB.
Integridade	`Content-MD5` é sempre verificado, mesmo quando um cabeçalho `x-amz-checksum-*` também é enviado. `x-amz-checksum-crc32`, `-sha1` e `-sha256` também são verificados; uma divergência responde `BadDigest`. `crc32c` e `crc64nvme` são aceitos sem verificação. Corpos `aws-chunked` são suportados.
Compatibilidade	`GetBucketVersioning`, `GetBucketAcl`, `GetObjectAcl` e as leituras de tags respondem valores fixos, para que as ferramentas que as consultam continuem funcionando.

Políticas de bucket, CORS, lifecycle, website, criptografia, object lock, versões, logging, notificações, replicação, escrita de ACL e de tags, GET por partNumber e uploads por formulário POST do navegador respondem 501 NotImplemented. Use as configurações da conta para regras de lifecycle.

Chaves

As chaves são caminhos literais. Uma chave pode ter até cerca de 1000 bytes: o limite de 1024 bytes também conta o prefixo da conta. Uma chave maior responde KeyTooLongError, e a mensagem diz o número exato de bytes que você tem. Os segmentos não podem ser vazios, . ou ...
Uma chave de 0 bytes terminada em / é um marcador de pasta, do jeito que o console da AWS cria pastas.
O Content-Type servido é derivado da extensão, como na API REST. Executáveis são recusados com InvalidArgument, e .html, .svg e .xml são servidos como download.

Metadados, cache e expiração

Os cabeçalhos x-amz-meta-* são mantidos no Pro e no Enterprise (até 5 chaves e 512 bytes, caso contrário MetadataTooLarge). Nos demais planos eles são descartados.
Cache-Control e Content-Disposition são mantidos. Um Cache-Control sem cache (no-cache, no-store ou max-age=0) fora do Enterprise é recusado com AccessDenied.
As regras por prefixo se aplicam aos objetos gravados pelo S3, incluindo a exclusão automática. max_size e extensions de uma regra só se aplicam aos uploads pela API REST.

Limites

Limite	Valor
Requisições por conta, a cada 10 segundos	Hobby 100 · Standard 200 · Pro 400 · Enterprise 600
Cópias no servidor (`CopyObject`, `UploadPartCopy`)	20 a cada 10 segundos
Chaves excluídas por `DeleteObjects`	2000 a cada 10 segundos
Uploads multipart abertos	32 por conta, compartilhados com os uploads em partes da API REST
`PutObject` único	100 MB
Parte (`UploadPart`)	5 MB a 80 MB, exceto a última parte
Tamanho do objeto	10 GiB
Credenciais inválidas	Falhas demais bloqueiam o IP por alguns minutos

Acima de um limite, o gateway responde SlowDown (HTTP 503), e os SDKs da AWS esperam e tentam novamente por conta própria. As requisições S3 não contam para o limite de requisições de API do seu plano. Confira o par de chaves antes de tentar novamente em loop: um IP que envia credenciais inválidas demais fica bloqueado por alguns minutos.

Tamanho da parte

As ferramentas multipart dividem arquivos grandes por conta própria; mantenha cada parte com 80 MB ou menos. Os padrões do AWS CLI (8 MB) e do rclone (5 MB) já se encaixam.

aws configure set default.s3.multipart_chunksize 64MB

from boto3.s3.transfer import TransferConfig

config = TransferConfig(multipart_chunksize=64 * 1024 * 1024)
s3.upload_file("backup.tar.gz", "private", "backups/backup.tar.gz", Config=config)

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

await new Upload({
  client: s3,
  params: { Bucket: "private", Key: "backups/backup.tar.gz", Body: stream },
  partSize: 64 * 1024 * 1024, // até 80 MB
}).done();

Gravar exige um plano pago. Sem ele, e no bucket legacy (somente leitura), as gravações respondem AccessDenied. A cota de armazenamento se aplica como na API REST.

Erros

O gateway responde com os erros XML padrão do S3, então os SDKs os tratam nativamente:

Erro	Quando
`AccessDenied`	Sem plano pago, chave somente leitura, gravação no `legacy` ou uma opção fora do seu plano.
`NoSuchBucket`	O bucket não é `public`, `private` nem `legacy`.
`NoSuchKey`	O objeto não existe.
`InvalidArgument`	Um tipo de arquivo bloqueado (executáveis e instaladores) ou um cabeçalho malformado.
`QuotaExceeded`	A conta atingiu o armazenamento incluído.
`EntityTooLarge` / `EntityTooSmall`	Um `PutObject` acima de 100 MB, uma parte acima de 80 MB ou uma parte abaixo de 5 MB que não seja a última.
`InvalidPart` / `InvalidPartOrder` / `NoSuchUpload`	Conclusão de multipart com partes inválidas, ou um upload que não existe mais.
`BadDigest`	O corpo não corresponde ao `Content-MD5` ou ao cabeçalho `x-amz-checksum-*`.
`PreconditionFailed`	Uma condição `If-Match` ou `If-None-Match` falhou.
`MetadataTooLarge`	Mais de 5 chaves de metadados ou 512 bytes.
`KeyTooLongError`	A chave é longa demais (cerca de 1000 bytes). A mensagem diz o limite exato da sua conta.
`SlowDown`	HTTP 503: um limite de taxa ou o limite de uploads abertos foi atingido. Os SDKs tentam novamente com backoff por conta própria.
`NotImplemented`	A operação não é suportada (veja acima).

Primeiros Passos

Objetos

Uploads em Partes

Conta

Links de Compartilhamento

S3

Credenciais

Buckets

Configuração

Operações suportadas

Chaves

Metadados, cache e expiração

Limites

Tamanho da parte

Erros

​Credenciais

​Buckets

​Configuração

​Operações suportadas

​Chaves

​Metadados, cache e expiração

​Limites

​Tamanho da parte

​Erros

Credenciais

Buckets

Configuração

Operações suportadas

Chaves

Metadados, cache e expiração

Limites

Tamanho da parte

Erros