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

# Grok Imagine Video Generation

> Complete guide to the xAI Grok Imagine video official channel on APIYI: grok-imagine-video / grok-imagine-video-1.5 / grok-imagine-video-1.5-lite, text-to-video and image-to-video with native audio, 1–15 seconds, priced the same as xAI per second by resolution ($0.02–0.25/s). OpenAI Videos-compatible; requires the GrokOfficial group by application.

## Overview

**Grok Imagine Video** is the **official channel** for xAI's video models: requests are relayed by APIYI to the official xAI API, **pricing matches xAI's list price**, and billing follows generated seconds and resolution. The API is an OpenAI Videos-compatible asynchronous task endpoint (`/v1/videos`) supporting **text-to-video** and **image-to-video**, and every video comes with an audio track.

Three models are available:

* **`grok-imagine-video`**: the base model, 480p / 720p
* **`grok-imagine-video-1.5`**: the newer model, 480p / 720p / 1080p
* **`grok-imagine-video-1.5-lite`**: lightweight 1.5, the lowest price at 480p / 720p

> [!WARNING]
>
> **🔒 This channel requires the `GrokOfficial` group, granted on application**
>
> Grok Imagine Video is not in the `Default` group. This family's content-safety policy differs substantially from the other models on the platform, so to limit compliance risk we grant access **selectively**:
>
> * **Existing customers with \$1,000+ in cumulative spend**: contact support, describe your use case, and we enable it after verification
> * **Everyone else**: apply through [WeCom support](https://work.weixin.qq.com/kfid/kfc9adfd5810ece25ec), describing your **use case** and your **content-moderation controls**; we enable it once approved
>
> A Token without the `GrokOfficial` group returns **`503`** — a permissions problem, not an outage. See [Group Setup](#group-setup) below.

> [!WARNING]
>
> **⚠️ Without `size`, the default is 480p and 8 seconds**
>
> If you submit without a resolution or duration, the video is generated and billed at **480p, 8 seconds**. For 720p / 1080p or a shorter clip, pass `size` (such as `"1280x720"`) and `seconds` explicitly.

> **[Video Generation API](/en/api-capabilities/grok-imagine-video/video-generation)**
>
> Submit text-to-video / image-to-video tasks, with an interactive Playground.

> **[Grok Imagine Official Images](/en/api-capabilities/grok-imagine-image-official/overview)**
>
> Same `GrokOfficial` group — image generation priced the same as xAI, by tier.

## Let an AI Agent Integrate It

Integrate / troubleshoot Grok Imagine video generation (text-to-video + image-to-video) in this project.

Read the docs before writing code: fetch [https://docs.apiyi.com/en/api-capabilities/grok-imagine-video/overview.md](https://docs.apiyi.com/en/api-capabilities/grok-imagine-video/overview.md) for the plain-text version of this page; for more parameter detail, append `.md` to the video-generation page URL the same way.

Requirements:

1. Pick one model: `grok-imagine-video` (480p / 720p), `grok-imagine-video-1.5` (480p / 720p / 1080p), or `grok-imagine-video-1.5-lite` (lightweight 1.5). The Token group must include `GrokOfficial` with billing mode Pay-as-you-go Priority or Pay-as-you-go, otherwise every call returns 503.

2. Async three-step flow: `POST /v1/videos` to submit and get the task `id` → poll `GET /v1/videos/{id}` every 5–10 seconds until `status` is `completed` or `failed` → download the MP4 from `GET /v1/videos/{id}/content` (with the same Authorization header). Cap total polling at 10 minutes.

3. Pass resolution and duration explicitly: `size` in pixels (such as `"1280x720"`, `"720x1280"`, `"1920x1080"`); the shorter side picks the tier (≥1080 is 1080p, ≥720 is 720p, otherwise 480p) and the aspect ratio snaps to the nearest supported one. `seconds` ranges from 1 to 15. **Without them the default is 480p and 8 seconds, and that is what you are billed for.** `grok-imagine-video` does not support 1080p and returns 400 if you ask for it.

4. Image-to-video: add `input_reference` on the same endpoint, set to a public image URL or a `data:image/...;base64,...` URI; or upload the file with multipart under the field name `input_reference`. The output frame follows the input image.

5. Billing: generated seconds × the per-second rate for the resolution, plus a small fee per input image for image-to-video. Turning off audio does not lower the price.

6. Moderation: a task blocked by content moderation still has `status` `completed`, but there is no video, the response carries `error.code: "moderation_blocked"`, **and it is still billed**. Check this field in code — do not treat it as a success, and do not blindly retry the same prompt.

7. The video can be downloaded as soon as the task is `completed`; save it to your own object storage right away instead of keeping the link.

8. Read the key from the `APIYI_API_KEY` environment variable and use [https://api.apiyi.com/v1](https://api.apiyi.com/v1) as base\_url; never hard-code it or commit it to git. When done, actually run one 2-second 480p text-to-video job and show me the clip's duration, resolution, and what the call cost.

## Models & Pricing

Pricing matches xAI's list price and is charged **per second of generated video**; the rate depends on model and resolution:

| Model | 480p | 720p | 1080p | Image-to-video input image |
| - | - | - | - | - |
| **`grok-imagine-video`** | \$0.05 / s | \$0.07 / s | Not supported | \$0.002 / image |
| **`grok-imagine-video-1.5`** | \$0.08 / s | \$0.14 / s | \$0.25 / s | \$0.01 / image |
| **`grok-imagine-video-1.5-lite`** | \$0.02 / s | \$0.03 / s | \$0.14 / s | \$0.01 / image |

> [!NOTE]
>
> Model pricing is aligned with the official sites and may change when they do; the table above is for reference only, and the **Model Pricing** tab in the top navigation is authoritative: [Model Pricing](/en/models/index).

> [!NOTE]
>
> **Billing notes and an example**
>
> * **Cost = seconds × per-second rate + input images × per-image fee**. Example: a 1-second 480p image-to-video job on `grok-imagine-video` = 1 × \$0.05 + 1 × \$0.002 = **\$0.052** (matches the bill in our tests).
> * **Defaults are billed too**: without `size` / `seconds` the job runs at 480p for 8 seconds — \$0.40 on `grok-imagine-video`.
> * **Audio is not billed separately**: videos include an audio track by default, and turning it off does not lower the price.
> * **Moderation blocks are billed**: xAI charges for videos its moderation blocks, and we bill on the same basis — see the [FAQ](#faq).
> * [Tiered top-up bonuses](/en/faq/recharge-promotions) apply on top; high-volume business customers can contact sales about dedicated pricing.

## Group Setup

> [!WARNING]
>
> **Grok Imagine Video is not in the `Default` group.** It lives in the **`GrokOfficial` group (same price as xAI, i.e. the table above)**, shared with [Grok Imagine Official Images](/en/api-capabilities/grok-imagine-image-official/overview), and access must be requested.

### Who can get access

| Customer type | How to get access |
| - | - |
| **Existing customers with \$1,000+ cumulative spend** | Contact support with your use case; enabled after verification |
| **Everyone else** | Apply with your use case and content-moderation controls; enabled once approved |

### How to apply

**1. Contact WeCom support**

Apply through [WeCom support](https://work.weixin.qq.com/kfid/kfc9adfd5810ece25ec), or email [hi@apiyi.com](mailto:hi@apiyi.com). Say you are applying for **`GrokOfficial` (Grok Imagine Official)**.

**2. Describe your use case and moderation controls**

Cover three things: what the videos are for, who the end users are, and what content review and human checks you run on your side. The more specific, the faster the review.

**3. Switch your Token group once approved**

Once approved, we enable `GrokOfficial` on your account. Go to the [Token page in the console](https://api.apiyi.com/token), switch the Token you use for this channel to `GrokOfficial`, and set the billing mode to `Pay-as-you-go Priority` or `Pay-as-you-go`.

> [!NOTE]
>
> **What it looks like before access is granted**: a Token without the `GrokOfficial` group returns **`503` (no available channel in the current group)**. Retrying will not help — the group has to be enabled first.
>
> **Do not use the `Pay-per-request` billing mode**: this channel is billed per second, so a pay-per-request Token cannot be routed and also returns 503.

> [!NOTE]
>
> **Compliance reminder**: once access is granted, responsibility for generated content lies with the caller. Follow local laws and regulations; do not generate illegal content, content that infringes others' likeness or intellectual property, or content inappropriate for minors. For consumer-facing distribution, add your own moderation layer. Background: [Compliance notes for calling overseas models](/en/faq/overseas-model-compliance). We revoke group access when abuse is found.

## Technical Specs

| Item | Spec |
| - | - |
| Model IDs | `grok-imagine-video`, `grok-imagine-video-1.5`, `grok-imagine-video-1.5-lite` |
| Capabilities | Text-to-video, image-to-video (one input image) |
| Duration | `seconds` 1–15, **default 8** |
| Resolution | 480p (default) / 720p / 1080p (no 1080p on `grok-imagine-video`) |
| Aspect ratio | `size` snaps to the nearest of `1:1` / `16:9` / `9:16` / `4:3` / `3:4` / `3:2` / `2:3`; image-to-video follows the input image |
| Audio | Included by default |
| Generation time | About 20–25 s for 2 s at 480p; about 35–50 s for image-to-video; about 110 s for 1080p on 1.5 |
| Download | Available from `/v1/videos/{id}/content` as soon as the task is `completed` |
| Suggested polling | Every 5–10 seconds, with a 10-minute overall cap |

## Endpoints

| Step | Method | Path | Notes |
| - | - | - | - |
| ① Submit | `POST` | `/v1/videos` | `application/json`; image-to-video can also upload a file with `multipart/form-data` |
| ② Check status | `GET` | `/v1/videos/{id}` | Returns `status` / `progress`, plus `seconds` once done |
| ③ Download | `GET` | `/v1/videos/{id}/content` | Returns the MP4; requires the Authorization header |

> [!TIP]
>
> Primary domain `https://api.apiyi.com`, backup domain `https://b.apiyi.com`. Full code samples: [Video Generation API](/en/api-capabilities/grok-imagine-video/video-generation).

### End-to-end flow (Python)

```python theme={null}
import os, time, requests

BASE = "https://api.apiyi.com/v1"
H = {"Authorization": f"Bearer {os.environ['APIYI_API_KEY']}"}

# ① Submit: 720p landscape, 5 seconds
task = requests.post(f"{BASE}/videos", headers=H, json={
    "model": "grok-imagine-video-1.5",
    "prompt": "a red paper boat drifting on a calm lake, gentle ripples, soft morning light",
    "seconds": "5",
    "size": "1280x720",
}, timeout=60).json()
vid = task["id"]

# ② Poll
for _ in range(60):
    time.sleep(8)
    job = requests.get(f"{BASE}/videos/{vid}", headers=H, timeout=60).json()
    if job["status"] in ("completed", "failed"):
        break

if job["status"] == "failed" or job.get("error"):
    # A moderation block also reports completed, but with error.code = moderation_blocked
    raise RuntimeError(job.get("error"))

# ③ Download the video and store it right away
mp4 = requests.get(f"{BASE}/videos/{vid}/content", headers=H, timeout=300)
open("out.mp4", "wb").write(mp4.content)
```

## Key Parameters

### `size` (resolution and aspect ratio)

`size` uses `WIDTHxHEIGHT` pixels; the gateway picks the resolution tier from the **shorter side** and snaps the **aspect ratio** to the nearest supported one:

| `size` example | Result |
| - | - |
| `"854x480"` | 480p, 16:9 (measured output 848×480) |
| `"1280x720"` | 720p, 16:9 (measured output 1280×720) |
| `"720x1280"` | 720p, 9:16 (measured output 720×1280) |
| `"1920x1080"` | 1080p, 16:9 (1.5 / 1.5-lite only) |

You can also pass `"480p"` / `"720p"` / `"1080p"` directly, or skip `size` and send xAI's native fields `resolution` (`480p` / `720p` / `1080p`) plus `aspect_ratio` (such as `9:16`); when both are present, `resolution` / `aspect_ratio` win. With neither, the video is generated at **480p**.

> [!WARNING]
>
> `grok-imagine-video` supports only 480p / 720p; a 1080p-class `size` returns `400`: `grok-imagine-video resolution must be one of 480p, 720p`.

### `seconds` (duration)

An integer from **1 to 15**, as a string (`"5"`) or a number (`5`); **default 8**. Out-of-range values return `400`: `duration must be an integer between 1 and 15`. Cost scales with seconds, so use 1–2 seconds while testing.

### `input_reference` (image-to-video)

Pass one input image to turn the job into image-to-video. Any of three forms works:

* Public image URL: `"input_reference": "https://example.com/first-frame.jpg"`
* base64 data URI: `"input_reference": "data:image/jpeg;base64,/9j/4AAQ..."`
* Multipart file upload: `-F "input_reference=@first-frame.jpg"`

For image-to-video, use `prompt` to describe motion and camera (such as "the cat slowly turns its head"); **the output frame follows the input image**. Each input image costs an extra \$0.002 (`grok-imagine-video`) or \$0.01 (1.5 / 1.5-lite).

## Best Practices

**1. Test prompts at 1–2 seconds and 480p**

Billing is per second, so confirm the look with short, low-resolution clips before rendering the final length at 720p / 1080p. `grok-imagine-video-1.5-lite` has the lowest 480p / 720p rate and suits batch exploration.

**2. Always pass size and seconds**

Leaving them out means 480p at 8 seconds — the most common source of "why is this so expensive" and "why is it so blurry".

**3. Poll every 5–10 seconds with an overall timeout**

Jobs usually finish within 20 seconds to 2 minutes. Faster polling gains nothing; cap the total at 10 minutes and log the task ID for troubleshooting if it times out.

**4. Handle moderation blocks**

Check `error.code` in the status response: `moderation_blocked` means the job was blocked, has no video, and was billed. Rephrase before resubmitting rather than retrying as is.

**5. Store the video right away**

Download from `/content` as soon as the job is `completed`; do not keep the download link long-term or hand it to end users.

## Error Codes & Retries

| HTTP / field | Meaning | What to do |
| - | - | - |
| `400` `invalid_request_error` | Invalid parameters: unsupported resolution, `seconds` outside 1–15, etc.; `message` explains | Fix as indicated; do not retry |
| `429` | Rate limit hit or insufficient balance | Retry with exponential backoff and check your balance |
| `503` | Token lacks the `GrokOfficial` group, or uses pay-per-request billing | **Permissions, not an outage** — see [Group Setup](#group-setup) |
| `status: failed` | Generation failed | Read `error.message`, adjust, and resubmit |
| `completed` + `error.code: moderation_blocked` | Blocked by content moderation; no video; billed | Change the prompt or input image before resubmitting |

## FAQ

> **Every call returns 503 — is the channel down?**
>
> Almost certainly permissions: the Token group lacks `GrokOfficial`, or the Token's billing mode is pay-per-request. For the former, apply via [Group Setup](#group-setup); for the latter, switch the billing mode to `Pay-as-you-go Priority` or `Pay-as-you-go`.

> **Why is my video 480p and 8 seconds?**
>
> Those are the defaults: without `size` and `seconds`, the job is generated and billed at 480p for 8 seconds. Pass `size` (such as `"1280x720"`) and `seconds` explicitly.

> **The task says completed, but there is no video to download?**
>
> Check the status response for `error.code: "moderation_blocked"`. If it is there, xAI's content moderation blocked the video: the task still reports `completed`, but there is no video, **and it is billed** (xAI charges for blocked videos too). Adjust the prompt or input image and resubmit.

> **Is it cheaper without audio?**
>
> No. Videos include an audio track by default, and per xAI's pricing, turning audio off does not lower the price.

> **Why doesn't the image-to-video output match the size I sent?**
>
> Image-to-video follows the input image's frame. For a specific aspect ratio, crop the input image to that ratio before submitting.

> **Are video editing, extension, or multiple reference images supported?**
>
> This channel currently offers **text-to-video** and **image-to-video with one input image**. Video editing, extension, and similar capabilities are not open yet; this page will be updated when they are.

> **Which of the three models should I pick?**
>
> * Need 1080p → `grok-imagine-video-1.5` (best quality) or `grok-imagine-video-1.5-lite` (cheaper)
> * Batch 480p / 720p on a budget → `grok-imagine-video-1.5-lite` (\$0.02 / \$0.03 per second)
> * Already on the base model and only need 480p / 720p → `grok-imagine-video`

## Related Docs

* [Grok Imagine Video Generation API](/en/api-capabilities/grok-imagine-video/video-generation) - submit endpoint reference with Playground
* [Grok Imagine Official Images](/en/api-capabilities/grok-imagine-image-official/overview) - same group, priced the same as xAI by tier
* [Grok Model Guide](/en/api-capabilities/grok/overview) - xAI text models
* [Top-up Bonuses](/en/faq/recharge-promotions)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.