Envio de Objeto Blob

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"
    }
}

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. A extensão armazenada vem do nome de arquivo que você envia na parte multipart (com fallback para o tipo MIME declarado e depois para bin), então sempre envie um nome de arquivo real. Praticamente qualquer tipo de arquivo é aceito; apenas executáveis e instaladores são recusados. Objetos podem receber uma expiração automática entre 7 e 1825 dias (5 anos), após a qual deixam de ser servidos. Uma única requisição aceita arquivos de 512 bytes até 100 MB, o maior corpo que o edge da Cloudflare aceita. Arquivos maiores, até 1 GiB, passam pelo fluxo de upload em partes. 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.
Envie um nome de arquivo real: a extensão armazenada é derivada dele.

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).

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).

number

Um número indicando o período de expiração do arquivo, variando de 7 a 1825 dias (5 anos).

boolean

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

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, formatos que um navegador renderiza inline (.html, .svg, .xml, .xhtml e similares) são sempre entregues como download (servidos como application/octet-stream) em vez de renderizados. Definir auto_download=true aplica esse mesmo comportamento de download forçado a qualquer tipo de arquivo.

Tipos de arquivo

Praticamente qualquer extensão é aceita, incluindo formatos sem tipo MIME registrado (.bam, .vcf, .fasta, .fastq, .parquet, .h5, .npy e assim por diante). Não existe mais uma allowlist de tipos MIME.

A extensão armazenada é derivada do nome de arquivo enviado na parte multipart, com fallback para o tipo MIME declarado e depois para bin.
Sufixos compostos de compressão são preservados: reads.fastq.gz é armazenado como .fastq.gz, não .gz.
O Content-Type servido é derivado no servidor a partir da extensão. Formatos desconhecidos são servidos como application/octet-stream, então são baixados em vez de renderizados.
Executáveis e instaladores são recusados com 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.

Resposta

string

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

object

Mostrar Alternar objeto

string

O ID do arquivo enviado.

string

O nome do arquivo enviado.

string

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

number

O tamanho do arquivo enviado, em bytes.

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 nome de arquivo enviado).

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 7 e 1825. (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

Uma única requisição aceita até 100 MB. Para arquivos de até 1 GiB, use o fluxo de upload em partes.

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

// A extensão do arquivo está malformada ou é longa demais.
{
    "status": "error",
    "code": "INVALID_FILE_TYPE"
}

// Extensões de executáveis/instaladores (exe, msi, bat, apk, ...) não são aceitas.
{
    "status": "error",
    "code": "BLOCKED_FILE_TYPE"
}

// O tamanho do arquivo é pequeno demais (< 512 bytes).
{
    "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

Uma única requisição aceita até 100 MB. Para arquivos de até 1 GiB, use o fluxo de upload em partes.

// Uma única requisição aceita até 100 MB. Use /v1/objects/chunked para arquivos de até 1 GiB.
{
    "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"
}

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"
    }
}

Endpoints do Blob

Uploads em Partes

Limites e uploads simultâneos

Tipos de arquivo

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 de arquivo

​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 de arquivo

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