# Grok Video API

> Generate, monitor, recover, and download videos through xAI's Grok Imagine Video 1.5 API or an explicitly configured compatible gateway. Use for paid Grok text-to-video or single-image-to-video; do not use for MiniMax H3 or local ComfyUI generation.

- Skill: `zmgid/grok-video-api-2` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add zmgid/grok-video-api-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zmgid/grok-video-api-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: zmgid (https://skillmd.com/u/zmgid)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zmgid/grok-video-api-2

---


# Grok Imagine Video Official API

Use the bundled dependency-free `scripts/grok_video.py` client. It reads the `grok` URL, API key, and selected model from the current user's `dsvideo/providers.json`, and falls back to `grok-imagine-video-1.5` on the official `https://api.x.ai` endpoint when no saved URL/model exists. The legacy `XAI_API_BASE`, `XAI_API_KEY`, and `XAI_VIDEO_MODEL` variables remain supported as overrides.

Before a paid request, read [references/grok-video-api.md](references/grok-video-api.md). Run `quote` before presenting this route. xAI does not document a balance-query endpoint, so state that account balance must be checked in xAI Console; do not invent a balance.

## Required rules

1. Preserve the current task’s agreed script, product, language and audio across follow-ups. Consolidate missing choices and cost confirmation into one question. A user instruction to generate the displayed plan or a specific variant is authorization for that variant; do not ask again for unchanged choices. Newly invented scripts or an unconfirmed paid cost require confirmation. Preparation and free dry runs may run before confirmation.
2. Read credentials from the saved `grok` provider or the legacy `XAI_API_KEY` override. Never print or place a literal key in a command.
3. Obtain an explicit `480p`, `720p`, or `1080p` choice for the current task. Never infer or silently change it. Reuse the user’s existing choice unless they change it.
4. Show the USD estimate from `quote`, including the selected duration and whether one source image is charged, before asking the user to choose Grok.
5. Run `--dry-run` first and compare model, resolution, duration, aspect ratio, mode, and audio with the confirmed request.
6. Run exactly one `generate` command for a completed file. It submits once, prints the request ID, polls that request, checks returned duration, and downloads the MP4.
7. After timeout or interruption, resume with `status` or `wait` and the same request ID. Never resubmit automatically.
8. A dry run is free but does not verify credentials or produce a video.

## Quote

```text
python <skill-directory>/scripts/grok_video.py quote --duration <1-15> --image-count <0-or-1>
```

The current official output rates are USD $0.08/sec for 480p, $0.14/sec for 720p, and $0.25/sec for 1080p. Image input adds $0.01 per image. Treat the quote as an estimate and link the official pricing page.

## Generate

```text
python <skill-directory>/scripts/grok_video.py generate \
  --prompt "<confirmed prompt>" \
  --resolution <480p-or-720p-or-1080p> \
  --duration <1-15> \
  --ratio <ratio> \
  [--image <local-path-or-public-url>] \
  [--no-audio] \
  --output <output.mp4>
```

Run the same command with `--dry-run` before removing that flag for the paid call. Local JPG/JPEG/PNG/WebP images are converted to data URIs; public HTTP(S) URLs and existing data URIs pass through.

## Recover

```text
python <skill-directory>/scripts/grok_video.py status <request-id>
python <skill-directory>/scripts/grok_video.py wait <request-id> \
  --expect-resolution <resolution> --expect-duration <seconds> --output <output.mp4>
```

The result URL is temporary, so download promptly. The client accepts both absolute xAI URLs and gateway-relative `/v1/videos/.../content` URLs; it sends the API credential on relative same-gateway downloads only. Deliver the local MP4 path, request ID, mode, selected resolution, verified duration, aspect ratio, and that Grok was the paid route.

## Dsivio 内置版

对话使用本 Skill 的原始脚本和 MCP。查找、保存或修改模板时读 [共享模板说明](../../TEMPLATES.md)，直接读写共享文件夹；不创建页面任务或同步草稿。运行环境由应用提供，内置副本随应用更新。

## 视频配置在哪

视频页面和本插件共用一份 `providers.json`，页面保存后下次脚本调用直接生效，不需要重复配置。路径优先取 `DSVIDEO_CONFIG_PATH`；否则 Windows 为 `%APPDATA%/dsvideo/providers.json`，macOS/Linux 为 `${XDG_CONFIG_HOME:-~/.config}/dsvideo/providers.json`。
用户问模型或配置时，运行 `python <插件根目录>/scripts/dsvideo_config.py show`（密钥脱敏），查看 `providers.grok` / `providers.minimax` / `providers.comfy` 的 `model` 和 `base_url`。MiniMax-H3 路线模型固定为 MiniMax-H3；ComfyUI 模型由工作流决定。旧环境变量显式覆盖时说明来源。生成仍使用插件自己的脚本和 MCP。

## Execution context

Read [运行与恢复](../ecom-h3-video/references/execution.md) before running commands. Keep requested speech and its language when switching routes or shortening a video. Official price estimates are not a custom gateway invoice.