Subir un archivo a Blob Storage

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=logo&prefix=images&security_hash=true' \
  --header 'Authorization: YOUR_API_KEY' \
  --form 'file=@./logo.png'

import fs from 'node:fs';

const form = new FormData();
form.append('file', new Blob([fs.readFileSync('./logo.png')]), 'logo.png');

const params = new URLSearchParams({
  name: 'logo',
  prefix: 'images',
  security_hash: 'true',
});

const response = await fetch(`https://blob.squarecloud.app/v1/objects?${params}`, {
  method: 'POST',
  headers: { Authorization: 'YOUR_API_KEY' },
  body: form,
});

import requests

with open('logo.png', 'rb') as f:
    response = requests.post(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'YOUR_API_KEY'},
        params={'name': 'logo', 'prefix': 'images', 'security_hash': 'true'},
        files={'file': ('logo.png', f, 'image/png')},
    )

{
    "status": "success",
    "response": {
        "id": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "private": false,
        "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "size": 416230,
        "name": "logo",
        "prefix": "images",
        "sha256": "5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
        "replaced": false
    }
}

{
    "status": "success",
    "response": {
        "id": "prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf",
        "private": true,
        "url": null,
        "size": 88412,
        "name": "2026-09",
        "prefix": "invoices",
        "sha256": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
        "replaced": false
    }
}

string

requerido

La clave de API de tu cuenta. Puedes encontrarla en la configuración de tu cuenta.

Object Post sube un archivo y devuelve su id y, para los archivos públicos, una url de la CDN que puedes incrustar o compartir directamente. Da soporte a adjuntos, exportaciones generadas y contenido multimedia subido por los usuarios de las aplicaciones alojadas en la plataforma. Una sola solicitud acepta archivos de 512 bytes hasta 100 MB. Los archivos más grandes, de hasta 10 GiB, pasan por el flujo de subida por partes o por el gateway S3. Requiere el scope blob:write, o un token de subida enviado en Authorization, y un plan activo.

Trata el id devuelto como opaco: guárdalo tal como llega y envíalo de vuelta a las demás rutas. Empieza por pub/ o prv/ y puede cambiar cuando el archivo cambia de visibilidad o de expiración. Los archivos heredados, almacenados antes de la actualización de septiembre de 2026, conservan ids sin ese prefijo, y todas las rutas aceptan ambos.

Parámetros

file

requerido

Usa FormData (multipart/form-data), exactamente un archivo por solicitud.
Envía un nombre de archivo real: la extensión almacenada proviene de él (reads.fastq.gz sigue siendo .fastq.gz).

string

requerido

El nombre del archivo, sin extensión. De 1 a 128 caracteres: letras, dígitos, _, . y -, empezando por una letra, un dígito o _. No puede contener ...

string

Una ruta de carpeta para el archivo, de hasta 8 segmentos separados por / y 256 caracteres en total. Cada segmento sigue el mismo patrón que name, con hasta 64 caracteres. Una / final se ignora.

boolean

predeterminado:"false"

true almacena el archivo sin URL pública. Léelo mediante Object Download, un enlace compartido o el gateway S3. Si se omite, decide la regla del prefijo.

string

Elimina el archivo automáticamente tras este tiempo: 30 o 30d para días, 6h para horas. De 1 hora a 1825 días (5 años). Las expiraciones de menos de 7 días requieren el plan Enterprise. Si se omite, decide la regla del prefijo.

boolean

predeterminado:"false"

true añade un sufijo aleatorio al nombre, para que la URL no se pueda adivinar y una nueva subida nunca reemplace a una anterior. Los archivos privados siempre lo reciben (false junto con private=true se rechaza).

boolean

predeterminado:"true"

Sin security hash, una nueva subida con el mismo nombre y prefijo reemplaza el archivo. false la rechaza en su lugar con 409 OBJECT_ALREADY_EXISTS.

string

inline (abrir en el navegador) o attachment (descargar, con el nombre de archivo original).

boolean

predeterminado:"false"

true hace que los navegadores descarguen el archivo en lugar de abrirlo, sea cual sea su tipo.

string

Cuánto tiempo guardan el archivo la CDN y los navegadores: immutable (1 año), max-age=N con N de 60 a 31536000 segundos, o no-cache (cada lectura va al almacenamiento; solo Enterprise). Los archivos con security hash usan immutable por defecto. La caché nunca dura más que la expiración del archivo.

string

Un objeto JSON con valores de tipo string, devuelto por Object Info. Las claves usan a-z, 0-9 y - (hasta 64 caracteres). Hasta 5 claves y 512 bytes en total. Solo Pro y Enterprise.

string

El SHA-256 del archivo. Si no coincide, la subida se rechaza con CHECKSUM_MISMATCH y no se almacena nada.

Límites de tasa y concurrencia

Cada cuenta puede tener como máximo 4 subidas en curso al mismo tiempo (TOO_MANY_CONCURRENT_UPLOADS, 429).
Los planes Hobby y Standard están limitados a 1 subida por segundo (RATE_LIMITED, 429). Pro y Enterprise están exentos.
Las subidas que superan el almacenamiento incluido de la cuenta se rechazan con STORAGE_QUOTA_EXCEEDED.

Tipos de archivo

Se acepta prácticamente cualquier extensión, incluidos formatos sin tipo MIME registrado (.bam, .vcf, .fasta, .parquet, .h5, .npy, etc.).

El Content-Type servido se determina en el servidor a partir de la extensión. Los formatos desconocidos se sirven como application/octet-stream.
Los formatos que un navegador renderiza (.html, .svg, .xml y similares) se sirven siempre como descargas.
Los ejecutables e instaladores se rechazan con BLOCKED_FILE_TYPE: exe, msi, dll, bat, cmd, com, scr, cpl, pif, hta, vbs, vbe, jse, wsf, wsh, msc, reg, lnk, sys, drv, ps1, apk, xpi.
Una regla del prefijo o un token de subida pueden restringir las extensiones y el tamaño aceptados.

Respuesta

string

“success” si tuvo éxito, “error” si no.

object

Mostrar Alternar objeto

string

El id del objeto: pub/<user_id>/<path> o prv/<user_id>/<path>. Trátalo como opaco.

boolean

Si el archivo es privado.

string | null

La URL pública de la CDN (https://blob.squarecloud.dev/pub/...), o null para los archivos privados.

ISO 8601

Cuándo se eliminará el archivo. Solo aparece cuando expira.

number

El tamaño del archivo, en bytes.

string

El nombre enviado en la solicitud.

string

El prefijo, cuando se envió uno.

string

El SHA-256 del archivo almacenado, en hexadecimal.

boolean

true cuando la subida reemplazó un archivo existente con el mismo nombre.

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=logo&prefix=images&security_hash=true' \
  --header 'Authorization: YOUR_API_KEY' \
  --form 'file=@./logo.png'

import fs from 'node:fs';

const form = new FormData();
form.append('file', new Blob([fs.readFileSync('./logo.png')]), 'logo.png');

const params = new URLSearchParams({
  name: 'logo',
  prefix: 'images',
  security_hash: 'true',
});

const response = await fetch(`https://blob.squarecloud.app/v1/objects?${params}`, {
  method: 'POST',
  headers: { Authorization: 'YOUR_API_KEY' },
  body: form,
});

import requests

with open('logo.png', 'rb') as f:
    response = requests.post(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'YOUR_API_KEY'},
        params={'name': 'logo', 'prefix': 'images', 'security_hash': 'true'},
        files={'file': ('logo.png', f, 'image/png')},
    )

{
    "status": "success",
    "response": {
        "id": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "private": false,
        "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "size": 416230,
        "name": "logo",
        "prefix": "images",
        "sha256": "5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
        "replaced": false
    }
}

{
    "status": "success",
    "response": {
        "id": "prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf",
        "private": true,
        "url": null,
        "size": 88412,
        "name": "2026-09",
        "prefix": "invoices",
        "sha256": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
        "replaced": false
    }
}

Errores

Código	HTTP	Cuándo
`INVALID_OBJECT_NAME` / `INVALID_OBJECT_PREFIX`	400	`name` o `prefix` no cumplen el patrón.
`INVALID_OBJECT_EXPIRE`	400	`expire` no es una duración de 1 hora a 1825 días.
`INVALID_OBJECT_PRIVATE` / `INVALID_OBJECT_OVERWRITE` / `INVALID_STORAGE_AUTO_DOWNLOAD`	400	El flag no es `true` ni `false`.
`INVALID_OBJECT_SECURITY_HASH`	400	No es un booleano, o es `false` en un archivo privado.
`INVALID_OBJECT_DISPOSITION` / `INVALID_OBJECT_CACHE_CONTROL` / `INVALID_OBJECT_METADATA` / `INVALID_CHECKSUM`	400	El valor está fuera de las formas aceptadas.
`INVALID_FILE` / `INVALID_FILE_TYPE` / `BLOCKED_FILE_TYPE` / `FILE_TYPE_NOT_ALLOWED`	400	Falta la parte del archivo, su extensión está mal formada o bloqueada, o la regla o el token no la permiten.
`FILE_TOO_SMALL`	400	El archivo tiene menos de 512 bytes.
`CHECKSUM_MISMATCH`	400	El archivo no coincide con `checksum_sha256`. No se almacenó nada.
`PERMISSION_DENIED`	401	La cuenta no tiene un plan activo.
`UPLOAD_TOKEN_USED`	401	Al token de subida no le quedan usos. Un token expirado responde `ACCESS_DENIED`.
`STORAGE_QUOTA_EXCEEDED`	403	La subida superaría el almacenamiento incluido.
`PREFIX_NOT_ALLOWED`	403	El token de subida está vinculado a otro prefijo.
`UPGRADE_REQUIRED`	403	Una opción requiere un plan superior. El `message` indica cuál.
`ACCOUNT_BLOCKED`	403	La cuenta tiene bloqueado el almacenamiento de archivos.
`INVALID_CONTENT_TYPE`	409	La solicitud no es `multipart/form-data`.
`OBJECT_ALREADY_EXISTS`	409	El nombre ya existe y `overwrite=false`.
`FILE_TOO_LARGE`	413	Supera 100 MB, o supera el tamaño permitido por la regla o el token.
`RATE_LIMITED` / `TOO_MANY_CONCURRENT_UPLOADS`	429	1 subida por segundo (Hobby y Standard), o 4 en curso.
`UPLOAD_FAILED`	500	El almacenamiento falló. Reintenta.
`PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE`	503	El almacenamiento no está disponible temporalmente. Reintenta.

Consulta Errores para ver la lista completa.

Relacionado

SDK de Blob: blob.put()

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=logo&prefix=images&security_hash=true' \
  --header 'Authorization: YOUR_API_KEY' \
  --form 'file=@./logo.png'

import fs from 'node:fs';

const form = new FormData();
form.append('file', new Blob([fs.readFileSync('./logo.png')]), 'logo.png');

const params = new URLSearchParams({
  name: 'logo',
  prefix: 'images',
  security_hash: 'true',
});

const response = await fetch(`https://blob.squarecloud.app/v1/objects?${params}`, {
  method: 'POST',
  headers: { Authorization: 'YOUR_API_KEY' },
  body: form,
});

import requests

with open('logo.png', 'rb') as f:
    response = requests.post(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'YOUR_API_KEY'},
        params={'name': 'logo', 'prefix': 'images', 'security_hash': 'true'},
        files={'file': ('logo.png', f, 'image/png')},
    )

{
    "status": "success",
    "response": {
        "id": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "private": false,
        "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "size": 416230,
        "name": "logo",
        "prefix": "images",
        "sha256": "5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
        "replaced": false
    }
}

{
    "status": "success",
    "response": {
        "id": "prv/3155597145698959364/invoices/2026-09_mugws5c0-1b4f0e9851971998e732078544c96b36.pdf",
        "private": true,
        "url": null,
        "size": 88412,
        "name": "2026-09",
        "prefix": "invoices",
        "sha256": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
        "replaced": false
    }
}

Primeros pasos

Objetos

Subidas por partes

Cuenta

Enlaces compartidos

S3

Subir un archivo a Blob Storage

Parámetros

Límites de tasa y concurrencia

Tipos de archivo

Respuesta

Errores

Relacionado

​Parámetros

​Límites de tasa y concurrencia

​Tipos de archivo

​Respuesta

​Errores

​Relacionado

Parámetros

Límites de tasa y concurrencia

Tipos de archivo

Respuesta

Errores

Relacionado