Blob Object Post

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

import fs from 'node:fs';

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

const params = new URLSearchParams({
  name: 'myfile',
  prefix: 'images',
  expire: '30',
});

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

import requests

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

{
    "status": "success",
    "response": {
        "id": "3155597145698959364/images/test_lxch4k7y-07ee.png",
        "name": "test",
        "prefix": "images",
        "size": 416230,
        "url": "https://public-blob.squarecloud.dev/3155597145698959364/images/test_lxch4k7y-07ee.png"
    }
}

string

requerido

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

Object Post sube un único archivo a Square Cloud Blob Storage y devuelve una URL respaldada por CDN que puedes incrustar o compartir directamente, sin necesidad de aprovisionar un bucket ni gestionar tú mismo las ACL. Es la base de los adjuntos, las exportaciones generadas y los archivos multimedia subidos por usuarios en aplicaciones alojadas en la plataforma. La extensión almacenada proviene del nombre de archivo que envías en la parte multipart (recurriendo al tipo MIME declarado como alternativa y, en último caso, a bin), así que envía siempre un nombre de archivo real. Se acepta prácticamente cualquier tipo de archivo; solo se rechazan ejecutables e instaladores. A los objetos se les puede asignar una expiración automática de entre 7 y 1825 días (5 años), tras la cual dejan de servirse. Una única solicitud acepta archivos de 512 bytes hasta 100 MB, el cuerpo más grande que acepta el edge de Cloudflare. Los archivos más grandes, hasta 1 GiB, pasan por el flujo de subida por fragmentos. Una vez subido un archivo, explóralo con Object List, elimínalo con Object Delete, o controla el uso frente a la cuota de tu plan con Account Stats.

file

requerido

Usa FormData (multipart/form-data). Exactamente un archivo por solicitud.
Envía un nombre de archivo real: la extensión almacenada se deriva de él.

string

requerido

Una cadena que representa el nombre del archivo. (sin extensión)
Debe cumplir el patrón a-z, A-Z, 0-9 y _. (de 3 a 32 caracteres)

string

Una cadena que representa el prefijo del archivo.
Debe cumplir el patrón a-z, A-Z, 0-9 y _. (de 3 a 32 caracteres)

number

Un número que indica el periodo de expiración del archivo, en un rango de 7 a 1825 días (5 años).

boolean

Establece en true si se requiere un hash de seguridad.

boolean

Establece en true si el archivo debe configurarse para descarga automática.

Límites de tasa y concurrencia

La subida requiere un plan de pago.

Toda cuenta puede tener como máximo 4 subidas en curso simultáneamente. Iniciar otra subida mientras 4 siguen en ejecución devuelve TOO_MANY_CONCURRENT_UPLOADS (429).
Los planes Hobby y Standard están además limitados a 1 subida por segundo (RATE_LIMITED, 429). Los planes Pro y Enterprise están exentos del límite por segundo.

Por seguridad, los formatos que un navegador renderiza en línea (.html, .svg, .xml, .xhtml y similares) siempre se entregan como descargas (servidos como application/octet-stream) en lugar de renderizarse. Establecer auto_download=true aplica el mismo comportamiento de descarga forzada a cualquier tipo de archivo.

Tipos de archivo

Se acepta prácticamente cualquier extensión, incluidos formatos sin tipo MIME registrado (.bam, .vcf, .fasta, .fastq, .parquet, .h5, .npy, etc.). Ya no existe una lista blanca de tipos MIME.

La extensión almacenada se deriva del nombre de archivo enviado en la parte multipart, recurriendo al tipo MIME declarado como alternativa y, en último caso, a bin.
Los sufijos de compresión compuestos se conservan: reads.fastq.gz se almacena como .fastq.gz, no como .gz.
El Content-Type servido se deriva en el servidor a partir de la extensión. Los formatos desconocidos se sirven como application/octet-stream, por lo que se descargan en lugar de renderizarse.
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.

Respuesta

string

Indica si la llamada fue exitosa. “success” si tuvo éxito, “error” si no.

object

Mostrar Alternar objeto

string

El ID del archivo subido.

string

El nombre del archivo subido.

string

El prefijo bajo el cual se almacenó el archivo (reflejado desde la query prefix; se omite cuando no se envió ninguno).

number

El tamaño del archivo subido, en bytes.

string

La URL pública en la CDN del archivo subido: https://public-blob.squarecloud.dev/<user_id>/<key>, donde la clave tiene el formato [prefix/]name[_hash][-exN].ext (los sufijos de hash y expiración solo aparecen cuando se usan; la extensión se deriva del nombre de archivo subido).

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

import fs from 'node:fs';

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

const params = new URLSearchParams({
  name: 'myfile',
  prefix: 'images',
  expire: '30',
});

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

import requests

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

{
    "status": "success",
    "response": {
        "id": "3155597145698959364/images/test_lxch4k7y-07ee.png",
        "name": "test",
        "prefix": "images",
        "size": 416230,
        "url": "https://public-blob.squarecloud.dev/3155597145698959364/images/test_lxch4k7y-07ee.png"
    }
}

Solución de problemas

Relacionado con el objeto

// The provided object name is invalid.
// Must adhere to the a to z, A to Z, 0 to 9, and _ pattern.
{
    "status": "error",
    "code": "INVALID_OBJECT_NAME"
}

// The provided object prefix is invalid.
// Must adhere to the a to z, A to Z, 0 to 9, and _ pattern.
{
    "status": "error",
    "code": "INVALID_OBJECT_PREFIX"
}

// The provided expiration value for the object is invalid.
// Must be a number ranging from 7 to 1825. (value in days).
{
    "status": "error",
    "code": "INVALID_OBJECT_EXPIRE"
}

// The provided security hash boolean is invalid.
// Just set to true or false. 😅
{
    "status": "error",
    "code": "INVALID_OBJECT_SECURITY_HASH"
}

// The provided auto-download boolean is invalid.
// Just set to true or false. 😅
{
    "status": "error",
    "code": "INVALID_STORAGE_AUTO_DOWNLOAD"
}

Relacionado con el archivo

Una única solicitud acepta hasta 100 MB. Para archivos de hasta 1 GiB, usa el flujo de subida por fragmentos.

// The provided file is invalid.
{
    "status": "error",
    "code": "INVALID_FILE"
}

// The file extension is malformed or too long.
{
    "status": "error",
    "code": "INVALID_FILE_TYPE"
}

// Executable/installer extensions (exe, msi, bat, apk, ...) are not accepted.
{
    "status": "error",
    "code": "BLOCKED_FILE_TYPE"
}

// The file size is too small (< 512 bytes).
{
    "status": "error",
    "code": "FILE_TOO_SMALL"
}

No autorizado

// The API key is missing or invalid. Set a valid key in the Authorization header.
{
    "status": "error",
    "code": "ACCESS_DENIED"
}

// The account has no active paid plan. Uploading to Blob Storage requires a paid plan.
{
    "status": "error",
    "code": "PERMISSION_DENIED"
}

Cuota de almacenamiento superada

// You have exceeded your storage quota. Delete some files or upgrade your plan.
{
    "status": "error",
    "code": "STORAGE_QUOTA_EXCEEDED"
}

Tipo de contenido inválido

// This route only accepts multipart/form-data requests with exactly one file.
{
    "status": "error",
    "code": "INVALID_CONTENT_TYPE"
}

Carga útil demasiado grande

Una única solicitud acepta hasta 100 MB. Para archivos de hasta 1 GiB, usa el flujo de subida por fragmentos.

// A single request accepts up to 100 MB. Use /v1/objects/chunked for files up to 1 GiB.
{
    "status": "error",
    "code": "FILE_TOO_LARGE"
}

Límite de tasa alcanzado

// Per-second upload limit reached (Hobby/Standard: max 1 upload per second).
{
    "status": "error",
    "code": "RATE_LIMITED"
}

// Too many simultaneous uploads (max 4 in progress at a time per account).
{
    "status": "error",
    "code": "TOO_MANY_CONCURRENT_UPLOADS"
}

Fallo en la subida

// Failed to upload object to storage. Please try again later.
{
    "status": "error",
    "code": "UPLOAD_FAILED"
}

Objects DeleteEsta documentación ofrece una descripción completa del endpoint DELETE /v1/objects de la API de SquareCloud Blob.

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

import fs from 'node:fs';

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

const params = new URLSearchParams({
  name: 'myfile',
  prefix: 'images',
  expire: '30',
});

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

import requests

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

{
    "status": "success",
    "response": {
        "id": "3155597145698959364/images/test_lxch4k7y-07ee.png",
        "name": "test",
        "prefix": "images",
        "size": 416230,
        "url": "https://public-blob.squarecloud.dev/3155597145698959364/images/test_lxch4k7y-07ee.png"
    }
}

Endpoints de Blob

Subida en Partes

Límites de tasa y concurrencia

Tipos de archivo

Respuesta

Solución de problemas

Relacionado con el objeto

Relacionado con el archivo

No autorizado

Cuota de almacenamiento superada

Tipo de contenido inválido

Carga útil demasiado grande

Límite de tasa alcanzado

Fallo en la subida

​Límites de tasa y concurrencia

​Tipos de archivo

​Respuesta

​Solución de problemas

​Relacionado con el objeto

​Relacionado con el archivo

​No autorizado

​Cuota de almacenamiento superada

​Tipo de contenido inválido

​Carga útil demasiado grande

​Límite de tasa alcanzado

​Fallo en la subida

Límites de tasa y concurrencia

Tipos de archivo

Respuesta

Solución de problemas

Relacionado con el objeto

Relacionado con el archivo

No autorizado

Cuota de almacenamiento superada

Tipo de contenido inválido

Carga útil demasiado grande

Límite de tasa alcanzado

Fallo en la subida