Pular para o conteúdo principal
Visão geral do serviço Blob Storage da Square Cloud

Por que escolher o Blob Storage da Square Cloud?

Como a maior plataforma de hospedagem de bots da América Latina, com a confiança de 80 dos 100 maiores servidores brasileiros do Discord, criamos o Blob Storage para resolver um problema que a nossa própria comunidade vivia enfrentando: a CDN do Discord nunca foi feita para ser um backend de armazenamento, e os links quebram, expiram ou sofrem rate limit. O Blob Storage substitui isso por um armazenamento de objetos projetado para durabilidade. A arquitetura é simples de propósito: um armazenamento de objetos compatível com S3 é a fonte da verdade dos seus arquivos, e uma CDN global os entrega a partir do edge. Você tem a durabilidade de 11 noves de um design S3 com a latência de leitura de um cache global, e todo plano pago inclui uma cota de armazenamento, com excedente quando você precisar de mais.

Recursos principais

Sem taxas de transferência

Zero taxas de entrada e saída. Faça upload e sirva o quanto precisar: você paga pelo armazenamento, nunca pela banda.

CDN global

Os arquivos públicos são servidos por uma CDN global, no edge, perto dos seus usuários, onde quer que eles estejam.

Arquivos privados

Armazene arquivos sem URL pública e entregue-os por meio de links temporários ou links de compartilhamento. Alterne qualquer arquivo entre público e privado a qualquer momento.

Links de compartilhamento

Links que expiram, podem ser revogados, limitam o número de downloads e, no Pro e no Enterprise, pedem uma senha.

Compatível com S3

Use aws-cli, boto3, rclone ou qualquer AWS SDK pelo gateway S3, com credenciais derivadas da sua chave de API.

Uploads pelo navegador

O seu servidor gera um token de upload e o navegador faz o upload diretamente, sem nunca ver a sua chave de API.

Regras por prefixo

Defina padrões (visibilidade, expiração, cache), limites (tamanho, tipos de arquivo) e exclusão automática após N dias para tudo sob um prefixo com as configurações da conta.

Operações no servidor

Copie, mova e renomeie arquivos sem baixá-los, e altere os cabeçalhos (cache, disposition, metadados) no próprio arquivo.

Como funciona

Os arquivos entram pela API REST, pelo navegador (com um token de upload) ou por qualquer ferramenta S3. Cada arquivo é público ou privado, e sai por uma URL pública, um link temporário ou um link de compartilhamento.

Armazenamento e preços

O armazenamento vem incluído no seu plano, e não há taxas de transferência: downloads são sempre gratuitos, e você só paga pelo armazenamento acima da cota incluída se ligar o excedente.

Armazenamento incluído

Todo plano pago, do Hobby ao Enterprise, inclui uma cota de armazenamento sem custo adicional, que a página Uso do dashboard mostra. A cota e o excedente são medidos em gigabytes decimais: 1 GB = 1.000.000.000 de bytes. O Blob Storage exige um plano ativo: não existe plano gratuito.
Cotas anteriores. Se o seu plano estava ativo quando uma mudança na cota incluída foi anunciada, você mantém a cota anterior por 90 dias após o anúncio, ou até o fim do período que você já tinha pago, se ele terminar depois. Planos vitalícios mantêm a cota anterior. Enquanto ela vale, ela é a sua cota incluída. A página Uso do dashboard mostra a data exata da sua conta, e o Account Stats a retorna em plan.legacy.

Ao atingir sua cota

Com o excedente desligado, uploads que passariam da cota incluída são recusados com STORAGE_QUOTA_EXCEEDED até você liberar espaço ou ligar o excedente. Nada do que já está armazenado é apagado, e tudo continua sendo servido normalmente.

Excedente

O excedente permite armazenar mais do que a cota incluída e pagar só pelo que passar dela. Ele é opcional e vem desligado.
  • Ligue pela página Uso do dashboard, autenticado na sua conta. Uma chave de API não consegue ligá-lo.
  • Defina um teto em GB inteiros acima da cota incluída: até 1 TB no Standard, até 100 TB no Pro e sem limite no Enterprise. O plano Hobby não tem excedente. Os uploads podem então chegar à cota incluída mais o teto.

Armazenamento acima da cota incluída

R$ 0,20 por GB-mês acima da cota incluída, e R$ 0,15 por GB-mês no que passar do primeiro 1 TB de excedente, aplicado automaticamente. Downloads continuam gratuitos.
  • Média diária: cada dia (UTC) conta o que você armazena acima da cota incluída, até o seu teto, e cada período de cobrança é cobrado pela média dos seus dias, arredondada para o próximo GB inteiro.
  • Cobrado com o plano: o excedente é cobrado no ciclo do seu plano, na mesma fatura da renovação. Quando não há renovação para levar o consumo, ele vai numa fatura de consumo separada: a cada 30 dias nos planos de mais de um mês, uma vez por mês nos planos vitalícios e quando um plano termina sem renovação. A fatura de consumo é cobrada no cartão salvo ou paga por PIX.
  • Mínimo de R$ 10 sobre o consumo de cada fatura, somando o Blob Storage e o pós-pago do AI Gateway. Um período sem consumo não custa nada.
  • 7 dias para pagar: se uma fatura de consumo continuar em aberto depois de 7 dias, o excedente é pausado e os uploads param na cota incluída até o pagamento (o pós-pago do AI Gateway também é pausado).
  • Desligar: é recusado enquanto você armazenar mais do que a cota incluída, então apague arquivos antes. Um teto abaixo do que você já armazena acima da cota também é recusado. O que você já usou continua sendo cobrado.
O Account Stats informa o seu uso, o armazenamento diário deste mês, a configuração do excedente e uma estimativa do excedente do mês. A página de Uso do dashboard mostra o consumo do ciclo atual e quando ele fecha.
O Blob Storage exige um plano ativo. Uma conta sem plano ativo ainda pode listar, baixar, excluir e tornar arquivos privados. Quando um plano expira ou é cancelado, os arquivos armazenados entram em uma fila de exclusão, então renove assim que possível: arquivos já excluídos não podem ser recuperados.

Recursos por plano

Todo plano tem a API completa: arquivos públicos e privados, links temporários, links de compartilhamento, gateway S3, tokens de upload e regras por prefixo. Algumas opções dependem do plano, e todas respondem com o mesmo código 403 UPGRADE_REQUIRED, com uma message que indica o plano (ou o limite) que se aplica:

Arquivos públicos e privados

Todo objeto é público ou privado, e o seu id indica qual: pub/<user_id>/<path> ou prv/<user_id>/<path>.
  • Arquivos públicos têm uma URL permanente na CDN: https://blob.squarecloud.dev/pub/<user_id>/<path>.
  • Arquivos privados não têm URL pública (url é null). Você os lê por meio de um link temporário, de um link de compartilhamento, da API ou do gateway S3.
Leia Links e compartilhamento para entender como funcionam a publicação, a despublicação e os diferentes tipos de link.

Tipos de arquivo suportados

Praticamente qualquer tipo de arquivo é aceito, incluindo formatos sem tipo MIME registrado: .bam, .vcf, .fasta, .fastq, .parquet, .h5, .npy e assim por diante. A extensão armazenada vem do nome do arquivo que você envia, e sufixos compostos de compressão são preservados (reads.fastq.gz continua .fastq.gz). A única exceção é uma denylist de executáveis e instaladores (.exe, .msi, .bat, .apk e similares), recusados com BLOCKED_FILE_TYPE.
A entrega é segura por design: o Content-Type servido é definido no servidor, nunca pelo cliente. Formatos desconhecidos e tipos renderizáveis pelo navegador (.html, .svg, .xml) são sempre servidos como download (application/octet-stream), então uploads maliciosos nunca são renderizados no navegador.

Performance e durabilidade

O Blob Storage passou por benchmarks extensivos antes do lançamento. Principais resultados:
  • Latência: os arquivos são recebidos em ~11 ms em média.
  • Durabilidade: projetada para 99,999999999% (11 noves).
  • Entrega no edge: arquivos públicos ficam em cache na borda da CDN, então leituras repetidas nunca voltam até a origem.
  • Health check: https://blob.squarecloud.dev/pub/status responde OK e nunca fica em cache, então você pode apontar o seu monitoramento para ele.
Benchmark de latência global do Blob Storage
Observação: os resultados de benchmark vêm de testes controlados e variam conforme a localização geográfica, o tamanho do arquivo, a qualidade da rede e o horário de pico. Para ter números mais precisos, teste a partir do seu ambiente de produção.
Limitações regionais: usuários na África e em algumas regiões da Ásia podem ter latências maiores devido à distância física dos data centers e à infraestrutura de rede local.

Como hospedar seus arquivos

1

Obtenha uma chave de API

Crie uma chave de API com o escopo blob:write nas configurações da sua conta. Veja Autenticação.
2

Faça o upload

Envie arquivos de até 100 MB para o Envio de Objeto. Arquivos maiores, até 10 GiB, passam pelo fluxo de upload em partes. Prefere ferramentas S3? Aponte-as para o gateway S3.
3

Sirva os arquivos

Use a url da resposta para arquivos públicos, ou crie um link temporário ou um link de compartilhamento para os privados.
Para um primeiro upload e download com curl, siga o início rápido da API do Blob Storage.
Usando JavaScript? O SDK de Blob (@squarecloud/blob) cuida para você dos uploads simples e multipart, links, compartilhamentos, regras e do gateway S3, no Node.js e no navegador.

Perguntas frequentes

Qualquer plano pago, a partir do Hobby. Todo plano inclui uma cota de armazenamento, e você pode ligar o excedente para armazenar mais. Veja Planos e Preços para a comparação completa.
Com o excedente desligado, uploads que passariam da cota são recusados com STORAGE_QUOTA_EXCEEDED até você excluir objetos ou ligar o excedente. Nada do que já está armazenado é apagado, e tudo continua sendo servido normalmente. O Account Stats mostra o seu uso e a estimativa do mês a qualquer momento.
Sim. O gateway S3 em https://s3-blob.squarecloud.app funciona com aws-cli, boto3, rclone e os AWS SDKs. Obtenha o par de chaves de acesso em Credenciais S3: ele é derivado da sua chave de API, então revogar a chave revoga o par.
Todo plano tem regras por prefixo (5 no Hobby e no Standard, 10 no Pro, 20 no Enterprise). Metadados personalizados e links de compartilhamento protegidos por senha exigem Pro ou Enterprise. Expirações e exclusão automática abaixo de 7 dias, e arquivos servidos sem cache no edge, exigem Enterprise. Fora desses planos a requisição é recusada com 403 UPGRADE_REQUIRED, e a sua message indica o plano que libera o recurso.