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.

Nota: para arquivos que seu serviço precisa ler do filesystem diretamente, use Volumes. Blob Storage é para arquivos servidos publicamente via CDN.

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.

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), 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>). Você pode adicionar domínios customizados na aba Domínios, com TLS provisionado automaticamente, e configurar regras de CORS na aba CORS.