Storage

Nuvem Storage es un almacenamiento de objetos compatible con S3 que corre sobre Cloudflare R2. Sin egress fees, con CDN global incluido.

Endpoints

Subir archivo

# Upload directo (multipart/form-data)
POST /v1/storage/upload
Authorization: Bearer <api_key>
Content-Type: multipart/form-data

# Body: form field "file" con el archivo
curl -X POST https://api.nuvem-latam.com/v1/storage/upload \
  -H "Authorization: Bearer $NUVEM_API_KEY" \
  -F "file=@foto.jpg" \
  -F "path=avatars/usuario123.jpg"

Respuesta:

{
  "id": "file_abc123",
  "name": "usuario123.jpg",
  "path": "avatars/usuario123.jpg",
  "contentType": "image/jpeg",
  "size": 102400,
  "url": "https://cdn.nuvem-latam.com/avatars/usuario123.jpg",
  "createdAt": "2026-04-12T00:00:00.000Z"
}

Listar archivos

GET /v1/storage/files?prefix=avatars/&page=1&pageSize=20
Authorization: Bearer <api_key>

Obtener archivo

GET /v1/storage/files/:fileId
Authorization: Bearer <api_key>

Generar presigned URL

POST /v1/storage/presigned-url
Authorization: Bearer <api_key>
{
  "path": "uploads/documento.pdf",
  "operation": "put",
  "expiresIn": 3600
}

Respuesta:

{
  "url": "https://api.nuvem-latam.com/v1/storage/presigned/...",
  "expiresAt": "2026-04-12T01:00:00.000Z"
}

Eliminar archivo

DELETE /v1/storage/files/:fileId
Authorization: Bearer <api_key>

SDK

JavaScript

import { createClient } from '@nuvem/js';

const nuvem = createClient({ apiKey: process.env.NUVEM_API_KEY! });

// Subir desde el browser (File API)
const file = document.querySelector('input[type="file"]').files[0];
const uploaded = await nuvem.storage.upload(file, { path: 'avatars/user123.jpg' });
console.log(uploaded.url);

// Listar archivos
const { data } = await nuvem.storage.list({ prefix: 'avatars/' });

// Generar presigned URL para upload desde el cliente
const { url } = await nuvem.storage.getPresignedUrl({
  path: 'uploads/doc.pdf',
  operation: 'put',
  expiresIn: 3600,
});

Límites

Plan	Tamaño máximo por archivo	Almacenamiento total
Free	10 MB	1 GB
Builder	100 MB	50 GB
Scale	5 GB	Ilimitado

Errores comunes

Código	Mensaje	Causa
file_too_large	El archivo excede el límite	Supera el límite del plan
file_not_found	El archivo no existe	ID inválido
invalid_content_type	Tipo de archivo no permitido	Tipo bloqueado por configuración