# 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` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add zmgid/grok-video-api`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zmgid/grok-video-api/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

---


# 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.

## 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.