Blob Storage

Blob Storage guarda arquivos (imagens, uploads de usuários, assets) e os serve por uma CDN global. Cada blob store recebe um domínio dedicado, como meu-app.cdn.runveloz.com, e você envia objetos a partir do seu app com o SDK @onveloz/blob ou direto pela API REST.

Quando usar Blob Storage

Blob Storage é o lugar padrão para os arquivos do seu app: uploads de usuários, imagens, PDFs, exportações e assets gerados. Comparado a um Volume:

• funciona com qualquer número de instâncias, então o serviço continua escalando horizontalmente;
• os arquivos sobrevivem a deploys, reinícios e mudanças de tamanho sem nenhuma configuração;
• a entrega sai pela CDN, sem consumir CPU nem banda do seu serviço.

Use um Volume só quando um software exige um diretório no disco local, como um app que guarda um banco SQLite em arquivo. Para dados estruturados, prefira um banco de dados gerenciado.

Importante: todo objeto é público. Quem tiver a URL consegue baixar o arquivo, então não envie dados sensíveis sem criptografar. A API não lista nem lê objetos: guarde as chaves (uploads/foto.png) no seu banco de dados.

Criar um blob store

No dashboard, dentro do seu projeto, adicione um recurso Blob Store. Logo após criar, você verá o guia de início rápido com a sua primeira chave de API já gerada. Copie a chave nesse momento: por segurança, ela não é exibida novamente.

Pela CLI, ou pelo MCP com as ferramentas blob_*:

veloz blob create uploads
veloz env set VELOZ_BLOB_TOKEN=vbk_sua_chave

veloz blob create mostra a primeira chave uma única vez. Para gerar outra, use veloz blob key-create uploads <nome>.

Autenticação

Toda chamada à API usa uma chave vbk_* no cabeçalho Authorization:

Authorization: Bearer vbk_sua_chave

A chave é vinculada a um blob store específico e concede acesso de leitura e escrita a ele. Trate como senha: defina em variável de ambiente (VELOZ_BLOB_TOKEN) e nunca commite no Git. Gere e revogue chaves na aba Chaves de API do store.

Segurança: a chave de API só trafega no cabeçalho Authorization, nunca na URL. As URLs de upload contêm um parâmetro ?token= que é uma assinatura temporária gerada pelo servidor, não a sua chave.

SDK @onveloz/blob

A forma recomendada de integrar. Instale:

npm install @onveloz/blob

Defina o token no ambiente:

VELOZ_BLOB_TOKEN=vbk_sua_chave

Envie e remova arquivos:

import { put, del } from "@onveloz/blob";
 
// Lê VELOZ_BLOB_TOKEN do ambiente (ou passe { token }).
const blob = await put("uploads/foto.png", arquivo, {
  access: "public",
  contentType: "image/png",
});
 
console.log(blob.url); // https://meu-app.cdn.runveloz.com/uploads/foto.png
 
await del("uploads/foto.png");

put aceita string, Blob, ArrayBuffer, Uint8Array ou ReadableStream como corpo. Para apontar para outro ambiente, defina VELOZ_BLOB_API ou passe apiUrl em cada chamada.

Cliente com configuração fixa

import { BlobClient } from "@onveloz/blob";
 
const blob = new BlobClient({ token: process.env.VELOZ_BLOB_TOKEN });
await blob.put("uploads/foto.png", arquivo);
await blob.del("uploads/foto.png");

Erros

O SDK lança erros tipados: BlobAccessError (token ausente ou inválido, 401/403), BlobQuotaError (blob store sem espaço na cota, code blob/quota-exceeded), BlobUploadError (falha no envio) e BlobError (genérico, com code e status).

API REST

O SDK é só um cliente fino sobre esta API. A base é https://platform.onveloz.com.

1. Gerar URL de upload

POST /api/blob/v1/upload-url troca a sua chave de API por uma URL de upload assinada.

curl -X POST https://platform.onveloz.com/api/blob/v1/upload-url \
  -H "Authorization: Bearer $VELOZ_BLOB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key":"uploads/foto.png","contentType":"image/png"}'

Resposta:

{
  "uploadUrl": "https://meu-app.cdn.runveloz.com/uploads/foto.png?token=...&expires=...",
  "publicUrl": "https://meu-app.cdn.runveloz.com/uploads/foto.png",
  "expires": "1717000000",
  "key": "uploads/foto.png"
}

2. Enviar o arquivo

Faça um PUT direto na uploadUrl retornada. Essa URL já está assinada, então não leva o cabeçalho Authorization.

curl -X PUT "<uploadUrl>" \
  -H "Content-Type: image/png" \
  --data-binary @foto.png

Depois disso, o arquivo fica disponível na publicUrl.

3. Remover um objeto

DELETE /api/blob/v1/objects remove por chave. É idempotente: chaves inexistentes retornam sucesso.

curl -X DELETE "https://platform.onveloz.com/api/blob/v1/objects?key=uploads%2Ffoto.png" \
  -H "Authorization: Bearer $VELOZ_BLOB_TOKEN"

Acesso público

Os objetos são servidos pelo domínio CDN do store (https://<store>.cdn.runveloz.com/<key>). Domínios customizados e regras de CORS ainda não estão disponíveis para blob stores.

Custos

R$0,25/GB/mês, calculado proporcionalmente à hora sobre o espaço armazenado. Cada organização tem 1 GB grátis em todos os planos.

→ Veja a tabela de preços completa