Grok imagine

Grok Imagine — Image & Video for Agents

GitHub · Install · API map · vs GPT Image 2

Generate images and videos with Grok Imagine (xAI) from Claude Code, Cursor, Codex, Grok Build, or a plain shell.

Auth (first match wins):

1. XAI_API_KEY
2. GROK_API_KEY
3. OIDC token from grok login (~/.grok/auth.json → key)

Only endpoints validated live are implemented — see docs/API.md.

When to trigger

• "grok imagine" / "grok image" / "grok video" / "xAI Imagine"
• "/grok-imagine"
• explicit request to generate or edit media with Grok

Do not hijack a generic "generate an image" if the user named another provider (GPT Image 2, Fal, etc.). If they named Grok Imagine, do not silently fall back.

How to invoke

Scripts live next to this file:

bash scripts/gen.sh \
  --mode <image|edit|video> \
  --prompt "<user's raw prompt>" \
  --out <absolute/path>

Text-to-image

bash scripts/gen.sh \
  --mode image \
  --prompt "A tiny blue boat on a calm sea at dusk, cinematic" \
  --out /absolute/path/image.jpg \
  --aspect-ratio 16:9

Optional: --fast → grok-imagine-image. Default → grok-imagine-image-quality. --n 2 writes stem-1.ext, stem-2.ext.

Image edit

bash scripts/gen.sh \
  --mode edit \
  --prompt "Repaint as neon cyan" \
  --ref /absolute/path/source.jpg \
  --out /absolute/path/edited.jpg

--ref required. Only the first ref is used (multi-image edit not validated).

Image-to-video

bash scripts/gen.sh \
  --mode video \
  --prompt "gentle camera push-in with subtle motion" \
  --ref /absolute/path/frame.jpg \
  --out /absolute/path/clip.mp4 \
  --duration 6

Default model: grok-imagine-video-1.5. Duration: 6 or 10. Optional --resolution 480p.

Text-to-video

bash scripts/gen.sh \
  --mode video \
  --prompt "A tiny blue boat rocking gently on a calm sea at dusk" \
  --out /absolute/path/clip.mp4 \
  --duration 6 \
  --aspect-ratio 16:9

Default model: grok-imagine-video.

Critical: grok-imagine-video-1.5 does not support T2V. Without --ref, the script uses the T2V-capable model.

Agent defaults

• Pass the user prompt raw (no unsolicited style padding).
• If no path given, choose ./grok-image-<YYYYMMDD-HHMMSS>.jpg or ./grok-video-<YYYYMMDD-HHMMSS>.mp4 (absolute when calling the script).
• After success, show/attach the file — do not stop at path-only.
• Prefer this skill’s CLI over inventing raw curl payloads.

Exit codes

code	meaning
0	success — path(s) on stdout
2	bad args
3	python3 missing
4	--ref missing on disk
5	API / network / video failure
6	empty media / download failed
7	auth missing or 401

On failure, name the layer in one sentence. Never print tokens or huge base64.

Hard constraints

• Do not substitute DALL·E / GPT Image 2 / HTML mockups when Grok Imagine was requested.
• Do not claim T2V works on grok-imagine-video-1.5.
• Do not invent unvalidated endpoints (video edit, extension, r2v) — re-test first.
• Do not log credentials.

Prerequisites

1. python3 on PATH (stdlib only — no pip install)
2. XAI_API_KEY or working grok login with Imagine entitlement

What this is not

Not the interactive Grok TUI slash commands alone. Not a free unlimited generation grant. Not multi-tenant SaaS. Concurrent calls are safe (stateless HTTPS).