Documentação da API

Introdução

Bem-vindo à documentação da API Brizo. Nossa API RESTful oferece acesso programático para enviar, gerenciar e distribuir arquivos pela infraestrutura CDN global.

URL base

Todas as chamadas devem usar: https://api.brizo.com/v1

URL base

Base URL

https://api.brizo.com/v1

Autenticação

Todas as requisições exigem autenticação com chave API. Inclua sua chave no cabeçalho X-API-Key de cada chamada.

Obtendo uma chave API

Faça login no painel Brizo
Acesse a seção Chaves API
Clique em 'Gerar nova chave' e dê um nome descritivo

Usando sua chave API

Inclua a chave no cabeçalho de cada requisição:

HTTP Header

X-API-Key: your_api_key_here

Alerta de segurança

Nunca exponha chaves API em código client-side ou repositórios públicos. Trate-as como senhas.

Início rápido

Veja um exemplo completo de upload usando a API Brizo:

JavaScript / Node.js

const FormData = require('form-data');
const fs = require('fs');
const fetch = require('node-fetch');

async function uploadFile(filePath) {
    // Step 1: Get presigned URL
    const fileStats = fs.statSync(filePath);
    const presignResponse = await fetch('https://api.brizo.com/v1/upload/presign', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'X-API-Key': 'your_api_key_here'
        },
        body: JSON.stringify({
            filename: 'example.jpg',
            fileType: 'image/jpeg',
            size: fileStats.size
        })
    });

    const { url, key } = (await presignResponse.json()).data;

    // Step 2: Upload to presigned URL
    const fileBuffer = fs.readFileSync(filePath);
    await fetch(url, {
        method: 'PUT',
        headers: { 'Content-Type': 'image/jpeg' },
        body: fileBuffer
    });

    // Step 3: Complete upload
    const completeResponse = await fetch('https://api.brizo.com/v1/upload/complete', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'X-API-Key': 'your_api_key_here'
        },
        body: JSON.stringify({
            key,
            filename: 'example.jpg',
            size: fileStats.size,
            type: 'image/jpeg'
        })
    });

    return await completeResponse.json();
}

uploadFile('./my-image.jpg')
    .then(console.log)
    .catch(console.error);

Upload de arquivos

POST /upload/presign

Solicite uma URL pré-assinada para iniciar o upload. Esse é o primeiro passo do fluxo.

Corpo da requisição

Parâmetro	Tipo	Obrigatório	Descrição
`filename`	string	✅	Nome original do arquivo
`fileType`	string	✅	Tipo MIME (ex.: 'image/jpeg', 'video/mp4')
`size`	number	✅	Tamanho em bytes

Resposta

JSON

{
  "status": "success",
  "data": {
    "url": "https://storage.brizo.com/presigned-url...",
    "key": "user_id/uuid.jpg",
    "method": "PUT",
    "headers": {
      "Content-Type": "image/jpeg"
    }
  }
}

POST /upload/complete

Finalize o processo e registre o arquivo na Brizo após enviar para a URL pré-assinada.

Corpo da requisição

Parâmetro	Tipo	Obrigatório	Descrição
`key`	string	✅	Chave retornada pelo endpoint de pré-assinatura
`filename`	string	✅	Nome original
`size`	number	✅	Tamanho em bytes
`type`	string	✅	Tipo MIME

Resposta

JSON

{
  "status": "success",
  "data": {
    "file": {
      "id": "abc123def456",
      "originalName": "example.jpg",
      "name": "user_id/uuid.jpg",
      "size": 1024000,
      "mimeType": "image/jpeg",
      "publicId": "a1b2c3d4e5f6g7h8",
      "downloads": 0,
      "created": "2025-11-23T12:00:00.000Z"
    }
  }
}

Gerenciar arquivos

GET /files

Recupere uma lista paginada de todos os arquivos da conta.

Parâmetros de consulta

Parâmetro	Tipo	Descrição
`page`	number	Número da página (padrão: 1)
`perPage`	number	Resultados por página (padrão: 30, máx: 100)

GET /files/:id

Obtenha detalhes de um arquivo específico por ID.

GET /files/public/:publicId

Acesse um arquivo usando o ID público. Não requer autenticação e serve para entrega pública.

Acesso público

Endpoint pensado para entrega CDN pública, sem autenticação.

Aviso de desempenho

Entrega otimizada através da nossa infraestrutura CDN global.

DELETE /files/:id

Exclua um arquivo de forma permanente. Esta ação não pode ser desfeita.

Gestão de chaves API

GET /api-keys

Liste todas as chaves associadas à sua conta.

POST /api-keys

Gere uma nova chave API para acesso programático.

Corpo da requisição

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	✅	Nome descritivo para a chave (ex.: 'Servidor de produção', 'Desenvolvimento')

DELETE /api-keys/:id

Revogue uma chave API. Ela será invalidada imediatamente.

Armazenamento S3

API compatível com S3 para gerenciar arquivos usando qualquer cliente ou SDK.

Compatibilidade

Funciona com PocketBase, rclone, s5cmd, AWS CLI, MinIO Client, Cyberduck e outros.

Configurações de conexão

Parâmetro	Valor
`Endpoint`	`https://api.brizo-cloud.com/s3`
`Bucket`	`brizo`
`Region`	`auto`
`Force Path Style`	`true`

Como obter credenciais

Faça login no painel Brizo
Vá até "Armazenamento S3"
Clique em "Gerar credenciais" para criar Access Key e Secret Key
Guarde a Secret Key em segurança (aparece apenas uma vez)

Exemplo: PocketBase

Configure o PocketBase para usar a Brizo como armazenamento S3:

PocketBase Settings

Endpoint: https://api.brizo-cloud.com/s3
Bucket: brizo
Region: auto
Access Key: YOUR_ACCESS_KEY_ID
Secret: YOUR_SECRET_ACCESS_KEY
Force Path Style: ✓ (enabled)

Exemplo: rclone

~/.config/rclone/rclone.conf

[brizo]
type = s3
provider = Other
env_auth = false
access_key_id = YOUR_ACCESS_KEY_ID
secret_access_key = YOUR_SECRET_ACCESS_KEY
endpoint = https://api.brizo-cloud.com/s3
acl = private

Operações suportadas

Operação	Descrição
`PutObject`	Enviar arquivos
`GetObject`	Baixar arquivos
`DeleteObject`	Excluir arquivos
`HeadObject`	Buscar metadados
`ListObjectsV2`	Listar arquivos
`CopyObject`	Copiar arquivos

SDK Node.js NOVO

Nosso SDK oficial de Node.js oferece uma forma simples e poderosa de integrar a Brizo às suas aplicações.

Ver documentação completa no GitHub

https://github.com/devAlphaSystem/Alpha-System-Brizo-SDK

Instalação

npm

npm install @alphasystem/brizo-sdk

Início rápido

JavaScript

const { BrizoClient } = require('@alphasystem/brizo-sdk');

// Initialize the client
const brizo = new BrizoClient({
    apiKey: 'your_api_key_here'
});

// Upload a file
const file = await brizo.files.upload('./my-image.jpg');
console.log('Uploaded:', file.publicId);

// List all files
const files = await brizo.files.list();
console.log('Files:', files);

// Create a folder
const folder = await brizo.folders.create('my-folder');

// Get S3 credentials
const credentials = await brizo.s3Credentials.create('my-app');
console.log('S3 Access Key:', credentials.accessKeyId);

Recursos

Upload e gestão de arquivos
Operações com pastas
Gerenciamento de credenciais S3
Suporte completo a TypeScript

Limites de tamanho de arquivo

A Brizo impõe os seguintes limites para garantir desempenho e confiabilidade.

Interface	Operação	Tamanho máximo
Web Dashboard	Upload	`10 GB`
REST API	Upload (presigned URL)	`10 GB`
S3-Compatible API	PutObject	`5 GB` *
All Interfaces	Download	Ilimitado **

* O limite PutObject do S3 é 5 GB por requisição. Use upload multipart para arquivos maiores.

** Downloads são limitados pela cota mensal de banda do seu plano, não por arquivo individual.

Limites de payload

Corpos de requisição são limitados para prevenir abuso:

Endpoint	Payload máximo
`/v1/auth/*`	`10 KB`
`/v1/*` (default)	`1 MB`
`/s3/*`	`5 GB`

Limites e cotas

Os limites dependem do seu plano. Acompanhe o uso no painel para evitar atingir o teto.

Plano	Requisições API	Armazenamento	Largura de banda
Free	50,000/month	2 GB	20 GB
Lite	1,000,000/month	10 GB	1 TB
Starter	5,000,000/month	50 GB	5 TB
Developer	20,000,000/month	200 GB	Unlimited
Pro	100,000,000/month	1 TB	Unlimited
Business	Unlimited	5 TB	Unlimited

Ao se aproximar dos limites, enviaremos alertas. Exceder pode resultar em throttling ou suspensão temporária.

Tratamento de erros

A API Brizo usa códigos HTTP convencionais para indicar sucesso ou falha:

Código	Significado
`400`	Bad Request - Parâmetros inválidos
`401`	Unauthorized - Chave API inválida ou ausente
`403`	Forbidden - Permissões insuficientes ou quota excedida
`404`	Not Found - Recurso não existe
`429`	Too Many Requests - Limite excedido
`500`	Internal Server Error - Problema do nosso lado

Formato da resposta de erro

JSON

{
  "status": "error",
  "message": "Invalid API key",
  "code": 401
}

Exemplos de código

Exemplo em Python

Python

import requests
import os

API_KEY = 'your_api_key_here'
BASE_URL = 'https://api.brizo.com/v1'

def upload_file(file_path):
    # Get file info
    file_size = os.path.getsize(file_path)
    file_name = os.path.basename(file_path)
    
    # Step 1: Get presigned URL
    presign_response = requests.post(
        f'{BASE_URL}/upload/presign',
        headers={'X-API-Key': API_KEY},
        json={
            'filename': file_name,
            'fileType': 'image/jpeg',
            'size': file_size
        }
    )
    data = presign_response.json()['data']
    
    # Step 2: Upload file
    with open(file_path, 'rb') as f:
        requests.put(data['url'], data=f, headers=data['headers'])
    
    # Step 3: Complete upload
    complete_response = requests.post(
        f'{BASE_URL}/upload/complete',
        headers={'X-API-Key': API_KEY},
        json={
            'key': data['key'],
            'filename': file_name,
            'size': file_size,
            'type': 'image/jpeg'
        }
    )
    
    return complete_response.json()

# Usage
result = upload_file('./my-image.jpg')
print(result)

Exemplos em cURL

Bash / cURL

# List files
curl -X GET "https://api.brizo.com/v1/files" \
  -H "X-API-Key: your_api_key_here"

# Delete a file
curl -X DELETE "https://api.brizo.com/v1/files/file_id_here" \
  -H "X-API-Key: your_api_key_here"