Vistoria Cloud API (Getting started)

Vistoria provides object storage similar to S3 or Backblaze, but designed to be simpler, leaner, and more affordable — perfect for developers who want to move fast without the overhead.

Step 1: Get Your API Key

To access the API, you'll need your personal API key.

1. Go to vistoria.cloud/account and log in to your account. If you don't have an account yet, you can quickly register here and then log in. After logging in, you will be automatically redirected to your dashboard. On the left-hand side of the dashboard, you’ll see a sidebar menu (as shown in the images below) where you can navigate to different sections like Files, Webhooks, and more.

2. Your API key will be available there under your account details.

Step 2: Upload a File

Use the API to upload images, videos, and documents. Max size: 50MB per file.

Note: The current 50MB limit ensures stability and quick uploads for all users. As Vistoria continues to grow and our infrastructure evolves, we plan to support larger file uploads in the future. Stay tuned!

Endpoint

POST https://api.vistoria.cloud/file/upload

Example Code (JavaScript)

async function uploadFile(filePath, apiKey) {
  const formData = new FormData();
  formData.append('file', filePath);

  const response = await fetch('https://api.vistoria.cloud/file/upload', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`
    },
    body: formData
  });

  const result = await response.json();
  console.log("File uploaded:", result.url);
  return result;
}

Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: Handled automatically via FormData

Body Parameters

file (required):The file to upload. The form key must be exactly named file.Uploads with a different key name will be rejected.

Successful Response

{
  "success": true,
  "message": "Files uploaded successfully.",
  "data": {
    "id": "18c068a9-f0c3-43e2-b26c-114c7b2a09c8",
    "filename_disk": "18c068a9-f0c3-43e2-b26c-114c7b2a09c8.jpg",
    "filename_download": "friends season 4 bluray.jpg",
    "title": "Friends Season 4 Bluray",
    "type": "image/jpeg",
    "filesize": "436781",
    "width": 600,
    "height": 600,
    "uploaded_on": "2025-04-26T11:00:48.908Z",
    "url": "https://api.vistoria.cloud/file/18c068a9-f0c3-43e2-b26c-114c7b2a09c8"
  }
}

Error Response

{
  "error": true,
  "message": "Invalid or expired API key."
}

Webhooks

You can register a Webhook URL to automatically receive notifications when file uploads complete or fail.

How It Works

You provide a Webhook URL via the dashboard or API.
When an upload is completed or failed, Vistoria sends a POST request to your URL.
The POST body contains event information and file details.

Example Payload

{
  "id": "18cab90c-5adb-4d33-9d09-7c81b54660fd",
  "date_created": "2025-04-28T13:06:21.422Z",
  "payload": {
    "id": "98af2d2d-779a-49a4-b1d7-db0b829c6026",
    "filename_disk": "98af2d2d-779a-49a4-b1d7-db0b829c6026.m3u8",
    "filename_download": "1080p (1).m3u8",
    "title": "1080p (1)",
    "type": "application/vnd.apple.mpegurl",
    "url": "https://api.vistoria.cloud/file/98af2d2d-779a-49a4-b1d7-db0b829c6026"
  },
  "event": "upload.completed",
  "user": "d0534b40-930c-4546-8d9c-69f651360a67"
}

Note: The payload field is a JSON string containing file details. You should parse it in your backend if needed.

Image Transformations

Easily transform images on the fly using URL parameters. You can resize, adjust quality, change formats, and apply advanced effects.

width: Set image width (in pixels).
height: Set image height (in pixels).
quality: Set image quality (1 to 100).
fit: Choose how the image should fit (`fill`, `contain`, `cover`, `inside`, `outside`).
format: Choose image format (`jpg`, `png`, `webp`, `auto`).
transforms: Apply advanced transformations like rotate, blur, flip, and tint.

Example URL:

https://api.vistoria.cloud/file/91f74629-2df9-4cd1-bdfb-50f9c7bf7174?width=500&height=500&quality=80&fit=fill&format=webp

This resizes the image to 500x500px, sets quality to 80, and converts it to WebP format.

Advanced Transformations Example:

https://api.vistoria.cloud/file/91f74629-2df9-4cd1-bdfb-50f9c7bf7174?transforms=[["rotate",90],["blur",10],["tint","rgb(255,0,255)"]]&width=500&height=500

This applies a 90° rotation, 10px blur, and a purple tint to the image, resizing it to 500x500px.

Cheers 🎉

Thanks for checking out Vistoria! This project is built with side-project love, and I hope it helps you ship faster and have fun building. If you have any feedback, suggestions, or run into any issues while using it, feel free to reach out to me directly:

Email: [email protected]
GitHub: github.com/jkitsao