> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Blob Storage: armazenamento compatível com S3

> Armazenamento de objetos compatível com S3: CDN global, arquivos privados, links temporários e de compartilhamento, sem cobrança de tráfego e incluso no plano.

export const BlobFlow = ({labels: l}) => {
  const dots = {
    app: "#3b82f6",
    browser: "#8b5cf6",
    s3: "#f59e0b",
    pub: "#06b6d4",
    tmp: "#10b981",
    share: "#ec4899"
  };
  const inputs = ["app", "browser", "s3"];
  const outputs = ["pub", "tmp", "share"];
  const box = (k, x, y, [w, h, ft, fs]) => <g key={`${k}-${x}-${y}`}>
      <rect className="d-box" x={x} y={y} width={w} height={h} rx="10" strokeWidth="1" />
      <circle cx={x + 20} cy={y + h / 2 - 9} r="4.5" fill={dots[k]} />
      <text className="d-title" x={x + 32} y={y + h / 2 - 4} fontSize={ft}>{l[k]}</text>
      <text className="d-text" x={x + 20} y={y + h / 2 + 16} fontSize={fs}>{l[k + "Sub"]}</text>
    </g>;
  const marker = id => <defs>
      <marker id={id} viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
        <path d="M0 0 L10 5 L0 10 z" fill="#64748b" />
      </marker>
    </defs>;
  const line = id => d => <path key={d} className="d-line" d={d} fill="none" strokeWidth="1.5" strokeDasharray="4 4" markerEnd={`url(#${id})`} />;
  const cloud = (x, y) => <g>
      <rect x={x} y={y} width="44" height="44" rx="10" fill="#1d4ed8" />
      <path transform={`translate(${x - 358} ${y - 106})`} d="M389.5 136H374.5a8 8 0 1 1 7.6-10.4h2.2a5.2 5.2 0 0 1 5.2 10.4z" fill="none" stroke="#fff" strokeWidth="1.8" strokeLinejoin="round" />
    </g>;
  const chips = (x, y) => <g>
      <rect className="d-chip" x={x} y={y} width="52" height="24" rx="6" />
      <text className="d-chip-text" x={x + 26} y={y + 16} fontSize="12" textAnchor="middle">pub/</text>
      <rect className="d-chip" x={x + 60} y={y} width="52" height="24" rx="6" />
      <text className="d-chip-text" x={x + 86} y={y + 16} fontSize="12" textAnchor="middle">prv/</text>
    </g>;
  const W = [210, 64, 16, 14];
  const T = [319, 56, 15, 13];
  return <div className="sc-diagram">
      <svg className="d-wide" viewBox="0 0 720 280" role="img" aria-label={l.alt} fontFamily="inherit">
        {marker("sc-arrow")}
        {["M215 42 C 245 42, 245 120, 275 120", "M215 140 L 275 140", "M215 238 C 245 238, 245 160, 275 160", "M445 120 C 475 120, 475 42, 505 42", "M445 140 L 505 140", "M445 160 C 475 160, 475 238, 505 238"].map(line("sc-arrow"))}
        {inputs.map((k, i) => box(k, 5, 10 + i * 98, W))}
        {outputs.map((k, i) => box(k, 505, 10 + i * 98, W))}
        <rect className="d-core" x="275" y="72" width="170" height="136" rx="12" strokeWidth="1.5" />
        {cloud(338, 86)}
        <text className="d-title" x="360" y="152" fontSize="16" textAnchor="middle">{l.core}</text>
        {chips(304, 166)}
      </svg>

      <svg className="d-tall" viewBox="0 0 320 520" role="img" aria-label={l.alt} fontFamily="inherit">
        {marker("sc-arrow-v")}
        {["M160 186 L 160 216", "M160 298 L 160 328"].map(line("sc-arrow-v"))}
        {inputs.map((k, i) => box(k, 0.5, 0.5 + i * 64, T))}
        <rect className="d-core" x="0.5" y="222" width="319" height="70" rx="12" strokeWidth="1.5" />
        {cloud(14, 235)}
        <text className="d-title" x="70" y="262" fontSize="16">{l.core}</text>
        {chips(194, 245)}
        {outputs.map((k, i) => box(k, 0.5, 334.5 + i * 64, T))}
      </svg>
    </div>;
};

<Frame>
  <img src="https://squarecloud.app/banners/pt-br/blob.png" alt="Visão geral do serviço Blob Storage da Square Cloud" style={{ borderRadius: "0.2rem" }} />
</Frame>

## 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 inclui **armazenamento generoso**.

## Recursos principais

<CardGroup cols={2}>
  <Card title="Sem taxas de transferência" icon="money-bill">
    **Zero taxas de entrada e saída.** Faça upload e sirva o quanto precisar: você paga pelo armazenamento, nunca pela banda.
  </Card>

  <Card title="CDN global" icon="globe">
    Os arquivos públicos são servidos por uma **CDN global**, no edge, perto dos seus usuários, onde quer que eles estejam.
  </Card>

  <Card title="Arquivos privados" icon="lock">
    Armazene arquivos **sem URL pública** e entregue-os por meio de [links temporários ou links de compartilhamento](/pt-br/blob-reference/links-and-sharing). Alterne qualquer arquivo entre público e privado a qualquer momento.
  </Card>

  <Card title="Links de compartilhamento" icon="share-nodes">
    Links que **expiram**, podem ser **revogados**, limitam o **número de downloads** e, no Pro e no Enterprise, pedem uma **senha**.
  </Card>

  <Card title="Compatível com S3" icon="bucket">
    Use **aws-cli, boto3, rclone** ou qualquer AWS SDK pelo [gateway S3](/pt-br/blob-reference/s3-compatibility), com credenciais derivadas da sua chave de API.
  </Card>

  <Card title="Uploads pelo navegador" icon="upload">
    O seu servidor gera um [token de upload](/pt-br/blob-reference/endpoint/upload-tokens) e o **navegador faz o upload diretamente**, sem nunca ver a sua chave de API.
  </Card>

  <Card title="Regras por prefixo" icon="sliders">
    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](/pt-br/blob-reference/endpoint/settings-put).
  </Card>

  <Card title="Operações no servidor" icon="arrows-rotate">
    [Copie, mova e renomeie](/pt-br/blob-reference/endpoint/copy) arquivos sem baixá-los, e [altere os cabeçalhos](/pt-br/blob-reference/endpoint/update) (cache, disposition, metadados) no próprio arquivo.
  </Card>
</CardGroup>

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

<BlobFlow
  labels={{
alt: "Os arquivos entram no Blob Storage pelo seu app, pelo navegador ou por ferramentas S3, e saem por uma URL pública, um link temporário ou um link de compartilhamento.",
app: "Seu app",
appSub: "API REST + chave de API",
browser: "Navegador",
browserSub: "Token de upload",
s3: "Ferramentas S3",
s3Sub: "aws-cli, boto3, rclone",
core: "Blob Storage",
pub: "URL pública",
pubSub: "CDN global, permanente",
tmp: "Link temporário",
tmpSub: "Até 24 horas",
share: "Link compartilhado",
shareSub: "Até 30 dias, revogável",
}}
/>

## Armazenamento e preços

O armazenamento vem incluído no seu plano, e não há taxas de transferência: você só paga pelo que fica armazenado acima da cota.

### Armazenamento incluído

Todo plano inclui armazenamento sem custo adicional, e ele cresce junto com o plano:

| Plano | Armazenamento incluído |
| - | - |
| Hobby-1 | **5 GB** |
| Hobby-2 | **15 GB** |
| Standard-4 | **30 GB** |
| Standard-6 | **50 GB** |
| Standard-8 | **100 GB** |
| Pro-12 | **200 GB** |
| Pro-16 em diante, incluindo Enterprise | **250 GB** |

### Ao atingir sua cota

Quando o seu uso atinge a cota incluída, **novos uploads são recusados** com `STORAGE_QUOTA_EXCEEDED` até você liberar espaço ou fazer upgrade do plano. Tudo o que já está armazenado continua sendo servido normalmente. O armazenamento mantido **acima** da cota (por exemplo, após um downgrade de plano) custa:

<Card title="Armazenamento acima da cota" icon="coins">
  **R\$ 0,20 por GiB iniciado** além da sua cota incluída.
</Card>

<Info>O [Account Stats](/pt-br/blob-reference/endpoint/stats) informa o seu uso atual, a média deste mês e o custo estimado de qualquer armazenamento mantido além da cota.</Info>

<Info>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.</Info>

### 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:

| Recurso | Disponível em |
| - | - |
| Regras por prefixo | **5** no Hobby e no Standard, **10** no Pro, **20** no Enterprise |
| Uploads sem o limite de 1 por segundo | Pro e Enterprise |
| Metadados personalizados (até 5 chaves, 512 bytes) | Pro e Enterprise |
| Links de compartilhamento protegidos por senha | Pro e Enterprise |
| Expirações e exclusão automática abaixo de 7 dias (a partir de 1 hora) | Enterprise |
| Arquivos servidos sem cache no edge (`no-cache`) | Enterprise |

## 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](/pt-br/blob-reference/endpoint/download), de um [link de compartilhamento](/pt-br/blob-reference/endpoint/shares-create), da API ou do [gateway S3](/pt-br/blob-reference/s3-compatibility).
* Arquivos legados, enviados antes da atualização de setembro de 2026, mantêm o id original `<user_id>/<path>`, e toda rota aceita esse id. A URL original em `https://public-blob.squarecloud.dev/<user_id>/<path>` continua funcionando por **30 dias, até 25 de outubro de 2026**: mova esses arquivos com [Object Copy](/pt-br/blob-reference/endpoint/copy) (`move: true`) para ganhar uma URL em `blob.squarecloud.dev`.

Leia [Links e compartilhamento](/pt-br/blob-reference/links-and-sharing) 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`.

<Warning>
  **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.
</Warning>

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

<Frame>
  <img src="https://cdn.squarecloud.app/docs/services/blob-global-latency-test.webp" alt="Benchmark de latência global do Blob Storage" style={{ borderRadius: "0.5rem" }} />
</Frame>

<Info>**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.</Info>
<Warning>**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**.</Warning>

## Como hospedar seus arquivos

<Steps>
  <Step title="Obtenha uma chave de API">
    Crie uma chave de API com o escopo `blob:write` nas [configurações da sua conta](https://squarecloud.app/pt-br/account/security). Veja [Autenticação](/pt-br/blob-reference/authentication).
  </Step>

  <Step title="Faça o upload">
    Envie arquivos de até **100 MB** para o [Envio de Objeto](/pt-br/blob-reference/endpoint/post). Arquivos maiores, até **10 GiB**, passam pelo [fluxo de upload em partes](/pt-br/blob-reference/endpoint/chunked-init). Prefere ferramentas S3? Aponte-as para o [gateway S3](/pt-br/blob-reference/s3-compatibility).
  </Step>

  <Step title="Sirva os arquivos">
    Use a `url` da resposta para arquivos públicos, ou crie um [link temporário](/pt-br/blob-reference/endpoint/download) ou um [link de compartilhamento](/pt-br/blob-reference/endpoint/shares-create) para os privados.
  </Step>
</Steps>

Para um primeiro upload e download com curl, siga o [início rápido da API do Blob Storage](/pt-br/blob-reference/quickstart).

<Tip>
  Usando JavaScript? O [SDK de Blob](/pt-br/sdks/blob/client) (`@squarecloud/blob`) cuida para você dos uploads simples e multipart, links, compartilhamentos, regras e do gateway S3, no Node.js e no navegador.
</Tip>

## Perguntas frequentes

<AccordionGroup>
  <Accordion title="Qual plano eu preciso para usar o Blob Storage?">
    O Blob Storage está disponível em qualquer **plano**, a partir do Hobby, cada um com sua própria cota de armazenamento incluída (veja a tabela acima). Veja [Planos e Preços](/pt-br/platform/plans) para a comparação completa.
  </Accordion>

  <Accordion title="O que acontece quando eu atinjo minha cota de armazenamento incluída?">
    Novos uploads são recusados com `STORAGE_QUOTA_EXCEEDED` até você excluir objetos ou fazer upgrade do plano. Tudo o que já está armazenado continua sendo servido normalmente. O armazenamento mantido acima da cota (por exemplo, após um downgrade) custa **R\$ 0,20 por GiB iniciado**, e o [Account Stats](/pt-br/blob-reference/endpoint/stats) mostra a estimativa a qualquer momento.
  </Accordion>

  <Accordion title="Link temporário ou link de compartilhamento?">
    Um [link temporário](/pt-br/blob-reference/endpoint/download) vale por **até 24 horas** e **não pode ser revogado**: use-o para entregar um arquivo a um usuário agora. Um [link de compartilhamento](/pt-br/blob-reference/endpoint/shares-create) dura **até 30 dias**, **pode ser revogado**, pode limitar o número de downloads e, no Pro e no Enterprise, pode pedir uma senha. Veja [Links e compartilhamento](/pt-br/blob-reference/links-and-sharing).
  </Accordion>

  <Accordion title="Posso usar ferramentas S3?">
    Sim. O [gateway S3](/pt-br/blob-reference/s3-compatibility) 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](/pt-br/blob-reference/endpoint/s3-credentials): ele é derivado da sua chave de API, então revogar a chave revoga o par.
  </Accordion>

  <Accordion title="Quais recursos dependem do plano?">
    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.
  </Accordion>

  <Accordion title="As URLs antigas dos meus arquivos continuam funcionando?">
    Por 30 dias. Arquivos legados, enviados antes da atualização de setembro de 2026, mantêm a URL em `public-blob.squarecloud.dev` até **25 de outubro de 2026**, e o id `<user_id>/<path>` continua valendo em toda rota. Para manter um link público depois disso, mova o arquivo com [Object Copy](/pt-br/blob-reference/endpoint/copy) (`move: true`): arquivos novos são servidos a partir de `blob.squarecloud.dev/pub/...`, e o id deles começa com `pub/` ou `prv/`.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.