> ## 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](/zh-Hant/api-capabilities/grok-imagine-video/video-generation)**
>
> 文生影片 / 圖生影片提交介面，帶互動式 Playground。

> **[Grok Imagine 官轉生圖](/zh-Hant/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]
>
> 模型價格與官網對齊，且可能隨官網調整；上表僅供參考，具體以頂部導航「模型價格」欄目為準：[模型價格](/zh-Hant/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 照樣收費，我們按同樣口徑計費，詳見 [常見問題](#常見問題)。
> * 可疊加 [充值階梯加贈](/zh-Hant/faq/recharge-promotions)；用量較大的企業客戶可聯絡商務溝通專屬價格。

## 分組介紹

> [!WARNING]
>
> **Grok Imagine 影片不在 `Default` 預設分組。** 本通道放在 **`GrokOfficial` 專屬分組（與官網同價，即上方定價表）**，與 [Grok Imagine 官轉生圖](/zh-Hant/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 端分發的場景建議在你這一側再加一層稽核。相關背景見 [國內產品呼叫海外模型的合規要點](/zh-Hant/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](/zh-Hant/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](/zh-Hant/api-capabilities/grok-imagine-video/video-generation) - 帶 Playground 的提交介面參考
* [Grok Imagine 官轉生圖](/zh-Hant/api-capabilities/grok-imagine-image-official/overview) - 同一分組，與官網同價按檔計費
* [Grok 系列模型呼叫指南](/zh-Hant/api-capabilities/grok/overview) - xAI 文本模型
* [充值加贈活動](/zh-Hant/faq/recharge-promotions)


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