Grok Imagine Video Server

npm version License: MIT

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

クイックスタート (npx)

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

# 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）: 参照画像をスタイル/コンテンツ参照として動画を生成
• 動画編集: 既存動画をプロンプトで編集
• 動画延長（Extension）: 既存動画の続きを生成して延長
• バッチ処理: CLIで複数動画を一括処理
• 多様なアスペクト比をサポート（16:9, 4:3, 1:1, 9:16 など）
• 解像度: 480p, 720p, 1080p（1080p は grok-imagine-video-1.5 × Image-to-Video 限定）
• 動画長: 1〜15秒（デフォルト8秒。編集時は元動画と同じ長さ、延長は1〜10秒）
• 非同期処理対応（ポーリングによる結果取得、進捗・コスト表示）

grok-imagine-video 1.5 対応: Reference-to-Video、動画延長、構造化エラー/進捗、実コスト（cost_in_usd_ticks）表示に対応しています。1080p は grok-imagine-video-1.5 の Image-to-Video に限り利用できます。

サポートモデル

モデル	機能	備考
grok-imagine-video	T2V / I2V / R2V / 編集 / 延長	推奨・デフォルト。1.5世代の各機能はこのモデルで動作
grok-imagine-video-1.5	I2V 中心（pinned版）	T2V / R2V / 延長は非対応。特定用途のみ

モデルと機能の対応について（実機検証済み）: Reference-to-Video・動画延長・Text-to-Video はいずれも基本モデル grok-imagine-video で動作します（公式ドキュメントの例も全て grok-imagine-video を使用）。pinned 版の grok-imagine-video-1.5 は T2V/R2V/延長を受け付けないため、通常はデフォルトの grok-imagine-video を使用してください。

1080p について: 公式ドキュメント（Video Generation）によると、1080p は grok-imagine-video-1.5 の Image-to-Video に限り利用できます。それ以外のモデル×モードの組み合わせで 1080p を指定すると 1080p video resolution is not available for this model. が返ります。これはアカウントの権限や Grok のサブスク（SuperGrok 等）とは無関係です。なお xAI の API 課金は消費者向け Grok サブスクとは別系統（前払いクレジット/請求）で、サブスク加入で API 機能が解放されることはありません。

必要条件

• Node.js 18.0.0 以上
• xAI API キー（console.x.ai から取得）

インストール

方法1: npx（推奨）

npx grok-imagine-video-mcp-server

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

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

{
  "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_url / image_path / image_file_id はいずれか1つのみ指定できます。また、画像（I2V）と reference_images（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	延長セグメントの長さ（1-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]

基本的な使用例

# 設定ファイルでバッチ実行
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	エラー（失敗またはキャンセルあり）

バッチ設定ファイル

{
  "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（テキストから動画生成）

{
  "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指定の場合:

{
  "prompt": "画像をアニメーション化する説明",
  "image_url": "https://example.com/image.jpg",
  "output_path": "animated.mp4",
  "duration": 5
}

ローカルファイルの場合（base64 data URL）:

{
  "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）

{
  "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	Yes	参照画像（各要素は url / path / file_id のいずれか）
output_path	string	No	出力ファイル名
duration	number	No	動画長（1-15秒）

画像（I2V）と reference_images（R2V）は同時指定できません。

4. Video Edit（動画編集）

{
  "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（動画延長）

{
  "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	延長セグメントの長さ（1-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

リトライポリシー

{
  "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[]	リトライ対象エラー	上記参照

設定例は examples/ ディレクトリを参照してください：

• batch-simple.json - 基本的な動画生成
• batch-image-to-video.json - 画像からの動画生成（URL指定）
• batch-local-images.json - ローカル画像からの動画生成
• batch-reference-to-video.json - 参照画像からの動画生成（R2V）
• 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 × Image-to-Video 限定。他の組み合わせでは "1080p video resolution is not available for this model." になります）
720p	HD画質（デフォルト）
480p	標準画質

動画長の制限

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

非同期処理について

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: "..." } → ダウンロード

使用例

# テキストから動画生成
「猫がボールで遊んでいる」の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

開発

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

開発用コマンド

# ビルド
npm run build

# ウォッチモード
npm run dev

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

トラブルシューティング

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

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

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

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

Rate Limit エラー

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

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

関連プロジェクト

• grok-imagine-image-mcp-server - 画像生成用MCP Server

ライセンス

MIT

作者

Junji Takashima [email protected]