Envio de Objeto Blob - Square Cloud

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=myfile&prefix=images&expire=30' \
  --header 'Authorization: SUA_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: 'SUA_API_KEY' },
  body: form,
});

import requests

with open('myphone.png', 'rb') as f:
    response = requests.post(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'SUA_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"
    }
}

Authorization

string

obrigatório

A chave da API para sua conta. Você pode encontrá-la nas configurações da conta.

Envio de objeto envia um único arquivo para o Blob Storage da Square Cloud e retorna uma URL servida pela CDN, pronta para incorporar ou compartilhar diretamente, sem que você precise provisionar um bucket ou gerenciar ACLs. Serve como base para anexos, exportações geradas e mídia enviada por usuários em aplicações hospedadas na plataforma. O content type declarado do arquivo enviado precisa corresponder a um dos tipos MIME permitidos pela plataforma; qualquer coisa fora dessa lista é rejeitada como INVALID_FILE_TYPE antes de o arquivo chegar ao armazenamento. Objetos podem receber uma expiração automática entre 1 e 365 dias, após a qual deixam de ser servidos. Depois de enviado, navegue pelo arquivo com Lista de objetos, remova-o com Exclusão de objeto, ou acompanhe o uso em relação à cota do seu plano com Estatísticas da conta.

file

obrigatório

Use FormData (multipart/form-data). Exatamente um arquivo por requisição.

name

string

obrigatório

Uma string representando o nome do arquivo (sem extensão).
Deve obedecer ao padrão a-z, A-Z, 0-9 e _ (3 a 32 caracteres).

prefix

string

Uma string representando o prefixo do arquivo.
Deve obedecer ao padrão a a z, A a Z, 0 a 9 e _ (3 a 32 caracteres).

expire

number

Um número indicando o período de expiração do arquivo, variando de 1 a 365 dias.

security_hash

boolean

Defina como true se um hash de segurança for exigido.

auto_download

boolean

Defina como true se o arquivo deve ser marcado para download automático.

Limites e uploads simultâneos

O envio de arquivos exige um plano pago.

Toda conta pode ter no máximo 4 uploads em andamento simultaneamente. Iniciar outro upload enquanto 4 ainda estão em execução retorna TOO_MANY_CONCURRENT_UPLOADS (429).
Planos Hobby e Standard são adicionalmente limitados a 1 upload por segundo (RATE_LIMITED, 429). Planos Pro e Enterprise são isentos do limite por segundo.

Por segurança, arquivos .html e .svg são sempre entregues como download (servidos como application/octet-stream) em vez de renderizados inline. Definir auto_download=true aplica esse mesmo comportamento de download forçado a qualquer tipo de arquivo.

Tipos MIME permitidos

Os uploads são validados contra uma whitelist rigorosa de tipos MIME; qualquer coisa fora dela é rejeitada como INVALID_FILE_TYPE. A extensão do arquivo armazenado é derivada no servidor a partir do tipo MIME.

Categoria	Tipos MIME
Vídeo	`video/mp4`, `video/mpeg`, `video/webm`, `video/x-flv`, `video/x-m4v`
Imagem	`image/jpeg`, `image/png`, `image/apng`, `image/tiff`, `image/gif`, `image/webp`, `image/bmp`, `image/svg+xml`, `image/x-icon`, `image/ico`, `image/cur`, `image/heic`, `image/heif`
Áudio	`audio/wav`, `audio/ogg`, `audio/opus`, `audio/mp4`, `audio/mpeg`, `audio/aac`
Texto	`text/html`, `text/css`, `text/csv`, `text/plain`, `text/x-sql`
Aplicação	`application/xml`, `application/sql`, `application/x-sql`, `application/x-sqlite3`, `application/x-pkcs12`, `application/pdf`, `application/json`, `application/javascript`

Resposta

status

string

Indica se a chamada foi bem-sucedida. “success” se bem-sucedida, “error” caso contrário.

response

object

Mostrar Alternar objeto

string

O ID do arquivo enviado.

name

string

O nome do arquivo enviado.

prefix

string

O prefixo sob o qual o arquivo foi armazenado (refletido da query prefix; omitido quando nenhum foi enviado).

size

number

O tamanho do arquivo enviado, em bytes.

url

string

A URL pública da CDN para o arquivo enviado: https://public-blob.squarecloud.dev/<user_id>/<key>, onde a chave é [prefix/]name[_hash][-exN].ext (os sufixos de hash e expiração só aparecem quando usados; a extensão é derivada do tipo MIME).

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=myfile&prefix=images&expire=30' \
  --header 'Authorization: SUA_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: 'SUA_API_KEY' },
  body: form,
});

import requests

with open('myphone.png', 'rb') as f:
    response = requests.post(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'SUA_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"
    }
}

Solução de problemas

Relacionado ao Objeto

// O nome do objeto fornecido é inválido.
// Deve obedecer ao padrão a a z, A a Z, 0 a 9 e _.
{
    "status": "error",
    "code": "INVALID_OBJECT_NAME"
}

// O prefixo do objeto fornecido é inválido.
// Deve obedecer ao padrão a a z, A a Z, 0 a 9 e _.
{
    "status": "error",
    "code": "INVALID_OBJECT_PREFIX"
}

// O valor de expiração fornecido para o objeto é inválido.
// Deve ser um número entre 1 e 365. (valor em dias).
{
    "status": "error",
    "code": "INVALID_OBJECT_EXPIRE"
}

// O booleano de hash de segurança fornecido é inválido.
// Deve ser apenas true ou false.
{
    "status": "error",
    "code": "INVALID_OBJECT_SECURITY_HASH"
}

// O booleano de download automático fornecido é inválido.
// Deve ser apenas true ou false.
{
    "status": "error",
    "code": "INVALID_STORAGE_AUTO_DOWNLOAD"
}

Relacionado ao Arquivo

O tamanho máximo de arquivo atualmente é 100MB. No futuro, planejamos aumentar para 10GB. Por enquanto, o limite é 100MB devido a restrições técnicas e de balanceamento.

// O arquivo fornecido é inválido.
{
    "status": "error",
    "code": "INVALID_FILE"
}

// O tipo de arquivo fornecido é inválido.
{
    "status": "error",
    "code": "INVALID_FILE_TYPE"
}

// O tamanho do arquivo é pequeno demais (< 1KB).
{
    "status": "error",
    "code": "FILE_TOO_SMALL"
}

Não autorizado

// A chave de API está ausente ou é inválida. Defina uma chave válida no cabeçalho Authorization.
{
    "status": "error",
    "code": "ACCESS_DENIED"
}

// A conta não possui um plano pago ativo. Enviar arquivos ao Blob Storage exige um plano pago.
{
    "status": "error",
    "code": "PERMISSION_DENIED"
}

Cota de armazenamento excedida

// Você excedeu sua cota de armazenamento. Exclua arquivos ou faça upgrade do plano.
{
    "status": "error",
    "code": "STORAGE_QUOTA_EXCEEDED"
}

Tipo de conteúdo inválido

// Esta rota aceita apenas requisições multipart/form-data com exatamente um arquivo.
{
    "status": "error",
    "code": "INVALID_CONTENT_TYPE"
}

Payload grande demais

O tamanho máximo atual de arquivo é 100MB.

// O arquivo enviado excede o tamanho máximo permitido de 100 MB.
{
    "status": "error",
    "code": "FILE_TOO_LARGE"
}

Limite de requisições

// Limite de uploads por segundo atingido (Hobby/Standard: máx. 1 upload por segundo).
{
    "status": "error",
    "code": "RATE_LIMITED"
}

// Uploads simultâneos demais (máx. 4 em andamento ao mesmo tempo por conta).
{
    "status": "error",
    "code": "TOO_MANY_CONCURRENT_UPLOADS"
}

Falha no upload

// Falha ao enviar o objeto para o armazenamento. Tente novamente mais tarde.
{
    "status": "error",
    "code": "UPLOAD_FAILED"
}

Excluir ObjetosEsta documentação fornece uma visão abrangente do endpoint DELETE /v1/objects da API Blob da SquareCloud.

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=myfile&prefix=images&expire=30' \
  --header 'Authorization: SUA_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: 'SUA_API_KEY' },
  body: form,
});

import requests

with open('myphone.png', 'rb') as f:
    response = requests.post(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'SUA_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"
    }
}

​Limites e uploads simultâneos

​Tipos MIME permitidos

​Resposta

​Solução de problemas

​Relacionado ao Objeto

​Relacionado ao Arquivo

​Não autorizado

​Cota de armazenamento excedida

​Tipo de conteúdo inválido

​Payload grande demais

​Limite de requisições

​Falha no upload

Limites e uploads simultâneos

Tipos MIME permitidos

Resposta

Solução de problemas

Relacionado ao Objeto

Relacionado ao Arquivo

Não autorizado

Cota de armazenamento excedida

Tipo de conteúdo inválido

Payload grande demais

Limite de requisições

Falha no upload