> ## Documentation Index
> Fetch the complete documentation index at: https://docs.widerouter.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Grok Imagine video models

> xAI's two video models on WideRouter: generating, editing and extending clips, plus duration, resolution, reference images and preset voices.

Two models in the Grok Imagine family produce video. Both run on the
[async task API](/api/async-tasks) with the same envelope as everything else —
there is no synchronous video endpoint, so this is the only way to reach them.

The two are not a simple old-and-new pair. `grok-imagine-video-1.5` generates at
higher resolution and can use preset voices; `grok-imagine-video` is the only one
that accepts **video as input**, which is what editing and extending require.
Which one you want depends on whether you are creating a clip or changing one.

## The series at a glance

|                              | Grok Imagine Video 1.5        | Grok Imagine Video   |
| ---------------------------- | ----------------------------- | -------------------- |
| **Model id**                 | `grok-imagine-video-1.5`      | `grok-imagine-video` |
| Text to video                | yes                           | yes                  |
| Image to video (first frame) | yes                           | yes                  |
| Reference images             | yes, up to 3                  | yes, up to 3         |
| **Edit an existing clip**    | no                            | **yes**              |
| **Extend an existing clip**  | no                            | **yes**              |
| Resolutions                  | `480p` / `720p` / **`1080p`** | `480p` / `720p`      |
| Preset voices                | **yes**, up to 3              | no                   |
| Silent output                | yes                           | yes                  |
| Duration                     | 1–15 s                        | 1–15 s               |

Asking for something a model cannot do fails at submit time, before anything is
queued, and the message says which model to use instead:

```json theme={null}
{
  "error": {
    "code": "invalid_params",
    "message": "edit needs a model that takes video input; use grok-imagine-video",
    "param": "input.mode"
  }
}
```

## Modes

`input.mode` selects what the model does. It takes `generate`, `edit` or
`extend`, and defaults to `generate`.

| `mode`     | Needs `input.video` | Output duration         | Models                    |
| ---------- | ------------------- | ----------------------- | ------------------------- |
| `generate` | no                  | `duration`, plus 0.04 s | both                      |
| `edit`     | yes                 | **inherits the source** | `grok-imagine-video` only |
| `extend`   | yes                 | source plus `duration`  | `grok-imagine-video` only |

`edit` rewrites an existing clip from a prompt and keeps its length, so it does
not accept `resolution` — the output follows the source. `extend` appends new
footage to the end.

```json theme={null}
{
  "model": "grok-imagine-video",
  "input": {
    "prompt": "the camera slowly pulls back",
    "mode": "extend",
    "video": "https://example.com/boat.mp4",
    "duration": 3
  }
}
```

Measured: a 3.04-second source with `duration: 3` produced a **6.04-second**
clip — the original plus a three-second extension, not a re-render.

<Warning>
  **The `duration` range narrows in `extend` mode.** The contract accepts 1–15
  seconds, but an extension is actually limited to **2–10 seconds**, and the
  source clip must itself be **at least 2 seconds** long. Neither limit is
  checked at submit time, so both come back as a task-level failure after the
  task is queued:

  `Duration must be between 2 and 10 seconds` · `Input video must be at least 2 seconds long, got 1.0s`
</Warning>

## Parameters

Everything below goes inside `input`. The envelope is described in the
[async task API](/api/async-tasks).

| Field              | Type      | Default       | Notes                                                                                    |
| ------------------ | --------- | ------------- | ---------------------------------------------------------------------------------------- |
| `prompt`           | string    | —             | Required.                                                                                |
| `mode`             | string    | `generate`    | `generate`, `edit` or `extend`.                                                          |
| `duration`         | integer   | model default | 1–15 seconds. See the warning above for `extend`.                                        |
| `resolution`       | string    | `480p`        | `480p`, `720p`, or `1080p` on 1.5 only. Not accepted in `edit` mode.                     |
| `aspect_ratio`     | string    | `16:9`        | One of `1:1` `16:9` `9:16` `4:3` `3:4` `3:2` `2:3`.                                      |
| `images`           | string\[] | —             | Exactly one image, used as the **first frame**.                                          |
| `video`            | string    | —             | Source clip for `edit` and `extend`. `https` URL or a base64 video data URI.             |
| `reference_images` | string\[] | —             | Up to 3 images the model draws style and subject from. Cannot be combined with `images`. |
| `voice_ids`        | string\[] | —             | Up to 3 preset voices. `grok-imagine-video-1.5` only.                                    |
| `generate_audio`   | boolean   | `true`        | Set `false` for a silent clip. Does not change the price.                                |

There is no `n` — video models produce one clip per task.

<Note>
  Unlike the image models, video has **no `auto` aspect ratio** and no ultra-wide
  ratios. The seven values above are the complete list.
</Note>

## Resolution and duration

Measured output pixels, one sample per tier:

| `resolution` | `aspect_ratio`   | Output      |
| ------------ | ---------------- | ----------- |
| `480p`       | `16:9` (default) | 848 × 480   |
| `480p`       | `9:16`           | 480 × 848   |
| `720p`       | `16:9`           | 1280 × 720  |
| `1080p`      | `16:9`           | 1920 × 1088 |

`1080p` is rejected on `grok-imagine-video` with
`1080p is only available on grok-imagine-video-1.5`.

**Clips come back about 0.04 seconds longer than requested** — ask for 3 seconds
and the file is 3.04 seconds. This is consistent across every sample and does not
affect what you are charged, which follows the requested duration.

## Reference images, first frames, and voices

Three different things can be fed in, and two of them are mutually exclusive:

* **`images`** is a **first frame**. Exactly one image, and the clip animates
  outward from it.
* **`reference_images`** is style and subject guidance, up to three images. Both
  models accept it, and using it **caps the output at `720p`** —
  `reference_images` with `1080p` is rejected with
  `reference images are capped at 720p`.
* Passing both is rejected:
  `cannot be combined with images; a first frame and reference images are different modes`.

`voice_ids` selects preset voices on `grok-imagine-video-1.5`, up to three per
clip. The accepted values are:

|          |           |          |          |          |          |
| -------- | --------- | -------- | -------- | -------- | -------- |
| `ara`    | `eve`     | `leo`    | `rex`    | `sal`    | `carina` |
| `zagan`  | `helix`   | `orion`  | `luna`   | `iris`   | `altair` |
| `zenith` | `perseus` | `helios` | `lux`    | `kepler` | `rigel`  |
| `cosmo`  | `celeste` | `ursa`   | `sirius` | `lumen`  | `castor` |
| `naksh`  | `atlas`   |          |          |          |          |

Custom voices are not available on WideRouter. Note that the voice id itself is
**not validated at submit time** — an unrecognized name is accepted, and the task
then fails. Neither voices nor `generate_audio: false` changes the price.

## Pricing

These models are served through the **`Grok-Official`** group. WideRouter's list
price matches xAI's official price exactly — the discount lives in the **group
multiplier**, which is `0.8` for `Grok-Official`. So what you pay is:

```
list price × group multiplier = charge
```

Video is priced **per second of output**, by resolution. These are list prices:

| Model                    | `480p`     | `720p`     | `1080p`       |
| ------------------------ | ---------- | ---------- | ------------- |
| `grok-imagine-video-1.5` | \$0.08 / s | \$0.14 / s | \$0.25 / s    |
| `grok-imagine-video`     | \$0.05 / s | \$0.07 / s | not available |

Three rules that the per-second rate alone does not tell you:

* **Media you send in is charged too.** A reference image adds roughly \$0.01;
  a source clip for `edit` or `extend` is charged per second of its own length,
  around \$0.01 per second.
* **`extend` does not re-charge the original.** Only the new segment is priced at
  the per-second rate, plus the source clip as an input. Measured: extending a
  3.04-second clip by 3 seconds cost \$0.18 — three seconds of output at
  \$0.05 plus 3.04 seconds of input at \$0.01 — while the result is 6.04 seconds
  long. Regenerating six seconds from scratch would have cost \$0.30.
* **`edit` costs about the source length twice**, once as output and once as
  input. Measured: a 1.04-second clip edited for \$0.06.

A worked example, end to end. Three seconds of `480p` on `grok-imagine-video`:

```
\$0.05 / s × 3 s        = \$0.15   list price
\$0.15 × 0.8            = \$0.12   charged on Grok-Official
```

<Info>
  A completed task carries `usage.cost_in_usd_ticks`, where `10000000000` ticks
  is \$1. That figure is the **list price** — before your group multiplier.
  Multiply it by your group's rate to get what actually leaves your balance.
</Info>

## Latency

Measured end to end on the async API, submit to `completed`:

| Request                                    | End to end |
| ------------------------------------------ | ---------- |
| `grok-imagine-video`, `480p`, 1 s          | 19 s       |
| `grok-imagine-video-1.5`, `480p`, 1 s      | 21 s       |
| `grok-imagine-video`, `480p`, 3 s          | 21–30 s    |
| `grok-imagine-video`, `edit` of a 1 s clip | 30 s       |
| `grok-imagine-video`, `extend` by 3 s      | 30 s       |
| `grok-imagine-video-1.5`, `1080p`, 3 s     | \~48 s     |
| `grok-imagine-video-1.5`, `480p`, 15 s     | \~51 s     |

Generation is much faster than the "usually several minutes" that video models
are often described with, but it is still slow enough that holding a connection
open is not an option — which is why there is no synchronous endpoint. Poll
every two to three seconds and size your client timeout from the slowest row
here, not the fastest.

## When a task fails

Video failures land as a `failed` task with an `error` object, not as an HTTP
error — the read endpoint still returns `200`. The common code is
`upstream_error`, and the message is passed through from xAI:

```json theme={null}
{
  "status": "failed",
  "counts": { "requested": 1, "succeeded": 0, "failed": 1 },
  "error": {
    "code": "upstream_error",
    "message": "Input video must be at least 2 seconds long, got 1.0s"
  }
}
```

Failures that happen before generation starts are fast — under a second for an
unreachable input, about six seconds for a constraint the upstream model
enforces.

## Next steps

<CardGroup cols={2}>
  <Card title="Playground" icon="play" href="/models/grok-imagine/video/playground">
    Submit a real video task from the browser and poll it to completion.
  </Card>

  <Card title="Grok Imagine image" icon="image" href="/models/grok-imagine/image/overview">
    The image half of the family — three variants and the quality grid.
  </Card>
</CardGroup>