google-veo3-1-mcp-server 1.0.0

package/dist/utils/video.js

@@ -0,0 +1,261 @@
+/**
+ * Video polling and download utilities for Veo 3.1 API
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { GEMINI_API_BASE_URL, DEFAULT_POLL_INTERVAL, DEFAULT_MAX_POLL_ATTEMPTS } from '../types/tools.js';
+import { debugLog, errorLog } from './debug.js';
+import { normalizeAndValidatePath, generateUniqueFilePath, ensureVideoExtension } from './path.js';
+/**
+ * Get API key from environment
+ */
+export function getApiKey() {
+    const apiKey = process.env.GOOGLE_API_KEY;
+    if (!apiKey) {
+        throw new Error('GOOGLE_API_KEY environment variable is not set');
+    }
+    return apiKey;
+}
+/**
+ * Check operation status
+ */
+export async function getOperationStatus(operationName, apiKey) {
+    // For Gemini API, the operation name format is different
+    // We need to construct the full URL based on the operation name
+    let url;
+    if (operationName.startsWith('http')) {
+        // Full URL provided
+        url = `${operationName}?key=${apiKey}`;
+    }
+    else if (operationName.startsWith('models/')) {
+        // Relative path from Gemini API
+        url = `${GEMINI_API_BASE_URL}/${operationName}?key=${apiKey}`;
+    }
+    else {
+        // Assume it's just the operation ID or full path
+        url = `${GEMINI_API_BASE_URL}/${operationName}?key=${apiKey}`;
+    }
+    debugLog('Checking operation status', { url: url.replace(apiKey, '***') });
+    const response = await fetch(url, {
+        method: 'GET',
+        headers: {
+            'Content-Type': 'application/json'
+        }
+    });
+    if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`Failed to get operation status: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+    const result = await response.json();
+    debugLog('Operation status response', result);
+    return result;
+}
+/**
+ * Poll for video generation completion
+ */
+export async function pollVideoResult(operationName, apiKey, pollInterval = DEFAULT_POLL_INTERVAL, maxAttempts = DEFAULT_MAX_POLL_ATTEMPTS) {
+    debugLog(`Starting poll for operation: ${operationName}`);
+    let attempts = 0;
+    while (attempts < maxAttempts) {
+        attempts++;
+        debugLog(`Poll attempt ${attempts}/${maxAttempts}`);
+        try {
+            const status = await getOperationStatus(operationName, apiKey);
+            if (status.error) {
+                // Operation completed with error
+                errorLog('Operation failed', status.error);
+                return status;
+            }
+            if (status.done) {
+                // Operation completed successfully
+                debugLog('Operation completed', status);
+                return status;
+            }
+            // Still processing, wait before next poll
+            debugLog(`Operation still processing, waiting ${pollInterval}ms`);
+            await sleep(pollInterval);
+        }
+        catch (error) {
+            // Check for transient errors (5xx)
+            if (error instanceof Error && error.message.includes('5')) {
+                debugLog(`Transient error, retrying: ${error.message}`);
+                await sleep(pollInterval);
+                continue;
+            }
+            throw error;
+        }
+    }
+    throw new Error(`Polling timeout: operation did not complete after ${maxAttempts} attempts`);
+}
+/**
+ * Download video from URL
+ */
+export async function downloadVideo(url, apiKey) {
+    let downloadUrl = url;
+    // Add API key for Google API URLs
+    if (apiKey && url.includes('generativelanguage.googleapis.com')) {
+        const separator = url.includes('?') ? '&' : '?';
+        downloadUrl = `${url}${separator}key=${apiKey}`;
+    }
+    debugLog('Downloading video', { url: downloadUrl.replace(apiKey || '', '***') });
+    const response = await fetch(downloadUrl);
+    if (!response.ok) {
+        throw new Error(`Failed to download video: ${response.status} ${response.statusText}`);
+    }
+    const arrayBuffer = await response.arrayBuffer();
+    return Buffer.from(arrayBuffer);
+}
+/**
+ * Save video buffer to file
+ */
+export async function saveVideo(videoData, outputPath) {
+    // Ensure .mp4 extension
+    outputPath = ensureVideoExtension(outputPath);
+    // Normalize and validate path
+    const normalizedPath = normalizeAndValidatePath(outputPath);
+    // Generate unique path to avoid overwriting
+    const uniquePath = generateUniqueFilePath(normalizedPath);
+    debugLog('Saving video', { path: uniquePath });
+    // Handle base64 encoded data
+    if (typeof videoData === 'string') {
+        const buffer = Buffer.from(videoData, 'base64');
+        fs.writeFileSync(uniquePath, buffer);
+    }
+    else {
+        fs.writeFileSync(uniquePath, videoData);
+    }
+    return uniquePath;
+}
+/**
+ * Download video and save to file
+ */
+export async function downloadAndSaveVideo(url, base64Data, outputPath, apiKey) {
+    if (base64Data) {
+        // Use base64 data directly
+        return saveVideo(base64Data, outputPath);
+    }
+    if (url) {
+        // Download from URL (pass API key for Google API URLs)
+        const key = apiKey || process.env.GOOGLE_API_KEY;
+        const videoData = await downloadVideo(url, key);
+        return saveVideo(videoData, outputPath);
+    }
+    throw new Error('No video data available (neither URL nor base64 provided)');
+}
+/**
+ * Extract video from operation response
+ */
+export function extractVideoFromResponse(response) {
+    // Handle Gemini API response format
+    // Structure: response.generateVideoResponse.generatedSamples[].video.uri
+    const generateVideoResponse = response.response?.generateVideoResponse;
+    if (generateVideoResponse?.generatedSamples?.length) {
+        const video = generateVideoResponse.generatedSamples[0].video;
+        if (video) {
+            return {
+                url: video.uri,
+                base64: video.bytesBase64Encoded
+            };
+        }
+    }
+    // Fallback: Check for Vertex AI format (generatedVideos)
+    if (response.response?.generatedVideos?.length) {
+        const video = response.response.generatedVideos[0].video;
+        return {
+            url: video.uri,
+            base64: video.bytesBase64Encoded
+        };
+    }
+    return null;
+}
+/**
+ * Read image file and convert to base64
+ */
+export async function readImageAsBase64(imagePath) {
+    // Check if it's already base64 or a URL
+    if (imagePath.startsWith('data:')) {
+        // Extract base64 from data URL
+        const match = imagePath.match(/^data:[^;]+;base64,(.+)$/);
+        if (match) {
+            return match[1];
+        }
+        throw new Error('Invalid data URL format');
+    }
+    if (imagePath.startsWith('http://') || imagePath.startsWith('https://')) {
+        // Download image from URL
+        const response = await fetch(imagePath);
+        if (!response.ok) {
+            throw new Error(`Failed to fetch image: ${response.status}`);
+        }
+        const buffer = await response.arrayBuffer();
+        return Buffer.from(buffer).toString('base64');
+    }
+    if (imagePath.startsWith('gs://')) {
+        // GCS URI - return as-is for the API to handle
+        throw new Error('GCS URIs should be passed directly to the API, not converted to base64');
+    }
+    // Assume it's a file path
+    const absolutePath = path.isAbsolute(imagePath)
+        ? imagePath
+        : path.resolve(process.cwd(), imagePath);
+    if (!fs.existsSync(absolutePath)) {
+        // Check if it's already base64 encoded
+        if (isBase64(imagePath)) {
+            return imagePath;
+        }
+        throw new Error(`Image file not found: ${absolutePath}`);
+    }
+    const buffer = fs.readFileSync(absolutePath);
+    return buffer.toString('base64');
+}
+/**
+ * Check if a string is base64 encoded
+ */
+function isBase64(str) {
+    if (str.length < 100)
+        return false; // Too short to be an image
+    try {
+        const decoded = Buffer.from(str, 'base64').toString('base64');
+        return decoded === str;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read video file and convert to base64
+ */
+export async function readVideoAsBase64(videoPath) {
+    if (videoPath.startsWith('gs://')) {
+        // GCS URI - return as-is for the API to handle
+        throw new Error('GCS URIs should be passed directly to the API, not converted to base64');
+    }
+    if (videoPath.startsWith('http://') || videoPath.startsWith('https://')) {
+        const response = await fetch(videoPath);
+        if (!response.ok) {
+            throw new Error(`Failed to fetch video: ${response.status}`);
+        }
+        const buffer = await response.arrayBuffer();
+        return Buffer.from(buffer).toString('base64');
+    }
+    // Assume it's a file path
+    const absolutePath = path.isAbsolute(videoPath)
+        ? videoPath
+        : path.resolve(process.cwd(), videoPath);
+    if (!fs.existsSync(absolutePath)) {
+        // Check if it's already base64 encoded
+        if (isBase64(videoPath)) {
+            return videoPath;
+        }
+        throw new Error(`Video file not found: ${absolutePath}`);
+    }
+    const buffer = fs.readFileSync(absolutePath);
+    return buffer.toString('base64');
+}
+/**
+ * Sleep utility
+ */
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=video.js.map

package/dist/utils/video.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"video.js","sourceRoot":"","sources":["../../src/utils/video.ts"],"names":[],"mappings":"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"}

package/docs/GOOGLE_VEO_3.1_API_SPECIFICATION.md

@@ -0,0 +1,392 @@
+# Google Veo 3.1 API 仕様書
+
+> 最終更新: 2026-02-01
+
+## 概要
+
+Veo 3.1はGoogleの最新動画生成AIモデルで、テキストプロンプトや画像から高品質な動画を生成できます。ネイティブオーディオ生成、フレーム補間、リファレンス画像による一貫性維持など、高度な機能を備えています。
+
+---
+
+## 利用可能なAPI
+
+Veo 3.1は2つのAPIプラットフォームで利用可能です：
+
+| プラットフォーム | 用途 | 認証方式 |
+|-----------------|------|----------|
+| **Gemini API** | 開発者向け、プロトタイピング | APIキー |
+| **Vertex AI** | エンタープライズ、本番環境 | OAuth 2.0 / サービスアカウント |
+
+---
+
+## モデルID一覧
+
+### Gemini API
+| モデルID | 説明 |
+|----------|------|
+| `veo-3.1-generate-preview` | Veo 3.1 標準版（プレビュー） |
+| `veo-3.1-fast-generate-preview` | Veo 3.1 高速版（プレビュー） |
+
+### Vertex AI
+| モデルID | 説明 | ステータス |
+|----------|------|-----------|
+| `veo-3.1-generate-001` | Veo 3.1 標準版 | Production |
+| `veo-3.1-fast-generate-001` | Veo 3.1 高速版 | Production |
+| `veo-3.1-generate-preview` | Veo 3.1 標準版 | Preview |
+| `veo-3.1-fast-generate-preview` | Veo 3.1 高速版 | Preview |
+
+---
+
+## 価格 (2026年1月時点)
+
+### Vertex AI / Gemini API 公式価格
+
+| 機能 | 解像度 | 価格（USD） |
+|------|--------|------------|
+| **動画 + オーディオ生成** | 720p, 1080p | **$0.40/秒** |
+| **動画 + オーディオ生成** | 4K | **$0.60/秒** |
+| **動画のみ（音声なし）** | 720p, 1080p | **$0.20/秒** |
+
+### コスト計算例
+
+| 動画長 | 音声あり (1080p) | 音声なし (1080p) |
+|--------|-----------------|-----------------|
+| 4秒 | $1.60 | $0.80 |
+| 6秒 | $2.40 | $1.20 |
+| 8秒 | $3.20 | $1.60 |
+
+### Gemini Advanced サブスクリプション
+- **$19.99/月**: Veo 3.1フルアクセス（ネイティブ音声生成、4Kアップスケーリング含む）
+- **$249.99/月 (Ultra)**: 約2,500本のVeo 3.1 Fast動画生成可能
+
+---
+
+## APIエンドポイント
+
+### Gemini API
+
+```
+POST https://generativelanguage.googleapis.com/v1beta/models/{MODEL_ID}:predictLongRunning
+```
+
+**認証ヘッダー:**
+```
+x-goog-api-key: YOUR_API_KEY
+```
+
+### Vertex AI
+
+```
+POST https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predictLongRunning
+```
+
+**認証ヘッダー:**
+```
+Authorization: Bearer $(gcloud auth print-access-token)
+```
+
+---
+
+## リクエストパラメータ
+
+### 必須/オプションパラメータ
+
+| パラメータ | 型 | 必須 | デフォルト | 説明 |
+|-----------|-----|------|-----------|------|
+| `prompt` | string | △ | - | テキストプロンプト（画像入力時はオプション） |
+| `image` | object | × | - | 開始フレーム画像（image-to-video用） |
+| `lastFrame` | object | × | - | 終了フレーム画像（フレーム補間用） |
+| `video` | object | × | - | 延長対象の動画（video extension用） |
+| `referenceImages` | array | × | - | 参照画像（最大3枚、Veo 3.1のみ） |
+| `negativePrompt` | string | × | - | 生成を避けたい要素 |
+
+### 生成設定パラメータ
+
+| パラメータ | 型 | デフォルト | 選択肢/範囲 |
+|-----------|-----|-----------|------------|
+| `aspectRatio` | string | "16:9" | "16:9", "9:16" |
+| `resolution` | string | "720p" | "720p", "1080p", "4k"(プレビューのみ) |
+| `durationSeconds` | integer | 8 | 4, 6, 8 |
+| `sampleCount` | integer | 1 | 1-4 |
+| `generateAudio` | boolean | - | true/false (Veo 3必須) |
+| `personGeneration` | string | "allow_adult" | "allow_adult", "dont_allow", "allow_all" |
+| `seed` | uint32 | ランダム | 0 - 4,294,967,295 |
+| `compressionQuality` | string | "optimized" | "optimized", "lossless" |
+| `resizeMode` | string | "pad" | "pad", "crop" |
+| `storageUri` | string | - | gs://BUCKET/PATH |
+
+### referenceImages の構造
+
+```json
+{
+  "referenceImages": [
+    {
+      "image": {
+        "bytesBase64Encoded": "BASE64_DATA"
+      },
+      "referenceType": "asset"
+    }
+  ]
+}
+```
+
+- `referenceType`: `"asset"`（キャラクター/オブジェクト）または `"style"`（スタイル）
+- 最大3枚のasset画像、または1枚のstyle画像
+
+---
+
+## サポートされるファイル形式
+
+### 入力画像
+- `image/jpeg`
+- `image/png`
+- `image/webp`
+- **最大サイズ:** 20MB
+
+### 入力動画（video extension用）
+- `video/mp4`, `video/mov`, `video/mpeg`, `video/avi`, `video/wmv`, `video/flv`
+- **要件:** 1-30秒、24fps、720p または 1080p
+
+### 出力動画
+- **形式:** MP4
+- **フレームレート:** 24fps
+- **透かし:** SynthID（デジタルウォーターマーク）
+
+---
+
+## 主要機能
+
+### 1. Text-to-Video（テキストから動画）
+テキストプロンプトから動画を生成
+
+```python
+from google import genai
+from google.genai import types
+
+client = genai.Client(api_key="YOUR_API_KEY")
+
+operation = client.models.generate_videos(
+    model="veo-3.1-generate-preview",
+    prompt="A cinematic shot of a golden retriever running through autumn leaves in slow motion",
+    config=types.GenerateVideosConfig(
+        aspect_ratio="16:9",
+        resolution="1080p",
+        duration_seconds=8,
+        generate_audio=True
+    )
+)
+
+# ポーリングで完了を待機
+while not operation.done:
+    time.sleep(10)
+    operation = client.operations.get(operation.name)
+
+# 結果を取得
+video = operation.response.generated_videos[0]
+```
+
+### 2. Image-to-Video（画像から動画）
+静止画をアニメーション化
+
+```python
+import base64
+
+with open("start_frame.jpg", "rb") as f:
+    image_data = base64.b64encode(f.read()).decode()
+
+operation = client.models.generate_videos(
+    model="veo-3.1-generate-preview",
+    prompt="Camera slowly zooms in while clouds move in the background",
+    image=types.Image(bytes_base64_encoded=image_data),
+    config=types.GenerateVideosConfig(
+        aspect_ratio="16:9",
+        duration_seconds=8
+    )
+)
+```
+
+### 3. First-Last Frame Interpolation（フレーム補間）
+開始フレームと終了フレームの間を補間
+
+```python
+operation = client.models.generate_videos(
+    model="veo-3.1-generate-preview",
+    prompt="Smooth transition between scenes",
+    image=types.Image(bytes_base64_encoded=first_frame_data),
+    last_frame=types.Image(bytes_base64_encoded=last_frame_data),
+    config=types.GenerateVideosConfig(
+        duration_seconds=8,
+        generate_audio=True
+    )
+)
+```
+
+### 4. Video Extension（動画延長）
+既存の動画を延長（最終1秒から続きを生成）
+
+```python
+operation = client.models.generate_videos(
+    model="veo-3.1-generate-preview",
+    prompt="Continue the action with the character walking forward",
+    video=types.Video(uri="gs://bucket/previous_video.mp4"),
+    config=types.GenerateVideosConfig(
+        # 延長は7秒、720p固定
+    )
+)
+```
+
+### 5. Reference Images（参照画像によるガイド）
+キャラクターやスタイルの一貫性を維持
+
+```python
+operation = client.models.generate_videos(
+    model="veo-3.1-generate-preview",
+    prompt="The character walks through a magical forest",
+    reference_images=[
+        types.ReferenceImage(
+            image=types.Image(bytes_base64_encoded=character_image),
+            reference_type="asset"
+        )
+    ],
+    config=types.GenerateVideosConfig(
+        duration_seconds=8
+    )
+)
+```
+
+---
+
+## Vertex AI REST API例
+
+### リクエスト
+
+```bash
+curl -X POST \
+  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
+  -H "Content-Type: application/json" \
+  "https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/publishers/google/models/veo-3.1-generate-001:predictLongRunning" \
+  -d '{
+    "instances": [{
+      "prompt": "A timelapse of a flower blooming in soft natural light"
+    }],
+    "parameters": {
+      "aspectRatio": "16:9",
+      "resolution": "1080p",
+      "durationSeconds": 8,
+      "generateAudio": true,
+      "sampleCount": 1,
+      "storageUri": "gs://my-bucket/output/"
+    }
+  }'
+```
+
+### レスポンス（初期）
+
+```json
+{
+  "name": "projects/PROJECT_ID/locations/us-central1/publishers/google/models/veo-3.1-generate-001/operations/OPERATION_ID"
+}
+```
+
+### 操作ステータス確認
+
+```bash
+curl -X GET \
+  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
+  "https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/publishers/google/models/veo-3.1-generate-001/operations/${OPERATION_ID}"
+```
+
+### 完了時レスポンス
+
+```json
+{
+  "name": "...",
+  "done": true,
+  "response": {
+    "generatedVideos": [
+      {
+        "video": {
+          "uri": "gs://my-bucket/output/video.mp4",
+          "bytesBase64Encoded": "..."
+        }
+      }
+    ]
+  }
+}
+```
+
+---
+
+## クォータと制限
+
+| 制限項目 | 値 |
+|----------|-----|
+| リクエスト/分（Production） | 50 |
+| リクエスト/分（Preview） | 10 |
+| 動画長 | 4, 6, 8秒 |
+| 同時生成数 | 最大4本/リクエスト |
+| プロンプト長 | 最大1,024トークン |
+| 入力画像サイズ | 最大20MB |
+| 動画保持期間 | 2日間（サーバー側） |
+| レイテンシー | 11秒 〜 6分 |
+
+### 地域制限
+- EU/UK/CH/MENA地域: `personGeneration`は`"allow_adult"`のみ利用可
+
+---
+
+## プロンプトのベストプラクティス
+
+### 構成要素
+1. **Subject（被写体）**: オブジェクト、人物、動物、風景
+2. **Action（動作）**: 被写体が何をしているか
+3. **Style（スタイル）**: 映画的スタイル、カメラワーク
+
+### 良いプロンプト例
+
+```
+A cinematic drone shot of a lone surfer riding a massive wave at sunset,
+golden hour lighting, slow motion, shot on ARRI Alexa,
+shallow depth of field with ocean spray in foreground
+```
+
+### 音声キューの指定
+
+```
+A chef in a busy kitchen, the sound of sizzling pans and chopping vegetables,
+ambient kitchen chatter in the background
+```
+
+---
+
+## エラーハンドリング
+
+### 一般的なエラー
+
+| エラーコード | 原因 | 対処法 |
+|-------------|------|--------|
+| 400 | 無効なパラメータ | リクエストパラメータを確認 |
+| 401 | 認証エラー | APIキー/トークンを確認 |
+| 429 | レート制限超過 | リトライまたはクォータ増加を申請 |
+| 500 | サーバーエラー | 時間をおいてリトライ |
+
+### コンテンツフィルタリング
+
+生成された動画が安全性ポリシーに違反する場合、空の結果が返されます。`negativePrompt`を使用して不適切なコンテンツの生成を抑制してください。
+
+---
+
+## 参考リンク
+
+- [Gemini API Video Generation](https://ai.google.dev/gemini-api/docs/video)
+- [Vertex AI Veo 3.1 Documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/models/veo/3-1-generate)
+- [Vertex AI Veo API Reference](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/veo-video-generation)
+- [Google Developers Blog - Veo 3.1 Announcement](https://developers.googleblog.com/en/introducing-veo-3-1-and-new-creative-capabilities-in-the-gemini-api/)
+
+---
+
+## 変更履歴
+
+| 日付 | 変更内容 |
+|------|----------|
+| 2026-02-01 | 初版作成 |