API de armazenamento de objetos
Armazenamento de objetos compatível com S3. Emita credenciais separadas por bucket, conecte qualquer SDK S3 diretamente e não pague pela saída de dados nas leituras.
- Credenciais: Access Key / Secret Key emitidos por bucket e válidos apenas para ele; o segredo aparece uma vez, e uma nova chave leva cerca de um minuto para ativar
- Configuração do SDK: a região é sempre auto, com endereçamento virtual-host; exemplos Node.js / Python / Go / PHP / aws-cli
- CORS: necessário antes de o navegador enviar ou ler diretamente; a origem deve ser um domínio concreto, nunca um curinga
- URLs pré-assinadas: uploads e downloads podem ser pré-assinados, permitindo fornecer ao navegador um link temporário em vez de uma chave
- Limites e preços: 5 GiB por PUT único e até 10000 partes multipart; o armazenamento é cobrado pelo uso diário efetivo, e exclusões e saída de dados são gratuitas
Visão geral
Armazenamento de objetos compatível com S3. Gere credenciais por bucket, use-as em qualquer SDK S3 e não pague pelo tráfego de saída.
Sua configuração existente de aws-sdk, boto3, s3cmd ou rclone funciona sem alterações — substitua o endpoint e defina a região como auto.
Credenciais
Gere-as por bucket em Armazenamento de objetos → Buckets → Chaves. Cada credencial fica restrita ao bucket e não pode acessar os demais.
- Endpoint — Endpoint S3, por exemplo https://<account>.r2.cloudflarestorage.com
- Bucket — O nome real do bucket (com prefixo da plataforma, diferente do apelido escolhido)
- Access Key ID — Access Key ID
- Secret Access Key — Secret Access Key — exibida apenas uma vez, na criação
- Region — Sempre auto. Usar us-east-1 ou similar invalida a assinatura, e todas as requisições retornam 403 SignatureDoesNotMatch
Uma credencial recém-gerada leva cerca de um minuto para chegar à borda do armazenamento; até lá, as chamadas retornam 401 Unauthorized. Isso não significa que a chave está errada — aguarde e tente novamente. É um erro fácil de interpretar incorretamente na primeira integração.
Nunca armazenamos a Secret Access Key, portanto não é possível recuperá-la depois de fechar o diálogo. Se perdê-la, será necessário excluir a chave e gerar outra, interrompendo a integração em uso nesse intervalo — salve-a imediatamente no seu gerenciador de segredos.
Configuração do SDK
Insira os quatro valores do console no SDK S3 que você já usa.
Use endereçamento por host virtual (o padrão); não habilite o estilo por caminho. Uma configuração incorreta causa 404 / NoSuchBucket, parecendo um erro de digitação no nome do bucket.
CORS
O navegador não pode acessar o bucket diretamente (envios ou leituras pelo frontend) até que o CORS esteja configurado — a requisição é bloqueada antes de ser enviada, gerando um erro de CORS no console e nenhum registro no servidor. Configure em Buckets → Configurações → CORS.
Uma origem curinga permite que qualquer site leia e grave neste bucket usando as credenciais dos seus visitantes, sem deixar um histórico de acesso que você possa consultar. Liste domínios específicos.
URLs pré-assinadas
Forneça URLs com validade limitada ao navegador em vez de enviar credenciais ao frontend. Tanto uploads quanto downloads podem usar URLs pré-assinadas, mantendo os arquivos grandes fora dos seus servidores.
Limites
- 5 GiB por PUT único; use upload multipart para arquivos maiores
- Até aproximadamente 4,995 TiB por objeto via multipart, com no máximo 10.000 partes
- Chaves de objeto com até 1024 bytes
- Uma gravação simultânea por segundo na mesma chave de objeto
Preços
Sem custo adicional dentro da franquia do plano; acima dela, aplicam-se as tarifas abaixo.
- Armazenamento — $0.03 / GB·mês — Cobrado pelo uso diário real, não pelo pico
- $9.00 / 1M — Operações de gravação e listagem (PutObject, ListObjects, multipart, …)
- $0.72 / 1M — Operações de leitura (GetObject, HeadObject, …)
- Tráfego de saída — Grátis — Leituras não têm custo de banda — a maior diferença de custo em relação ao armazenamento de objetos tradicional
- Exclusões — Grátis — Excluir objetos ou buckets e interromper uploads multipart é gratuito
O custo por GB é menor, mas há retenção mínima de 30 dias (excluir antes ainda gera cobrança de 30 dias) e uma tarifa de recuperação em cada leitura. Em um bucket lido diariamente, a conta aumenta em vez de diminuir — essa opção é indicada para arquivos e backups, com gravações frequentes e leituras raras.
Perguntas frequentes
Por que uma credencial recém-emitida continua retornando 401?
Uma nova credencial leva cerca de um minuto para chegar aos nós de armazenamento, e chamadas nesse intervalo retornam 401 Unauthorized. Não significa chave incorreta — aguarde um pouco e tente novamente. É um erro fácil de interpretar incorretamente na primeira integração.
Qual região devo usar e o que causa SignatureDoesNotMatch?
A região é sempre auto. Usar us-east-1 ou algo parecido invalida a assinatura, e todas as solicitações retornam 403 SignatureDoesNotMatch. Mantenha também o endereçamento virtual-host e não ative path-style — esse erro aparece como 404 NoSuchBucket.
Páginas relacionadas: Documentação da API · Serviços em nuvem Tovanix · Usar domínios
Carregando…