Dokumentacja VirtualDrive Cloud

Magazyn obiektowy dla programistów i agentów AI. Dodaj magazyn plików do dowolnej aplikacji w kilka minut.

Szybki start

Utwórz projekt w panelu, wygeneruj klucz API, a następnie zainstaluj SDK:

npm install @virtualdrive/cloud

import { VirtualDrive } from "@virtualdrive/cloud";

const vd = new VirtualDrive(process.env.VD_API_KEY);

const file = await vd.files.upload({ name: "hello.txt", data: "hi!" });
console.log(file.url);

Uwierzytelnianie

Every request authenticates with a project API key sent as a Bearer token. Keys are scoped to a single project and a set of permissions (files:read, files:write, files:delete). Keys are shown once at creation — store them as a secret.

Authorization: Bearer vdk_live_xxxxxxxxxxxxxxxx

Wysyłanie pliku

Wyślij bajty bezpośrednio albo poproś o wstępnie podpisany adres URL do dużych wysyłek lub wysyłek prosto z przeglądarki.

curl https://api.virtualdrive.cloud/v1/files \
  -H "Authorization: Bearer $VD_API_KEY" \
  -F "name=report.pdf" \
  -F "file=@report.pdf"

Pobieranie i podpisane adresy URL

Każdy plik można serwować krótko żyjącym podpisanym adresem URL. Domyślnie nic nie jest publiczne.

const { url } = await vd.files.signedUrl(fileId, { expiresIn: 3600 });

Listowanie i usuwanie

const { files } = await vd.files.list({ prefix: "invoices/" });
await vd.files.delete(fileId);

Przykłady dla frameworków

Kilka popularnych integracji. Wszystkie korzystają z SDK dla JS; trzymaj klucz po stronie serwera.

Next.js — obsługa trasy

// app/api/upload/route.ts
import { VirtualDrive } from "@virtualdrive/cloud";
const vd = new VirtualDrive(process.env.VD_API_KEY!);

export async function POST(req: Request) {
  const form = await req.formData();
  const file = form.get("file") as File;
  const stored = await vd.files.upload({
    name: file.name,
    data: await file.arrayBuffer(),
    contentType: file.type,
  });
  return Response.json({ url: stored.url });
}

Express

import express from "express";
import { VirtualDrive } from "@virtualdrive/cloud";
const vd = new VirtualDrive(process.env.VD_API_KEY);

app.post("/upload", async (req, res) => {
  const file = await vd.files.upload({ name: req.body.name, data: req.body.data });
  res.json({ url: file.url });
});

Swift (iOS / macOS)

import VirtualDrive

let vd = VirtualDrive(apiKey: ProcessInfo.processInfo.environment["VD_API_KEY"]!)
let file = try await vd.files.upload(name: "photo.jpg", data: imageData, contentType: "image/jpeg")
print(file.url)

Swift Package: add this repo's sdk-swift via Swift Package Manager (iOS 15+ / macOS 12+). Keep the key server-side for shipped apps; use a short-lived key or proxy for clients.

Przeglądarka

Nigdy nie umieszczaj klucza API w przeglądarce. Wysyłaj przez własny serwer (przykłady powyżej) albo pozwól serwerowi zwrócić podpisany adres URL do użycia po stronie klienta.

Serwer MCP

Podłącz dowolnego agenta AI do swojego magazynu przez Model Context Protocol. Skieruj klienta MCP na hostowany punkt końcowy z kluczem projektu albo uruchom lokalną nakładkę:

npx @virtualdrive/mcp --key $VD_API_KEY

# Tools exposed: list_files, read_file, write_file, delete_file

LLM-readable API summary: /developers/llms.txt

Webhooki

Register an endpoint in the dashboard to receive events: file.uploaded, file.deleted. Each delivery is a POST with an HMAC-SHA256 signature so you can verify it came from us.

// Headers on every delivery:
//   X-VD-Event: file.uploaded
//   X-VD-Signature: sha256=<hex>
// Verify (Node):
import crypto from "crypto";
const sig = "sha256=" + crypto.createHmac("sha256", WHSEC).update(rawBody).digest("hex");
if (sig !== req.headers["x-vd-signature"]) throw new Error("bad signature");

// Body: { "event": "file.uploaded", "created": "...",
//         "data": { "id": "...", "name": "...", "size": 1234 } }

Błędy i limity

Standard HTTP status codes. 401 invalid key · 403 scope/quota · 413 file too large · 429 rate limited · 503 service paused. Usage is metered per project (stored bytes + requests); a generous free tier is included at launch.