# Grok Imagine Video MCP Server

[![npm version](https://badge.fury.io/js/grok-imagine-video-mcp-server.svg)](https://www.npmjs.com/package/grok-imagine-video-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

xAI の Grok Imagine Video API 用 MCP (Model Context Protocol) サーバー。テキストプロンプトからの動画生成、画像からの動画生成（Image-to-Video）、既存動画の編集をサポートします。

## クイックスタート (npx)

最も簡単な方法は `npx` を使用することです：

```bash
# APIキーを設定
export XAI_API_KEY="xai-your-api-key"

# サーバーを実行
npx grok-imagine-video-mcp-server
```

## 機能

- **動画生成（Text-to-Video）**: テキストプロンプトから新規動画を生成
- **動画生成（Image-to-Video）**: 画像を入力として動画を生成（プロンプト省略可）
- **動画生成（Reference-to-Video / R2V）**: 参照画像をスタイル/コンテンツ参照として動画を生成（`grok-imagine-video-1.5` ではプリセットボイス `reference_audios` も指定可）
- **動画編集**: 既存動画をプロンプトで編集
- **動画延長（Extension）**: 既存動画の続きを生成して延長
- **バッチ処理**: CLIで複数動画を一括処理
- 多様なアスペクト比をサポート（16:9, 4:3, 1:1, 9:16 など）
- 解像度: 480p, 720p, 1080p（1080p は `grok-imagine-video-1.5` 限定）
- 動画長: 1〜15秒（デフォルト8秒。編集時は元動画と同じ長さ、延長は2〜10秒）
- 音声つき（効果音・環境音・BGM が自動生成される。話者の声のみ 1.5 の `reference_audios` で選択可、それ以外はプロンプトで指示する）
- 非同期処理対応（ポーリングによる結果取得、進捗・コスト表示）

> **grok-imagine-video 1.5 対応**: Reference-to-Video（プリセットボイス含む）、動画延長、構造化エラー/進捗、実コスト（`cost_in_usd_ticks`）表示に対応しています。

プロンプトの書き方は [docs/prompt-templates.md](docs/prompt-templates.md) を参照してください。

## サポートモデル

| モード | `grok-imagine-video` | `grok-imagine-video-1.5` |
|--------|:--:|:--:|
| Text-to-Video | ✅ | ✅ |
| Image-to-Video | ✅ | ✅ |
| Reference-to-Video | ✅ | ✅ |
| R2V のプリセットボイス（`reference_audios`） | ❌ | ✅ |
| 編集 | ✅ | ❌ |
| 延長 | ✅ | ❌ |
| 1080p | ❌ | ✅ |

> **モデルと機能の対応について（2026-08-30 実機検証済み）**:
> `grok-imagine-video-1.5` は Text-to-Video に続き **Reference-to-Video も受け付けるようになりました**（プリセットボイス `reference_audios` を含む）。一方 編集・延長は引き続き `Video editing is not supported for this model.` / `Video extension is not supported for this model.` を返します。全モードを使えるのは基本モデル `grok-imagine-video` のみで、これがデフォルトです。なお 1080p が使えるのは T2V/I2V のみで、**R2V の出力は 720p 上限**です。
>
> **1080p について**: 1080p は `grok-imagine-video-1.5` でのみ利用できます。公式ドキュメントは「1.5 の Image-to-Video 限定」と書いていますが、実測では **1.5 の Text-to-Video でも 1080p が通ります**（出力実寸 1920x1088）。基本モデルで `1080p` を指定すると `1080p video resolution is not available for this model.` が返ります。これは**アカウントの権限や Grok のサブスク（SuperGrok 等）とは無関係**です。なお xAI の API 課金は消費者向け Grok サブスクとは別系統（前払いクレジット/請求）で、サブスク加入で API 機能が解放されることはありません。

## 音声

出力される MP4 には**常に AAC 音声トラックが含まれます**。効果音・環境音・BGM はプロンプトのシーン内容から自動生成されます。話者の声だけは `grok-imagine-video-1.5` の R2V で `reference_audios`（プリセットボイス、最大3件。プロンプト中で `<AUDIO_0>` … と参照）として選択できますが、効果音・BGM を制御する API パラメータはありません。狙った音にしたい場合はプロンプト本文で指示します（[テンプレート集](docs/prompt-templates.md#音声について)参照）。音声が不要なら `ffmpeg -i in.mp4 -c copy -an out.mp4` で除去してください。

## 必要条件

- Node.js 18.0.0 以上
- xAI API キー（[console.x.ai](https://console.x.ai/) から取得）

## インストール

### 方法1: npx（推奨）

```bash
npx grok-imagine-video-mcp-server
```

### 方法2: グローバルインストール

```bash
npm install -g grok-imagine-video-mcp-server
grok-imagine-video-mcp-server
```

## 設定

### 環境変数

| 変数 | 必須 | 説明 |
|------|------|------|
| `XAI_API_KEY` | Yes | xAI API キー |
| `DEBUG` | No | `true` でデバッグログを有効化 |
| `OUTPUT_DIR` | No | 動画のデフォルト出力ディレクトリ |
| `VIDEO_POLL_INTERVAL` | No | ポーリング間隔（ミリ秒、デフォルト: 5000） |
| `VIDEO_MAX_POLL_ATTEMPTS` | No | 最大ポーリング回数（デフォルト: 120） |

### Claude Desktop 設定

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "grok-imagine-video": {
      "command": "npx",
      "args": ["-y", "grok-imagine-video-mcp-server"],
      "env": {
        "XAI_API_KEY": "xai-your-api-key-here"
      }
    }
  }
}
```

## ツール

### generate_video

テキストプロンプトまたは画像から動画を生成します。

| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| `prompt` | string | 条件付き | 生成する動画の説明テキスト。T2V/R2V では必須、I2V（画像指定時）では省略可 |
| `output_path` | string | No | 出力ファイルパス（デフォルト: generated_video.mp4） |
| `model` | string | No | モデル（デフォルト: grok-imagine-video） |
| `duration` | number | No | 動画長（1-15秒、デフォルト: 8） |
| `aspect_ratio` | string | No | アスペクト比（デフォルト: 16:9） |
| `resolution` | string | No | 解像度（480p/720p/1080p、デフォルト: 720p） |
| `image_url` | string | No | Image-to-Video用の入力画像URL |
| `image_path` | string | No | ローカル画像ファイルパス（base64 data URLとして送信。10MB超はFiles API経由で自動アップロード） |
| `image_file_id` | string | No | xAI Files API の File ID（Image-to-Video用） |
| `reference_images` | array | No | Reference-to-Video用の参照画像（各要素は `url` / `path` / `file_id` のいずれか）。プロンプト中では `<IMAGE_0>` … で参照 |
| `reference_audios` | array | No | R2V用のプリセットボイス（最大3件、各要素は `voice_id` または `url`）。**`grok-imagine-video-1.5` 限定**。プロンプト中では `<AUDIO_0>` … で参照 |

> **注意**: `image_url` / `image_path` / `image_file_id` はいずれか1つのみ指定できます。また、画像（I2V）と `reference_images` / `reference_audios`（R2V）も同時指定できません。`reference_audios` は単独指定（音声のみの R2V）も可能です。

### edit_video

既存動画を編集します。

| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| `prompt` | string | Yes | 編集内容の説明 |
| `video_url` | string | No* | 編集する動画のURL（公開アクセス可能、最大8.7秒） |
| `video_path` | string | No* | ローカル動画ファイルパス（.mp4、Files API 経由で自動アップロード） |
| `video_file_id` | string | No* | xAI Files API の File ID（*いずれか1つを指定） |
| `output_path` | string | No | 出力ファイルパス（デフォルト: edited_video.mp4） |
| `model` | string | No | モデル（デフォルト: grok-imagine-video） |

> **注意**: 編集後の動画は元動画と同じ長さになります。`duration` パラメータは編集時には指定できません。

### extend_video

既存動画の続きを生成して延長します（grok-imagine-video 1.5）。

| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| `prompt` | string | Yes | 続きで何が起こるかの説明 |
| `video_url` | string | No* | 延長する動画のURL（公開アクセス可能 or base64 data URL、.mp4） |
| `video_path` | string | No* | ローカル動画ファイルパス（.mp4、Files API 経由で自動アップロード） |
| `video_file_id` | string | No* | xAI Files API の File ID（*いずれか1つを指定） |
| `output_path` | string | No | 出力ファイルパス（デフォルト: extended_video.mp4） |
| `model` | string | No | モデル（デフォルト: grok-imagine-video） |
| `duration` | number | No | 延長セグメントの長さ（2-10秒、デフォルト: 6） |

### upload_file

ローカルの画像・動画ファイルを xAI Files API にアップロードし、`file_id` を取得します。ファイルは非公開のまま保存され、`image_file_id` / `reference_images[].file_id` / `video_file_id` として再利用できます（同じファイルを何度も送り直す必要がありません）。

| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| `file_path` | string | Yes | アップロードするファイルのパス（画像: jpg/jpeg/png/gif/webp/bmp/tiff、動画: mp4、最大 48MB） |

## バッチ処理 CLI

### コマンド書式

```
grok-imagine-video-batch <config.json> [options]
```

または npx 経由：

```
npx grok-imagine-video-batch <config.json> [options]
```

### 基本的な使用例

```bash
# 設定ファイルでバッチ実行
npx grok-imagine-video-batch batch.json

# コスト見積もりのみ（実行しない）
npx grok-imagine-video-batch batch.json --estimate-only

# 出力先とフォーマットを指定
npx grok-imagine-video-batch batch.json --output-dir ./videos --format json

# ポーリング設定をカスタマイズ
npx grok-imagine-video-batch batch.json --poll-interval 10000 --max-poll-attempts 60

# 高並列実行（タイムアウト延長）
npx grok-imagine-video-batch batch.json --max-concurrent 5 --timeout 1800000

# ヘルプ表示
npx grok-imagine-video-batch --help

# バージョン表示
npx grok-imagine-video-batch --version
```

### CLI オプション一覧

| オプション | 短縮形 | 引数 | 説明 | デフォルト |
|-----------|--------|------|------|-----------|
| `--output-dir` | - | `<path>` | 出力ディレクトリを上書き | 設定ファイルから |
| `--format` | - | `text\|json` | 出力フォーマット | `text` |
| `--timeout` | - | `<ms>` | タイムアウト（ミリ秒、最小1000） | `600000` |
| `--max-concurrent` | - | `<n>` | 最大同時実行数（1-10） | `2` |
| `--poll-interval` | - | `<ms>` | ポーリング間隔（ミリ秒、最小1000） | `5000` |
| `--max-poll-attempts` | - | `<n>` | 最大ポーリング回数 | `120` |
| `--estimate-only` | - | - | コスト見積もりのみ（実行しない） | - |
| `--allow-any-path` | - | - | 任意の出力パスを許可（CI/CD用） | - |
| `--help` | `-h` | - | ヘルプメッセージ表示 | - |
| `--version` | `-v` | - | バージョン表示 | - |

### 終了コード

| コード | 意味 |
|--------|------|
| `0` | 成功（全ジョブ完了） |
| `1` | エラー（失敗またはキャンセルあり） |

### バッチ設定ファイル

```json
{
  "jobs": [
    {
      "prompt": "猫がボールで遊んでいる",
      "output_path": "cat_video.mp4",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p"
    },
    {
      "prompt": "キャラクターが歩いているアニメーション",
      "image_url": "https://example.com/character.jpg",
      "output_path": "walking.mp4",
      "duration": 10
    },
    {
      "prompt": "ボールを大きくして",
      "video_url": "https://example.com/video.mp4",
      "output_path": "edited.mp4"
    }
  ],
  "output_dir": "./output",
  "max_concurrent": 2,
  "poll_interval": 5000,
  "max_poll_attempts": 120,
  "default_model": "grok-imagine-video",
  "default_duration": 5,
  "retry_policy": {
    "max_retries": 2,
    "retry_delay_ms": 1000
  }
}
```

### ジョブ定義スキーマ

各ジョブは3種類のうち1つを指定します：

#### 1. Text-to-Video（テキストから動画生成）

```json
{
  "prompt": "生成したい動画の説明",
  "output_path": "output.mp4",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "model": "grok-imagine-video"
}
```

| フィールド | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| `prompt` | string | Yes | 動画の説明テキスト |
| `output_path` | string | No | 出力ファイル名 |
| `duration` | number | No | 動画長（1-15秒） |
| `aspect_ratio` | string | No | アスペクト比 |
| `resolution` | string | No | 解像度（720p/480p） |
| `model` | string | No | モデル名 |

#### 2. Image-to-Video（画像から動画生成）

**URL指定の場合:**
```json
{
  "prompt": "画像をアニメーション化する説明",
  "image_url": "https://example.com/image.jpg",
  "output_path": "animated.mp4",
  "duration": 5
}
```

**ローカルファイルの場合（base64 data URL）:**
```json
{
  "prompt": "画像をアニメーション化する説明",
  "image_path": "./images/character.jpg",
  "output_path": "animated.mp4",
  "duration": 5
}
```

| フィールド | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| `prompt` | string | Yes | アニメーションの説明 |
| `image_url` | string | No* | 入力画像のURL（公開アクセス可能） |
| `image_path` | string | No* | ローカル画像ファイルパス（base64 data URLとして送信。10MB超はFiles API経由で自動アップロード） |
| `image_file_id` | string | No* | xAI Files API の File ID |
| `output_path` | string | No | 出力ファイル名 |
| `duration` | number | No | 動画長（1-15秒） |

> *`image_url` / `image_path` / `image_file_id` のいずれか1つを指定（同時指定不可）

#### 3. Reference-to-Video（参照画像から動画生成 / R2V）

```json
{
  "prompt": "アニメ風に歩くキャラクター",
  "reference_images": [
    { "url": "https://example.com/style.jpg" },
    { "path": "./images/character.png" }
  ],
  "output_path": "r2v.mp4",
  "duration": 8
}
```

| フィールド | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| `prompt` | string | Yes | 動画の説明 |
| `reference_images` | array | 条件付き | 参照画像（各要素は `url` / `path` / `file_id` のいずれか）。`reference_audios` があれば省略可 |
| `reference_audios` | array | 条件付き | プリセットボイス（最大3件、各要素は `voice_id` または `url`）。`grok-imagine-video-1.5` 限定 |
| `output_path` | string | No | 出力ファイル名 |
| `duration` | number | No | 動画長（1-15秒） |

参照音声（プリセットボイス）を使う例：

```json
{
  "model": "grok-imagine-video-1.5",
  "prompt": "<IMAGE_0> の人物が <AUDIO_0> の声で商品を紹介する",
  "reference_images": [{ "path": "./images/person.png" }],
  "reference_audios": [{ "voice_id": "eve" }],
  "output_path": "r2v_voice.mp4",
  "duration": 8
}
```

> 画像（I2V）と `reference_images` / `reference_audios`（R2V）は同時指定できません。`reference_audios`（プリセットボイス、最大3件）は `grok-imagine-video-1.5` 限定です。

#### 4. Video Edit（動画編集）

```json
{
  "prompt": "編集内容の説明",
  "video_url": "https://example.com/video.mp4",
  "output_path": "edited.mp4"
}
```

| フィールド | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| `prompt` | string | Yes | 編集内容の説明 |
| `video_url` | string | No* | 編集する動画のURL（最大8.7秒） |
| `video_path` | string | No* | ローカル動画ファイルパス（.mp4、Files API 経由で自動アップロード） |
| `video_file_id` | string | No* | xAI Files API の File ID（*いずれか1つを指定） |
| `output_path` | string | No | 出力ファイル名 |

#### 5. Video Extension（動画延長）

```json
{
  "operation": "extend",
  "prompt": "カメラが引いて街並みが見える",
  "video_url": "https://example.com/video.mp4",
  "output_path": "extended.mp4",
  "duration": 6
}
```

| フィールド | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| `operation` | string | Yes | `"extend"` を指定（省略するとソース動画付きは編集扱い） |
| `prompt` | string | Yes | 続きで何が起こるかの説明 |
| `video_url` | string | No* | 延長する動画のURL |
| `video_path` | string | No* | ローカル動画ファイルパス（.mp4、Files API 経由で自動アップロード） |
| `video_file_id` | string | No* | xAI Files API の File ID（*いずれか1つを指定） |
| `output_path` | string | No | 出力ファイル名 |
| `duration` | number | No | 延長セグメントの長さ（2-10秒、デフォルト6） |

> `video_url` / `video_path` / `video_file_id` を持つジョブは既定で編集（edit）として扱われます。延長したい場合は `"operation": "extend"` を明示してください。

### グローバル設定

| フィールド | 型 | 説明 | デフォルト |
|-----------|-----|------|-----------|
| `output_dir` | string | 出力ディレクトリ | `./output` |
| `max_concurrent` | number | 最大同時実行数（1-10） | `2` |
| `poll_interval` | number | ポーリング間隔（ms） | `5000` |
| `max_poll_attempts` | number | 最大ポーリング回数 | `120` |
| `default_model` | string | デフォルトモデル | `grok-imagine-video` |
| `default_duration` | number | デフォルト動画長 | `8` |
| `default_aspect_ratio` | string | デフォルトアスペクト比 | `16:9` |
| `default_resolution` | string | デフォルト解像度 | `720p` |

### リトライポリシー

```json
{
  "retry_policy": {
    "max_retries": 2,
    "retry_delay_ms": 1000,
    "retry_on_errors": ["rate_limit", "429", "500", "502", "503"]
  }
}
```

| フィールド | 型 | 説明 | デフォルト |
|-----------|-----|------|-----------|
| `max_retries` | number | 最大リトライ回数 | `2` |
| `retry_delay_ms` | number | リトライ間隔（ms） | `1000` |
| `retry_on_errors` | string[] | リトライ対象エラー（エラーメッセージへの部分一致） | `["rate_limit", "timeout", "429", "503", "service_unavailable", "internal_error"]` |

`service_unavailable` と `internal_error` は xAI が「リトライすべき」と定義しているエラーコードです。
`invalid_argument` / `permission_denied` / `failed_precondition` はリクエスト内容の問題なのでリトライしません。

設定例は `examples/` ディレクトリを参照してください：
- `batch-simple.json` - 基本的な動画生成
- `batch-image-to-video.json` - 画像からの動画生成（URL指定）
- `batch-local-images.json` - ローカル画像からの動画生成
- `batch-reference-to-video.json` - 参照画像からの動画生成（R2V）
- `batch-reference-voice.json` - 参照画像＋プリセットボイス／音声のみの R2V（`grok-imagine-video-1.5`）
- `batch-with-edits.json` - 動画編集チェーン
- `batch-extend.json` - 動画延長（Extension）
- `batch-social-media.json` - SNS向けフォーマット

## サポートされているアスペクト比

| アスペクト比 | 用途例 |
|-------------|--------|
| `16:9` | 横長ワイドスクリーン、YouTube（デフォルト） |
| `4:3` | 標準的な横長 |
| `1:1` | 正方形、Instagram |
| `9:16` | 縦長、TikTok、Reels、Stories |
| `3:4` | 縦長 |
| `3:2` / `2:3` | 写真比率 |

## サポートされている解像度

| 解像度 | 説明 |
|--------|------|
| `1080p` | フルHD画質（**`grok-imagine-video-1.5` の T2V/I2V 限定**。R2V は 720p 上限。基本モデルでは "1080p video resolution is not available for this model." になります） |
| `720p` | HD画質（デフォルト） |
| `480p` | 標準画質 |

## 動画長の制限

| 操作 | 最小 | 最大 | デフォルト |
|------|------|------|-----------|
| 生成（Text/Image/Reference-to-Video） | 1秒 | 15秒 | 8秒 |
| 編集 | - | 8.7秒 | 元動画と同じ |
| 延長（Extension） | 2秒 | 10秒 | 6秒 |

## 料金

動画 1 秒あたりの単価（USD）。1秒ジョブの `usage.cost_in_usd_ticks` から実測（2026-07-31）。

| モデル | 480p | 720p | 1080p |
|--------|------|------|-------|
| `grok-imagine-video` | $0.05 | $0.07 | 非対応 |
| `grok-imagine-video-1.5` | $0.08 | $0.14 | $0.25 |

- 実課金額はジョブごとに `usage.cost_in_usd_ticks` として返り、結果表示に含まれます
- バッチ CLI の `--estimate-only` はこの表で事前見積もりを出します（編集は 720p 単価で概算）
- 参照画像・参照音声・入力画像・入力動画にも課金されるため、R2V の実額は上表の単価をやや上回ります（実測例: 1.5 / 480p / 1秒 / 参照画像1枚 + ボイス1件 = $0.09）

## 非同期処理について

Video APIは非同期で動作します：

1. **リクエスト送信**: 動画生成/編集リクエストを送信
2. **request_id 取得**: APIから `request_id` が返される
3. **ポーリング**: 定期的に結果を確認（デフォルト: 5秒間隔）
4. **結果取得**: 完了後、動画URLを取得してダウンロード

```
POST /v1/videos/generations → { request_id: "abc123" }
                ↓
GET /v1/videos/abc123 → { status: "pending" } → 待機
                ↓
GET /v1/videos/abc123 → { status: "completed", url: "..." } → ダウンロード
```

`status` は `pending` / `done`（旧 `completed`） / `failed` / `expired` のいずれかです。
`failed` と `expired` は終端としてポーリングを打ち切り、エラーを返します（`expired` はリクエストの保持期限切れで、再送信が必要）。

## 使用例

```
# テキストから動画生成
「猫がボールで遊んでいる」の5秒動画を16:9で生成して

# 画像から動画生成
この画像のキャラクターを歩かせる動画を作って

# 動画編集
この動画の背景を夜に変更して
```

## API リファレンス

| 機能 | エンドポイント |
|------|---------------|
| 動画生成（T2V/I2V/R2V） | `POST https://api.x.ai/v1/videos/generations` |
| 動画編集 | `POST https://api.x.ai/v1/videos/edits` |
| 動画延長 | `POST https://api.x.ai/v1/videos/extensions` |
| 結果取得 | `GET https://api.x.ai/v1/videos/{request_id}` |

- **ドキュメント**: [docs.x.ai](https://docs.x.ai/)

## 開発

```bash
git clone https://github.com/ex-takashima/grok-imagine-video-mcp-server.git
cd grok-imagine-video-mcp-server
npm install
npm run build
npm start
```

### 開発用コマンド

```bash
# ビルド
npm run build

# ウォッチモード
npm run dev

# バッチCLI実行
npm run batch -- examples/batch-simple.json --estimate-only
```

## トラブルシューティング

### ポーリングがタイムアウトする

動画生成には時間がかかる場合があります。以下を試してください：

```bash
# ポーリング回数を増やす
npx grok-imagine-video-batch batch.json --max-poll-attempts 200

# タイムアウトを延長
npx grok-imagine-video-batch batch.json --timeout 1200000
```

### Rate Limit エラー

並列数を減らすか、リトライ設定を調整してください：

```json
{
  "max_concurrent": 1,
  "retry_policy": {
    "max_retries": 3,
    "retry_delay_ms": 5000,
    "retry_on_errors": ["rate_limit", "429"]
  }
}
```

## 関連プロジェクト

- [grok-imagine-image-mcp-server](https://github.com/ex-takashima/grok-imagine-image-mcp-server) - 画像生成用MCP Server

## ライセンス

MIT

## 作者

Junji Takashima <takajyun00@gmail.com>