Enviar um arquivo para o 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

obrigatório

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

O Envio de Objeto faz o upload de um arquivo e retorna o seu id e, para arquivos públicos, uma url da CDN que você pode incorporar ou compartilhar diretamente. Ele dá suporte a anexos, exportações geradas e mídias enviadas por usuários em aplicações hospedadas na plataforma. Uma única requisição aceita arquivos de 512 bytes até 100 MB. Arquivos maiores, até 10 GiB, passam pelo fluxo de upload em partes ou pelo gateway S3. Exige o escopo blob:write, ou um token de upload enviado em Authorization, e um plano ativo.

Trate o id retornado como opaco: guarde-o como veio e envie-o de volta às outras rotas. Ele começa com pub/ ou prv/ e pode mudar quando o arquivo muda de visibilidade ou de expiração. Arquivos legados, armazenados antes da atualização de setembro de 2026, mantêm ids sem esse prefixo, e toda rota aceita os dois.

Parâmetros

file

obrigatório

Use FormData (multipart/form-data), exatamente um arquivo por requisição.
Envie um nome de arquivo real: a extensão armazenada vem dele (reads.fastq.gz continua .fastq.gz).

string

obrigatório

O nome do arquivo, sem extensão. De 1 a 128 caracteres: letras, dígitos, _, . e -, começando com uma letra, um dígito ou _. Não pode conter ...

string

O caminho da pasta do arquivo, com até 8 segmentos separados por / e 256 caracteres no total. Cada segmento segue o mesmo padrão de name, com até 64 caracteres. Uma / no final é ignorada.

boolean

padrão:"false"

true armazena o arquivo sem URL pública. Leia-o pelo Download de Objeto, por um link de compartilhamento ou pelo gateway S3. Quando omitido, a regra do prefixo decide.

string

Exclui o arquivo automaticamente depois desse tempo: 30 ou 30d para dias, 6h para horas. De 1 hora a 1825 dias (5 anos). Expirações abaixo de 7 dias exigem o plano Enterprise. Quando omitido, a regra do prefixo decide.

boolean

padrão:"false"

true adiciona um sufixo aleatório ao nome, para que a URL não possa ser adivinhada e um novo upload nunca substitua um antigo. Arquivos privados sempre o recebem (false junto com private=true é recusado).

boolean

padrão:"true"

Sem security hash, um novo upload com o mesmo nome e prefixo substitui o arquivo. false o recusa com 409 OBJECT_ALREADY_EXISTS.

string

inline (abre no navegador) ou attachment (download, com o nome original do arquivo).

boolean

padrão:"false"

true faz os navegadores baixarem o arquivo em vez de abri-lo, seja qual for o tipo.

string

Por quanto tempo a CDN e os navegadores mantêm o arquivo: immutable (1 ano), max-age=N com N de 60 a 31536000 segundos, ou no-cache (toda leitura vai ao armazenamento; somente Enterprise). Arquivos com security hash usam immutable por padrão. O cache nunca dura mais que a expiração do arquivo.

string

Um objeto JSON de valores string, retornado pelo Informações do Objeto. As chaves usam a-z, 0-9 e - (até 64 caracteres). Até 5 chaves e 512 bytes no total. Somente Pro e Enterprise.

string

O SHA-256 do arquivo. Quando não corresponde, o upload é recusado com CHECKSUM_MISMATCH e nada é armazenado.

Limites de taxa e concorrência

Cada conta pode ter no máximo 4 uploads em andamento ao mesmo tempo (TOO_MANY_CONCURRENT_UPLOADS, 429).
Os planos Hobby e Standard são limitados a 1 upload por segundo (RATE_LIMITED, 429). Pro e Enterprise são isentos.
Uploads acima do armazenamento incluído da conta são recusados com STORAGE_QUOTA_EXCEEDED.

Tipos de arquivo

Praticamente qualquer extensão é aceita, incluindo formatos sem tipo MIME registrado (.bam, .vcf, .fasta, .parquet, .h5, .npy e assim por diante).

O Content-Type servido é derivado no servidor a partir da extensão. Formatos desconhecidos são servidos como application/octet-stream.
Formatos que um navegador renderiza (.html, .svg, .xml e similares) são sempre servidos como download.
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.
Uma regra do prefixo ou um token de upload pode restringir as extensões e o tamanho aceitos.

Resposta

string

“success” se bem-sucedida, “error” caso contrário.

object

Mostrar Alternar objeto

string

O id do objeto: pub/<user_id>/<path> ou prv/<user_id>/<path>. Trate-o como opaco.

boolean

Se o arquivo é privado.

string | null

A URL pública da CDN (https://blob.squarecloud.dev/pub/...), ou null para arquivos privados.

ISO 8601

Quando o arquivo será excluído. Presente apenas quando ele expira.

number

O tamanho do arquivo, em bytes.

string

O nome enviado na requisição.

string

O prefixo, quando um foi enviado.

string

O SHA-256 do arquivo armazenado, em hexadecimal.

boolean

true quando o upload substituiu um arquivo existente com o mesmo nome.

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

Erros

Código	HTTP	Quando
`INVALID_OBJECT_NAME` / `INVALID_OBJECT_PREFIX`	400	`name` ou `prefix` não corresponde ao padrão.
`INVALID_OBJECT_EXPIRE`	400	`expire` não é uma duração de 1 hora a 1825 dias.
`INVALID_OBJECT_PRIVATE` / `INVALID_OBJECT_OVERWRITE` / `INVALID_STORAGE_AUTO_DOWNLOAD`	400	A flag não é `true` nem `false`.
`INVALID_OBJECT_SECURITY_HASH`	400	Não é um booleano, ou é `false` em um arquivo privado.
`INVALID_OBJECT_DISPOSITION` / `INVALID_OBJECT_CACHE_CONTROL` / `INVALID_OBJECT_METADATA` / `INVALID_CHECKSUM`	400	O valor está fora das formas aceitas.
`INVALID_FILE` / `INVALID_FILE_TYPE` / `BLOCKED_FILE_TYPE` / `FILE_TYPE_NOT_ALLOWED`	400	A parte do arquivo está ausente, a extensão está malformada ou bloqueada, ou a regra ou o token não a permite.
`FILE_TOO_SMALL`	400	O arquivo tem menos de 512 bytes.
`CHECKSUM_MISMATCH`	400	O arquivo não corresponde a `checksum_sha256`. Nada foi armazenado.
`PERMISSION_DENIED`	401	A conta não tem um plano ativo.
`UPLOAD_TOKEN_USED`	401	O token de upload não tem mais usos. Um token expirado responde `ACCESS_DENIED`.
`STORAGE_QUOTA_EXCEEDED`	403	O upload ultrapassaria o armazenamento incluído.
`PREFIX_NOT_ALLOWED`	403	O token de upload está vinculado a outro prefixo.
`UPGRADE_REQUIRED`	403	Uma opção exige um plano superior. A `message` indica qual.
`ACCOUNT_BLOCKED`	403	A conta está bloqueada para armazenar arquivos.
`INVALID_CONTENT_TYPE`	409	A requisição não é `multipart/form-data`.
`OBJECT_ALREADY_EXISTS`	409	O nome já existe e `overwrite=false`.
`FILE_TOO_LARGE`	413	Acima de 100 MB, ou acima do tamanho permitido pela regra ou pelo token.
`RATE_LIMITED` / `TOO_MANY_CONCURRENT_UPLOADS`	429	1 upload por segundo (Hobby e Standard), ou 4 em andamento.
`UPLOAD_FAILED`	500	O armazenamento falhou. Tente novamente.
`PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE`	503	O armazenamento está temporariamente indisponível. Tente novamente.

Veja Erros para a lista completa.

Relacionados

SDK do 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
    }
}

Primeiros passos

Objetos

Uploads em partes

Conta

Links de compartilhamento

S3

Enviar um arquivo para o Blob Storage

Parâmetros

Limites de taxa e concorrência

Tipos de arquivo

Resposta

Erros

Relacionados

​Parâmetros

​Limites de taxa e concorrência

​Tipos de arquivo

​Resposta

​Erros

​Relacionados

Parâmetros

Limites de taxa e concorrência

Tipos de arquivo

Resposta

Erros

Relacionados