---
name: grok-media
description: xAI Grok image and video generation guide covering authentication, endpoints, prompt structure, image editing, reference-image video, and async polling.
metadata:
  author: OpenMontage
  version: "1.0.0"
  tags: xai, grok, image-generation, video-generation, media
title: grok-media
canonical_url: https://skilld.dev/gh/openmontageinc/openmontage/grok-media
last_updated: 2026-10-14T05:11:31.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install openmontageinc/openmontage/grok-media`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/grok-media`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/openmontageinc/openmontage/grok-media) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/grok-media`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/grok-media --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/grok-media --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Grok Media

Use this skill when working with xAI media models in OpenMontage.

## Models

- `grok-imagine-image` for image generation and image editing
- `grok-imagine-video` for text-to-video, image-to-video, and reference-image video

## Authentication

- Env var: `XAI_API_KEY`
- Base URL: `https://api.x.ai/v1`
- Header: `Authorization: Bearer $XAI_API_KEY`

## Image API

### Text-to-image

- Endpoint: `POST /images/generations`
- Core fields:
  - `model`
  - `prompt`
  - `n`
  - `aspect_ratio`
  - `resolution`

### Image edit

- Endpoint: `POST /images/edits`
- Use `image` for one source image
- Use `images` for multi-image compositing
- Each source image can be:
  - a public HTTPS URL
  - a base64 data URI

### Image prompting

- Grok responds well to direct natural language
- For edits, describe only the intended change and preserve everything else implicitly
- For multi-image merges, explicitly name how each source contributes
- Prefer one strong scene description over long style-stacking

## Video API

### Generation

- Endpoint: `POST /videos/generations`
- Polling endpoint: `GET /videos/{request_id}`
- Success state: `status == "done"`
- Failure states to handle explicitly: `failed`, `expired`

### Modes

- Text-to-video:
  - prompt-only generation
- Image-to-video:
  - use `image: {"url": ...}`
  - this anchors the starting frame
- Reference-to-video:
  - use `reference_images: [{"url": ...}, ...]`
  - this influences who/what appears in the video without locking the first frame
  - prompts can reference inputs with placeholders like `<IMAGE_1>`, `<IMAGE_2>`

### Video constraints

- Grok video is best treated as short-form generation
- Current output resolutions are `480p` and `720p`
- Reference-image video supports multiple images and is useful for product placement, wardrobe transfer, and identity consistency
- Download outputs promptly; provider URLs may be temporary

## Pricing

- `grok-imagine-image`: `$0.02` per generated image
- `grok-imagine-image` edits/composites: add `$0.002` per input image
- `grok-imagine-video`:
  - `480p`: `$0.05` per second
  - `720p`: `$0.07` per second
- `grok-imagine-video` image-conditioned requests: add `$0.002` per input image

## Grok-Specific Prompt Guidance

### Images

- Start with subject, action, setting
- Add one style anchor, not five
- For edits:
  - describe the desired modification
  - keep the rest of the image stable by omission, not by writing a giant preservation list

### Video

- Keep prompts scene-local: one shot, one main motion idea, one emotional beat
- For reference-conditioned video, explicitly map source images to roles:
  - person from `<IMAGE_1>`
  - jacket from `<IMAGE_2>`
  - product from `<IMAGE_3>`
- Camera and pacing language helps:
  - slow push-in
  - handheld follow
  - locked-off medium shot
  - high-energy whip pan transition

## Good Fits

- Image style transfer
- Image compositing from multiple sources
- Reference-conditioned short video
- Product-led motion clips
- Character-consistent scenes without hard first-frame lock

## Weak Fits

- Long-form clip generation
- Heavy reliance on deterministic seeds
- Overloaded prompts with multiple scene changes

## Failure Handling

- If generation submission succeeds but polling expires, surface it as a provider/runtime issue
- If a request fails, preserve the endpoint, mode, and prompt summary in the error
- Do not silently substitute a different provider after xAI was selected without user approval
