> ## 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 视频生成

> xAI Grok Imagine 视频生成官方通道（官转）完整指南：grok-imagine-video / grok-imagine-video-1.5 / grok-imagine-video-1.5-lite 三款，文生视频与图生视频，自带音轨，1–15 秒，与 xAI 官网同价按秒按分辨率计费（$0.02–0.25/秒）。OpenAI Videos 兼容接口，需申请开通 GrokOfficial 分组。

## 概述

**Grok Imagine 视频**是 xAI 视频生成模型的**官方通道**：请求经 API易 转发到 xAI 官方 API，**价格与 xAI 官网一致**，按生成秒数与分辨率计费。接口是 OpenAI Videos 兼容的异步任务式端点（`/v1/videos`），支持**文生视频**和**图生视频**，生成的视频自带音轨。

本通道提供三个型号：

* **`grok-imagine-video`**：基础款，480p / 720p
* **`grok-imagine-video-1.5`**：新一代，480p / 720p / 1080p
* **`grok-imagine-video-1.5-lite`**：1.5 轻量版，480p / 720p 单价最低

> [!WARNING]
>
> **🔒 本通道需申请开通 `GrokOfficial` 分组**
>
> Grok Imagine 视频不在 `Default` 默认分组。该系列的内容安全策略与平台其它模型差异较大，为避免合规风险我们采取**定向开放**：
>
> * **累计消费满 \$1,000 的存量客户**：联系客服说明用途，核验后开通
> * **其他客户**：通过[企业微信客服](https://work.weixin.qq.com/kfid/kfc9adfd5810ece25ec)提交申请，说明**使用场景**与**内容管控措施**，审核通过后为你单独开通
>
> 令牌分组不含 `GrokOfficial` 时调用会返回 **`503`**，这是权限问题、不是服务故障。详见下方 [分组介绍](#分组介绍)。

> [!WARNING]
>
> **⚠️ 不传 `size` 默认是 480p、8 秒**
>
> 提交时如果不指定分辨率和时长，会按 **480p、8 秒**生成并计费。需要 720p / 1080p 或更短的片子，请显式传 `size`（如 `"1280x720"`）和 `seconds`。

> **[视频生成 API](/api-capabilities/grok-imagine-video/video-generation)**
>
> 文生视频 / 图生视频提交接口，带交互式 Playground。

> **[Grok Imagine 官转生图](/api-capabilities/grok-imagine-image-official/overview)**
>
> 同一个 `GrokOfficial` 分组，与官网同价按档计费的图片生成。

## 让 AI Agent 帮你接入

帮我在当前项目里接入 / 排查 Grok Imagine 视频生成（文生视频 + 图生视频）。

先读文档再动手：抓 [https://docs.apiyi.com/api-capabilities/grok-imagine-video/overview.md](https://docs.apiyi.com/api-capabilities/grok-imagine-video/overview.md) 拿到本页纯文本版；需要更细的参数说明时，video-generation 页同样在地址后加 `.md` 即可。

接入要求：

1. 模型名三选一：`grok-imagine-video`（480p / 720p）、`grok-imagine-video-1.5`（480p / 720p / 1080p）、`grok-imagine-video-1.5-lite`（1.5 轻量版）。令牌分组必须包含 `GrokOfficial`、计费模式为按量优先或按量计费，否则固定返回 503。

2. 异步三步流程：`POST /v1/videos` 提交拿到任务 `id` → 每 5–10 秒 `GET /v1/videos/{id}` 轮询，直到 `status` 为 `completed` 或 `failed` → `GET /v1/videos/{id}/content` 下载 MP4（带同一个 Authorization 头）。轮询总时长上限给到 10 分钟。

3. 分辨率与时长要显式传：`size` 用像素写法（如 `"1280x720"`、`"720x1280"`、`"1920x1080"`），短边决定档位（≥1080 为 1080p、≥720 为 720p、其余 480p），宽高比按最接近的一档取；`seconds` 取 1 到 15。**不传时默认 480p、8 秒，并按此计费。** `grok-imagine-video` 不支持 1080p，传了返回 400。

4. 图生视频：在同一端点加 `input_reference`，值是图片的公网 URL 或 `data:image/...;base64,...`；也可以用 multipart 上传文件，字段名 `input_reference`。输出画幅跟随输入图。

5. 计费：按生成秒数 × 分辨率单价，图生视频每张输入图另收少量费用。关闭音频不降价。

6. 审核：被内容审核拦截的任务 `status` 依然是 `completed`，但没有成片，响应里带 `error.code: "moderation_blocked"`，**并且照常计费**。代码里要判断这个字段，不要当成功处理，也不要无脑重试同一个提示词。

7. 成片在 `completed` 后即可下载，请立即转存到自己的对象存储，不要长期引用。

8. Key 从环境变量 `APIYI_API_KEY` 读，base\_url 用 [https://api.apiyi.com/v1，不要硬编码进代码、也不要提交进](https://api.apiyi.com/v1，不要硬编码进代码、也不要提交进) git。改完真跑一次 2 秒 480p 的文生视频，把成片时长、分辨率和这次调用的花费贴给我。

## 模型与定价

价格与 xAI 官网一致，按**生成视频的秒数**计费，单价由模型与分辨率决定：

| 模型 | 480p | 720p | 1080p | 图生视频输入图 |
| - | - | - | - | - |
| **`grok-imagine-video`** | \$0.05 / 秒 | \$0.07 / 秒 | 不支持 | \$0.002 / 张 |
| **`grok-imagine-video-1.5`** | \$0.08 / 秒 | \$0.14 / 秒 | \$0.25 / 秒 | \$0.01 / 张 |
| **`grok-imagine-video-1.5-lite`** | \$0.02 / 秒 | \$0.03 / 秒 | \$0.14 / 秒 | \$0.01 / 张 |

> [!NOTE]
>
> 模型价格与官网对齐，且可能随官网调整；上表仅供参考，具体以顶部导航「模型价格」栏目为准：[模型价格](/models/index)。

> [!NOTE]
>
> **计费说明与算例**
>
> * **费用 = 秒数 × 分辨率单价 + 输入图张数 × 输入图单价**。例：`grok-imagine-video` 480p 生成 1 秒图生视频 = 1 × \$0.05 + 1 × \$0.002 = **\$0.052**（实测账单一致）。
> * **默认值也计费**：不传 `size` / `seconds` 时按 480p、8 秒生成，`grok-imagine-video` 即 \$0.40 一条。
> * **音频不单独计费**：成片默认带音轨，关闭音频不降价。
> * **审核拦截照常计费**：被 xAI 内容审核拦截的视频，xAI 照样收费，我们按同样口径计费，详见 [常见问题](#常见问题)。
> * 可叠加 [充值阶梯加赠](/faq/recharge-promotions)；用量较大的企业客户可联系商务沟通专属价格。

## 分组介绍

> [!WARNING]
>
> **Grok Imagine 视频不在 `Default` 默认分组。** 本通道放在 **`GrokOfficial` 专属分组（与官网同价，即上方定价表）**，与 [Grok Imagine 官转生图](/api-capabilities/grok-imagine-image-official/overview) 共用一个分组，需申请开通后才能调用。

### 谁可以开通

| 客户类型 | 开通方式 |
| - | - |
| **累计消费满 \$1,000 的存量客户** | 联系客服说明用途，核验后开通 |
| **其他客户** | 提交申请，说明使用场景与内容管控措施，审核通过后单独开通 |

### 怎么申请

**1. 联系企业微信客服**

通过[企业微信客服](https://work.weixin.qq.com/kfid/kfc9adfd5810ece25ec)提交申请，也可发邮件到 [hi@apiyi.com](mailto:hi@apiyi.com)。注明申请的是 **`GrokOfficial`（Grok Imagine 官转）**。

**2. 说明使用场景与内容管控措施**

请写清楚三件事：视频用于什么业务、面向什么终端用户、你这一侧有哪些内容审核与人工复核措施。信息越具体，审核越快。

**3. 开通后切换令牌分组**

审核通过后我们为你的账号开通 `GrokOfficial` 分组。请到[控制台令牌页](https://api.apiyi.com/token)把调用本通道的令牌分组切到 `GrokOfficial`，计费模式选 `按量优先` 或 `按量计费`。

> [!NOTE]
>
> **未开通时的表现**：令牌分组不含 `GrokOfficial` 时调用返回 **`503`（当前分组无可用渠道）**，重试无效，需要先完成开通。
>
> **令牌「计费模式」不要选 `按次计费`**：本通道按秒计费，按次计费的令牌路由不到，同样会返回 503。

> [!NOTE]
>
> **合规提醒**：开通后生成内容的合规责任在调用方。请遵守当地法律法规，不得用于生成违法内容、侵犯他人肖像权与知识产权的内容，或面向未成年人的不当内容；面向 C 端分发的场景建议在你这一侧再加一层审核。相关背景见 [国内产品调用海外模型的合规要点](/faq/overseas-model-compliance)。发现滥用我们会收回该分组权限。

## 技术规格

| 项目 | 规格 |
| - | - |
| 模型 ID | `grok-imagine-video`、`grok-imagine-video-1.5`、`grok-imagine-video-1.5-lite` |
| 能力 | 文生视频、图生视频（1 张输入图） |
| 时长 | `seconds` 1–15 秒，**默认 8 秒** |
| 分辨率 | 480p（默认）/ 720p / 1080p（`grok-imagine-video` 无 1080p） |
| 宽高比 | 由 `size` 换算到最接近的一档：`1:1` / `16:9` / `9:16` / `4:3` / `3:4` / `3:2` / `2:3`；图生视频跟随输入图 |
| 音频 | 默认自带音轨 |
| 生成耗时 | 2 秒 480p 约 20–25 秒；图生视频约 35–50 秒；1.5 的 1080p 约 110 秒 |
| 成片下载 | `completed` 后立即可用 `/v1/videos/{id}/content` 下载 |
| 建议轮询 | 每 5–10 秒一次，总时长上限 10 分钟 |

## 端点一览

| 步骤 | 方法 | 路径 | 说明 |
| - | - | - | - |
| ① 提交任务 | `POST` | `/v1/videos` | `application/json`；图生视频也可用 `multipart/form-data` 上传文件 |
| ② 查询状态 | `GET` | `/v1/videos/{id}` | 返回 `status` / `progress`，完成后带 `seconds` |
| ③ 下载成片 | `GET` | `/v1/videos/{id}/content` | 返回 MP4，需带 Authorization 头 |

> [!TIP]
>
> 主域名 `https://api.apiyi.com`，备用域名 `https://b.apiyi.com`。完整代码示例见 [视频生成 API](/api-capabilities/grok-imagine-video/video-generation)。

### 完整流程（Python）

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

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

# ① 提交：720p 横屏 5 秒
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"]

# ② 轮询
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"):
    # 审核拦截时 status 也是 completed，但带 error.code = moderation_blocked
    raise RuntimeError(job.get("error"))

# ③ 下载成片并立即转存
mp4 = requests.get(f"{BASE}/videos/{vid}/content", headers=H, timeout=300)
open("out.mp4", "wb").write(mp4.content)
```

## 关键参数详解

### `size`（分辨率与宽高比）

`size` 用 `宽x高` 的像素写法，网关按**短边**换算分辨率档，按**宽高比**取最接近的一档：

| `size` 示例 | 换算结果 |
| - | - |
| `"854x480"` | 480p、16:9（实测输出 848×480） |
| `"1280x720"` | 720p、16:9（实测输出 1280×720） |
| `"720x1280"` | 720p、9:16（实测输出 720×1280） |
| `"1920x1080"` | 1080p、16:9（仅 1.5 / 1.5-lite） |

也可以直接传 `"480p"` / `"720p"` / `"1080p"`，或者不用 `size`、改传 xAI 原生字段 `resolution`（`480p` / `720p` / `1080p`）加 `aspect_ratio`（如 `9:16`），两者同时传时以 `resolution` / `aspect_ratio` 为准。都不传时按 **480p** 生成。

> [!WARNING]
>
> `grok-imagine-video` 只支持 480p / 720p，传 1080p 级别的 `size` 会返回 `400`：`grok-imagine-video resolution must be one of 480p, 720p`。

### `seconds`（时长）

取值 **1–15** 的整数，字符串（`"5"`）或数字（`5`）都可以，**默认 8 秒**。超出范围返回 `400`：`duration must be an integer between 1 and 15`。费用与秒数成正比，测试阶段建议用 1–2 秒。

### `input_reference`（图生视频）

传一张输入图即可转为图生视频，三种写法任选：

* 公网图片 URL：`"input_reference": "https://example.com/first-frame.jpg"`
* base64 Data URI：`"input_reference": "data:image/jpeg;base64,/9j/4AAQ..."`
* multipart 上传文件：`-F "input_reference=@first-frame.jpg"`

图生视频时 `prompt` 用来描述动作与镜头（如「猫慢慢转过头」），**输出画幅跟随输入图**。每张输入图另收 \$0.002（`grok-imagine-video`）或 \$0.01（1.5 / 1.5-lite）。

## 最佳实践

**1. 先用 1–2 秒、480p 试提示词**

费用按秒计，先用短时长低分辨率确认画面方向，再出 720p / 1080p 的正式长度。`grok-imagine-video-1.5-lite` 的 480p / 720p 单价最低，适合批量试错。

**2. 每次都显式传 size 和 seconds**

不传会按 480p、8 秒生成并计费，最常见的「怎么这么贵」「怎么这么糊」都来自漏传。

**3. 轮询间隔 5–10 秒，设总超时**

任务一般在 20 秒到 2 分钟内完成。轮询过密没有收益，建议总时长上限 10 分钟，超时后记录任务 ID 便于排查。

**4. 处理审核拦截**

检查查询结果里的 `error.code`：`moderation_blocked` 表示被拦截、没有成片但已计费。换个表述再提交，不要原样重试。

**5. 成片立即转存**

`completed` 后立即用 `/content` 下载到自己的存储，不要把下载链接长期保存或直接给终端用户。

## 错误码与重试

| HTTP / 字段 | 含义 | 处理建议 |
| - | - | - |
| `400` `invalid_request_error` | 参数非法：分辨率不支持、`seconds` 超出 1–15 等，`message` 会写明原因 | 按提示修改，不要重试 |
| `429` | 频率超限或额度不足 | 指数退避重试，并检查账户余额 |
| `503` | 令牌未开通 `GrokOfficial` 分组，或令牌计费模式为按次计费 | **权限问题不是故障**，先按 [分组介绍](#分组介绍) 处理 |
| `status: failed` | 生成失败 | 查看 `error.message`，调整后重新提交 |
| `completed` + `error.code: moderation_blocked` | 被内容审核拦截，无成片，照常计费 | 修改提示词或输入图后再提交 |

## 常见问题

> **调用一直返回 503，是渠道挂了吗？**
>
> 基本是权限问题：令牌分组不含 `GrokOfficial`，或令牌计费模式是「按次计费」。前者按 [分组介绍](#分组介绍) 申请开通；后者把计费模式改成 `按量优先` 或 `按量计费` 即可。

> **为什么我生成的视频是 480p、8 秒？**
>
> 这是默认值：提交时没有传 `size` 和 `seconds`，就按 480p、8 秒生成并计费。请显式传 `size`（如 `"1280x720"`）和 `seconds`。

> **任务显示 completed，但下载不到视频？**
>
> 先看查询结果里有没有 `error.code: "moderation_blocked"`。有的话说明这条视频被 xAI 的内容审核拦截了：任务状态仍是 `completed`，但没有成片，**并且照常计费**（xAI 对被拦截的视频同样收费）。请调整提示词或输入图后重新提交。

> **关掉音频能便宜吗？**
>
> 不能。成片默认带音轨，按 xAI 官方口径，关闭音频不降价。

> **图生视频的输出比例为什么和我传的 size 不一样？**
>
> 图生视频的输出画幅跟随输入图。需要特定比例，请先把输入图裁成目标比例再提交。

> **支持视频编辑、视频延长、多张参考图吗？**
>
> 本通道当前对外开放的是**文生视频**与**单张输入图的图生视频**。视频编辑、视频延长等能力暂未开放，开放后会在本页更新。

> **三个型号怎么选？**
>
> * 要 1080p → `grok-imagine-video-1.5`（画质最好）或 `grok-imagine-video-1.5-lite`（更便宜）
> * 批量出 480p / 720p、控制成本 → `grok-imagine-video-1.5-lite`（\$0.02 / \$0.03 每秒）
> * 已在用基础款、只需 480p / 720p → `grok-imagine-video`

## 相关文档

* [Grok Imagine 视频生成 API](/api-capabilities/grok-imagine-video/video-generation) - 带 Playground 的提交接口参考
* [Grok Imagine 官转生图](/api-capabilities/grok-imagine-image-official/overview) - 同一分组，与官网同价按档计费
* [Grok 系列模型调用指南](/api-capabilities/grok/overview) - xAI 文本模型
* [充值加赠活动](/faq/recharge-promotions)


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