VirtualDrive Cloud ドキュメント

開発者とAIエージェントのためのオブジェクトストレージ。どんなアプリにも数分でファイルストレージを追加できます。

クイックスタート

ダッシュボードでプロジェクトを作成し、APIキーを発行してから、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);

認証

すべてのリクエストは、Bearerトークンとして送られるプロジェクトAPIキーで認証します。キーは単一のプロジェクトと権限のセット（files:read、files:write、files:delete）にスコープされます。キーは作成時に一度だけ表示されます — シークレットとして保管してください。

Authorization: Bearer vdk_live_xxxxxxxxxxxxxxxx

ファイルをアップロード

バイト列を直接アップロードするか、大きなファイルやブラウザからの直接アップロードには事前署名付きURLをリクエストします。

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

ダウンロードと署名付きURL

すべてのファイルは、短命の署名付きURLで配信できます。デフォルトでは何も公開されません。

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

一覧と削除

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

フレームワーク例

よくある統合例をいくつか。いずれもJS SDKを使います。キーはサーバー側に保管してください。

Next.js — ルートハンドラー

// 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: このリポジトリの sdk-swift を Swift Package Manager 経由で追加します（iOS 15+ / macOS 12+）。出荷するアプリではキーをサーバー側に保管し、クライアントには短命キーかプロキシを使ってください。

ブラウザ

APIキーをブラウザに置いてはいけません。サーバー経由でアップロードするか（上記の例）、サーバーが署名付きURLを返してクライアントに使わせてください。

MCPサーバー

Model Context Protocol経由で、どんなAIエージェントもストレージに接続できます。MCPクライアントをプロジェクトキー付きでホスト型エンドポイントに向けるか、ローカルのシムを実行します。

npx @virtualdrive/mcp --key $VD_API_KEY

# Tools exposed: list_files, read_file, write_file, delete_file

LLMが読める形式のAPI概要: /developers/llms.txt

Webhook

ダッシュボードでエンドポイントを登録すると、イベント（file.uploaded、file.deleted）を受け取れます。各配信はHMAC-SHA256署名付きのPOSTなので、当社からのものであることを検証できます。

// 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 } }

エラーと制限

標準的なHTTPステータスコードを使います。401 無効なキー · 403 スコープ／クォータ · 413 ファイルが大きすぎる · 429 レート制限 · 503 サービス一時停止。使用量はプロジェクト単位で計測されます（保存バイト数＋リクエスト数）。ローンチ時には手厚い無料枠が含まれます。