Compatibilidad con S3

Blob Storage habla la API de S3 en https://s3-blob.squarecloud.app. Cualquier herramienta que permita definir un endpoint personalizado funciona: aws-cli, boto3, el SDK de AWS para JavaScript, rclone, Cyberduck y la mayoría de las herramientas de copia de seguridad.

Credenciales

Las herramientas S3 firman las solicitudes con un par de claves de acceso. Obtenlo en S3 Credentials:

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

El par se deriva de tu API key. No necesita gestión aparte: revocar o regenerar la key hace lo mismo con el par, y el par recibe los mismos scopes. Una key con solo blob:read da un par de solo lectura. El par no cambia mientras la API key no cambie, así que obtenlo una vez y guárdalo en tu gestor de secretos o en una variable de entorno. No llames a la ruta en cada arranque: acepta 10 solicitudes por hora.

Ajuste	Valor
Endpoint	`https://s3-blob.squarecloud.app`
Región	`auto`
Direccionamiento	Path-style (`https://s3-blob.squarecloud.app/<bucket>/<key>`)
Firma	AWS Signature Version 4

Buckets

Tu cuenta ve tres buckets fijos. No puedes crear ni eliminar buckets.

Bucket	Contenido	Acceso
`public`	Archivos públicos, servidos en `https://blob.squarecloud.dev/pub/<user_id>/<key>`	Lectura y escritura
`private`	Archivos privados, sin URL pública	Lectura y escritura
`legacy`	Archivos heredados, subidos antes de la actualización de septiembre de 2026	Lectura, listado y eliminación

Una key en el bucket public o private es la ruta del objeto sin tu id de usuario: images/logo.png en el bucket public es el objeto pub/<user_id>/images/logo.png en la API REST. Los archivos escritos por S3 aparecen en la API REST y en el dashboard, y viceversa.

Configuración

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

boto3 necesita signature_version="s3v4" para las URL prefirmadas: sin eso, generate_presigned_url firma con el antiguo SigV2, que el gateway no acepta. Las URL prefirmadas duran hasta 7 días (604800 segundos).

Las respuestas del gateway nunca se guardan en caché en el edge. Una URL prefirmada deja de funcionar exactamente cuando expira, cuando se revoca la API key o cuando se elimina el objeto.

Operaciones compatibles

Área	Operaciones
Buckets	`ListBuckets`, `HeadBucket`, `GetBucketLocation`. `CreateBucket` sobre un bucket existente tiene éxito; `DeleteBucket` responde `BucketNotEmpty` mientras el bucket tenga archivos.
Listado	`ListObjects` y `ListObjectsV2`, con `delimiter`, `prefix` y `encoding-type=url`.
Objetos	`HeadObject`, `GetObject` (con `Range`, `If-Match`, `If-None-Match`, `If-Modified-Since`), `PutObject` (hasta 100 MB en una sola solicitud), `CopyObject` (directivas de metadatos `COPY` y `REPLACE`), `DeleteObject`, `DeleteObjects` (hasta 1000 keys).
Multipart	`CreateMultipartUpload`, `UploadPart` (de 5 MB a 80 MB por parte, excepto la última), `UploadPartCopy`, `CompleteMultipartUpload`, `AbortMultipartUpload`, `ListParts`, `ListMultipartUploads`. Objetos de hasta 10 GiB.
Integridad	`Content-MD5` siempre se verifica, incluso cuando también se envía una cabecera `x-amz-checksum-*`. `x-amz-checksum-crc32`, `-sha1` y `-sha256` también se verifican; si no coinciden, responde `BadDigest`. `crc32c` y `crc64nvme` se aceptan sin verificación. Se admiten cuerpos `aws-chunked`.
Compatibilidad	`GetBucketVersioning`, `GetBucketAcl`, `GetObjectAcl` y las lecturas de etiquetas responden valores fijos para que las herramientas que los consultan sigan funcionando.

Las políticas de bucket, CORS, lifecycle, website, cifrado, object lock, versiones, logging, notificaciones, replicación, escrituras de ACL y de etiquetas, GET por partNumber y las subidas por formulario POST desde el navegador responden 501 NotImplemented. Usa la configuración de la cuenta para las reglas de ciclo de vida.

Keys

Las keys son rutas literales. Una key puede tener hasta unos 1000 bytes: el límite de 1024 bytes también cuenta el prefijo de la cuenta. Una key más larga responde KeyTooLongError, y su mensaje indica el número exacto de bytes que tienes. Los segmentos no pueden estar vacíos ni ser . o ...
Una key de 0 bytes que termina en / es un marcador de carpeta, igual que la consola de AWS crea carpetas.
El Content-Type servido se deriva de la extensión, como en la API REST. Los ejecutables se rechazan con InvalidArgument y .html, .svg y .xml se sirven como descargas.

Metadatos, caché y expiración

Las cabeceras x-amz-meta-* se conservan en Pro y Enterprise (hasta 5 claves y 512 bytes; si no, MetadataTooLarge). En otros planes se descartan.
Cache-Control y Content-Disposition se conservan. Un Cache-Control sin caché (no-cache, no-store o max-age=0) fuera de Enterprise se rechaza con AccessDenied.
Las reglas por prefijo se aplican a los objetos escritos por S3, incluida la eliminación automática. max_size y extensions de una regla solo se aplican a las subidas REST.

Límites

Límite	Valor
Solicitudes por cuenta, cada 10 segundos	Hobby 100 · Standard 200 · Pro 400 · Enterprise 600
Copias en el servidor (`CopyObject`, `UploadPartCopy`)	20 cada 10 segundos
Keys eliminadas por `DeleteObjects`	2000 cada 10 segundos
Subidas multipart abiertas	32 por cuenta, compartidas con las subidas por partes de la API REST
`PutObject` único	100 MB
Parte (`UploadPart`)	De 5 MB a 80 MB, excepto la última parte
Tamaño del objeto	10 GiB
Credenciales inválidas	Demasiados fallos bloquean la IP durante unos minutos

Por encima de un límite, el gateway responde SlowDown (HTTP 503), y los SDK de AWS esperan y reintentan por su cuenta. Las solicitudes S3 no cuentan para el límite de solicitudes de API de tu plan. Comprueba el par de keys antes de reintentar en bucle: una IP que envía demasiadas credenciales inválidas queda bloqueada durante unos minutos.

Tamaño de parte

Las herramientas multipart dividen los archivos grandes por su cuenta; mantén cada parte en 80 MB o menos. Los valores por defecto de AWS CLI (8 MB) y rclone (5 MB) ya encajan.

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, // hasta 80 MB
}).done();

Escribir requiere un plan de pago. Sin él, y en el bucket de solo lectura legacy, las escrituras responden AccessDenied. La cuota de almacenamiento se aplica igual que en la API REST.

Errores

El gateway responde con errores XML estándar de S3, así que los SDK los gestionan de forma nativa:

Error	Cuándo
`AccessDenied`	Sin plan de pago, key de solo lectura, escritura en `legacy` o una opción fuera de tu plan.
`NoSuchBucket`	El bucket no es `public`, `private` ni `legacy`.
`NoSuchKey`	El objeto no existe.
`InvalidArgument`	Un tipo de archivo bloqueado (ejecutables e instaladores) o una cabecera mal formada.
`QuotaExceeded`	La cuenta alcanzó su almacenamiento incluido.
`EntityTooLarge` / `EntityTooSmall`	Un `PutObject` de más de 100 MB, una parte de más de 80 MB o una parte de menos de 5 MB que no es la última.
`InvalidPart` / `InvalidPartOrder` / `NoSuchUpload`	Finalización multipart con partes incorrectas, o una subida que ya no existe.
`BadDigest`	El cuerpo no coincide con `Content-MD5` o con la cabecera `x-amz-checksum-*`.
`PreconditionFailed`	Falló una condición `If-Match` o `If-None-Match`.
`MetadataTooLarge`	Más de 5 claves de metadatos o 512 bytes.
`KeyTooLongError`	La key es demasiado larga (unos 1000 bytes). El mensaje indica el límite exacto para tu cuenta.
`SlowDown`	HTTP 503: se alcanzó un límite de tasa o el límite de subidas abiertas. Los SDK reintentan con backoff por su cuenta.
`NotImplemented`	La operación no es compatible (ver arriba).

Primeros Pasos

Objetos

Subida en Partes

Cuenta

Enlaces Compartidos

S3

Credenciales

Buckets

Configuración

Operaciones compatibles

Keys

Metadatos, caché y expiración

Límites

Tamaño de parte

Errores

​Credenciales

​Buckets

​Configuración

​Operaciones compatibles

​Keys

​Metadatos, caché y expiración

​Límites

​Tamaño de parte

​Errores

Credenciales

Buckets

Configuración

Operaciones compatibles

Keys

Metadatos, caché y expiración

Límites

Tamaño de parte

Errores