内容
# Grok Imagine 视频 MCP 服务器
[](https://www.npmjs.com/package/grok-imagine-video-mcp-server)
[](https://opensource.org/licenses/MIT)
xAI 的 Grok Imagine Video API 的 MCP（模型上下文协议）服务器。支持从文本提示生成视频，从图像生成视频（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）**：以参考图像作为风格/内容参考生成视频
- **视频编辑**：根据提示编辑现有视频
- **视频延长（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](https://docs.x.ai/developers/model-capabilities/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](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` | 是 | xAI API 密钥 |
| `DEBUG` | 否 | 设置 `true` 以启用调试日志 |
| `OUTPUT_DIR` | 否 | 视频的默认输出目录 |
| `VIDEO_POLL_INTERVAL` | 否 | 轮询间隔（毫秒，默认：5000） |
| `VIDEO_MAX_POLL_ATTEMPTS` | 否 | 最大轮询次数（默认：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"
}
}
}
}
```
## 工具
### 生成视频
从文本提示或图像生成视频。
| 参数 | 类型 | 必需 | 说明 |
|-----------|-----|------|------|
| `prompt` | string | 条件 | 生成视频的描述文本。T2V/R2V 必需，I2V（指定图像时）可选 |
| `output_path` | string | 否 | 输出文件路径（默认：generated_video.mp4） |
| `model` | string | 否 | 模型（默认：grok-imagine-video） |
| `duration` | number | 否 | 视频长度（1-15秒，默认：8） |
| `aspect_ratio` | string | 否 | 宽高比（默认：16:9） |
| `resolution` | string | 否 | 分辨率（480p/720p/1080p，默认：720p） |
| `image_url` | string | 否 | Image-to-Video 的输入图像 URL |
| `image_path` | string | 否 | 本地图像文件路径（以 base64 data URL 发送。超过 10MB 将通过 Files API 自动上传） |
| `image_file_id` | string | 否 | xAI Files API 的 File ID（Image-to-Video 用） |
| `reference_images` | array | 否 | Reference-to-Video 的参考图像（每个元素为 `url` / `path` / `file_id` 之一） |
> **注意**：`image_url` / `image_path` / `image_file_id` 只能指定一个。同时不能指定图像（I2V）和 `reference_images`（R2V）。
### 编辑视频
编辑现有视频。
| 参数 | 类型 | 必需 | 说明 |
|-----------|-----|------|------|
| `prompt` | string | 是 | 编辑内容的描述 |
| `video_url` | string | 否* | 编辑视频的 URL（公开访问，最大 8.7 秒） |
| `video_path` | string | 否* | 本地视频文件路径（.mp4，通过 Files API 自动上传） |
| `video_file_id` | string | 否* | xAI Files API 的 File ID（*至少指定一个） |
| `output_path` | string | 否 | 输出文件路径（默认：edited_video.mp4） |
| `model` | string | 否 | 模型（默认：grok-imagine-video） |
> **注意**：编辑后的视频长度与原视频相同。编辑时不能指定 `duration` 参数。
### 延长视频
延长现有视频的续篇（grok-imagine-video 1.5）。
| 参数 | 类型 | 必需 | 说明 |
|-----------|-----|------|------|
| `prompt` | string | 是 | 续篇中发生内容的描述 |
| `video_url` | string | 否* | 延长视频的 URL（公开访问或 base64 data URL，.mp4） |
| `video_path` | string | 否* | 本地视频文件路径（.mp4，通过 Files API 自动上传） |
| `video_file_id` | string | 否* | xAI Files API 的 File ID（*至少指定一个） |
| `output_path` | string | 否 | 输出文件路径（默认：extended_video.mp4） |
| `model` | string | 否 | 模型（默认：grok-imagine-video） |
| `duration` | number | 否 | 延长片段的长度（1-10秒，默认：6） |
### 上传文件
将本地图像/视频文件上传到 xAI Files API 并获取 `file_id`。文件将保持私有状态，可作为 `image_file_id` / `reference_images[].file_id` / `video_file_id` 重新使用（无需重复发送相同的文件）。
| 参数 | 类型 | 必需 | 说明 |
|-----------|-----|------|------|
| `file_path` | string | 是 | 上传文件的路径（图像：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
}
}
```
### 作业定义模式
每个作业指定以下三种类型之一：
#### 1. 文本到视频（文本生成视频）
```json
{
"prompt": "生成视频的描述文本",
"output_path": "output.mp4",
**duration**: 5,
"aspect_ratio": "16:9",
"resolution": "720p",
"model": "grok-imagine-video"
}
```
| 字段 | 类型 | 必需 | 说明 |
|-----------|-----|------|------|
| `prompt` | string | 是 | 视频描述文本 |
| `output_path` | string | 否 | 输出文件名 |
| `duration` | number | 否 | 视频长度（1-15秒） |
| `aspect_ratio` | string | 否 | 宽高比 |
| `resolution` | string | 否 | 分辨率（720p/480p） |
| `model` | string | 否 | 模型名称 |
#### 2. 图像到视频（图像生成视频）
**URL 指定：**
```json
{
"prompt": "动画描述",
"image_url": "https://example.com/image.jpg",
"output_path": "animated.mp4",
"duration": 5
}
```
**本地文件：**
```json
{
"prompt": "动画描述",
"image_path": "./images/character.jpg",
"output_path": "animated.mp4",
"duration": 5
}
```
| 字段 | 类型 | 必需 | 说明 |
|-----------|-----|------|------|
| `prompt` | string | 是 | 动画描述 |
| `image_url` | string | 否* | 输入图像的 URL（公开访问） |
| `image_path` | string | 否* | 本地图像文件路径（以 base64 data URL 发送。超过 10MB 将自动通过 Files API 上传） |
| `image_file_id` | string | 否* | xAI Files API 的 File ID |
| `output_path` | string | 否 | 输出文件名 |
| `duration` | number | 否 | 视频长度（1-15秒） |
> *`image_url` / `image_path` / `image_file_id` 只能指定一个。同时不能指定图像（I2V）和 `reference_images`（R2V）。
#### 4. 视频编辑
```json
{
"prompt": "编辑内容描述",
"video_url": "https://example.com/video.mp4",
"output_path": "edited.mp4"
}
```
| 字段 | 类型 | 必需 | 说明 |
|-----------|-----|------|------|
| `prompt` | string | 是 | 编辑内容描述 |
| `video_url` | string | 否* | 编辑视频的 URL（最大 8.7 秒） |
| `video_path` | string | 否* | 本地视频文件路径（.mp4，通过 Files API 自动上传） |
| `video_file_id` | string | 否* | xAI Files API 的 File ID（*至少指定一个） |
| `output_path` | string | 否 | 输出文件名 |
#### 5. 视频延长
```json
{
"operation": "extend",
"prompt": "相机拉远，显示城市景观",
"video_url": "https://example.com/video.mp4",
"output_path": "extended.mp4",
"duration": 6
}
```
| 字段 | 类型 | 必需 | 说明 |
|-----------|-----|------|------|
| `operation` | string | 是 | 指定 `"extend"` |
| `prompt` | string | 是 | 续篇内容描述 |
| `video_url` | string | 否* | 延长视频的 URL |
| `video_path` | string | 否* | 本地视频文件路径（.mp4，通过 Files API 自动上传） |
| `video_file_id` | string | 否* | xAI Files API 的 File ID（*至少指定一个） |
| `output_path` | string | 否 | 输出文件名 |
| `duration` | number | 否 | 延长片段长度（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 | 轮询间隔（毫秒） | `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 | 重试间隔（毫秒） | `1000` |
| `retry_on_errors` | string[] | 重试触发错误 | 上表 |
## 支持的宽高比
| 宽高比 | 用例 |
|-------------|--------|
| `16:9` | 横向宽屏，YouTube（默认） |
| `4:3` | 标准横向 |
| `1:1` | 正方形，Instagram |
| `9:16` | 纵向，TikTok，Reels，Stories |
| `3:4` | 纵向 |
| `3:2` / `2:3` | 照片比例 |
## 支持的分辨率
| 分辨率 | 说明 |
|--------|------|
| `1080p` | 全高清（**仅限 `grok-imagine-video-1.5` × Image-to-Video 支持**。其他组合将返回 "1080p video resolution is not available for this model."） |
| `720p` | 高清（默认） |
| `480p` | 标准清晰度 |
## 视频长度限制
| 操作 | 最小 | 最大 | 默认值 |
|------|------|------|-----------|
| 生成（Text/Image/Reference-to-Video） | 1 秒 | 15 秒 | 8 秒 |
| 编辑 | - | 8.7 秒 | 与原视频相同 |
| 延长 | 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](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
```
### 速率限制错误
减少并发数或调整重试设置：
```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 服务器
## 许可证
MIT
## 作者
Junji Takashima <takajyun00@gmail.com>
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器