> ## 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 影片模型
> xAI 在 WideRouter 上的兩個影片模型：生成、編輯與延長片段，以及時長、解析度、參考圖與預設音色。
Grok Imagine 系列裡有兩個模型出影片。兩個都走[非同步任務 API](/zh-Hant/api/async-tasks)，
信封與其他模型一致——**影片沒有同步介面**，這是唯一的呼叫方式。
這兩個不是簡單的新舊關係。`grok-imagine-video-1.5` 解析度更高、能用預設音色；
而 `grok-imagine-video` 是唯一**接受影片作為輸入**的，編輯和延長都要靠它。
用哪個取決於你是要造一段片子，還是要改一段現成的。
## 系列總覽
| | Grok Imagine Video 1.5 | Grok Imagine Video |
| ---------- | ----------------------------- | -------------------- |
| **模型 ID** | `grok-imagine-video-1.5` | `grok-imagine-video` |
| 文生影片 | 支援 | 支援 |
| 圖生影片（首幀） | 支援 | 支援 |
| 參考圖 | 支援，最多 3 張 | 支援，最多 3 張 |
| **編輯已有片段** | 不支援 | **支援** |
| **延長已有片段** | 不支援 | **支援** |
| 解析度 | `480p` / `720p` / **`1080p`** | `480p` / `720p` |
| 預設音色 | **支援**，最多 3 個 | 不支援 |
| 靜音輸出 | 支援 | 支援 |
| 時長 | 1–15 秒 | 1–15 秒 |
向一個模型要它做不到的事，會在提交時就被拒、不會入隊，而且訊息會告訴你該換哪個：
```json theme={null}
{
"error": {
"code": "invalid_params",
"message": "edit needs a model that takes video input; use grok-imagine-video",
"param": "input.mode"
}
}
```
## 三種模式
`input.mode` 決定模型做什麼，取 `generate`、`edit` 或 `extend`，預設 `generate`。
| `mode` | 需要 `input.video` | 產物時長 | 支援的模型 |
| ---------- | ---------------- | -------------------- | ---------------------- |
| `generate` | 否 | `duration` 再加 0.04 秒 | 兩個都行 |
| `edit` | 是 | **繼承源片長度** | 僅 `grok-imagine-video` |
| `extend` | 是 | 源片加 `duration` | 僅 `grok-imagine-video` |
`edit` 按提示詞改寫一段現成的片子並保持長度，所以它不接受 `resolution`——
輸出跟隨源片。`extend` 是在末尾接一段新畫面。
```json theme={null}
{
"model": "grok-imagine-video",
"input": {
"prompt": "the camera slowly pulls back",
"mode": "extend",
"video": "https://example.com/boat.mp4",
"duration": 3
}
}
```
實測：3.04 秒的源片配 `duration: 3`，產出 **6.04 秒**——原片加三秒延長段，
不是重新渲染。
**`extend` 模式下 `duration` 的範圍會收窄。** 契約層接受 1–15 秒，
但延長段實際只允許 **2–10 秒**，而且源片本身必須**至少 2 秒**。
這兩條都不在提交時校驗，所以都是任務入隊之後才以失敗形式回來：
`Duration must be between 2 and 10 seconds` · `Input video must be at least 2 seconds long, got 1.0s`
## 參數
下面這些都放在 `input` 裡。信封見[非同步任務 API](/zh-Hant/api/async-tasks)。
| 欄位 | 型別 | 預設 | 說明 |
| ------------------ | --------- | ---------- | ------------------------------------------------------- |
| `prompt` | string | — | 必填。 |
| `mode` | string | `generate` | `generate`、`edit` 或 `extend`。 |
| `duration` | integer | 模型預設 | 1–15 秒。`extend` 見上面的提醒。 |
| `resolution` | string | `480p` | `480p`、`720p`，`1080p` 僅 1.5。`edit` 模式下不接受。 |
| `aspect_ratio` | string | `16:9` | 取 `1:1` `16:9` `9:16` `4:3` `3:4` `3:2` `2:3` 之一。 |
| `images` | string\[] | — | 恰好一張圖，作為**首幀**。 |
| `video` | string | — | `edit` 與 `extend` 的源片。`https` URL 或 base64 影片 data URI。 |
| `reference_images` | string\[] | — | 最多 3 張，模型從中取風格與主體。不能與 `images` 同時給。 |
| `voice_ids` | string\[] | — | 最多 3 個預設音色，僅 `grok-imagine-video-1.5`。 |
| `generate_audio` | boolean | `true` | 傳 `false` 出靜音片段，不影響價格。 |
沒有 `n`——影片模型每個任務只產一段。
和影像模型不同，影片**沒有 `auto` 畫幅**，也沒有超寬比例。上面七個就是全部。
## 解析度與時長
實測輸出畫素，每檔一個樣本：
| `resolution` | `aspect_ratio` | 輸出 |
| ------------ | -------------- | ----------- |
| `480p` | `16:9`（預設） | 848 × 480 |
| `480p` | `9:16` | 480 × 848 |
| `720p` | `16:9` | 1280 × 720 |
| `1080p` | `16:9` | 1920 × 1088 |
`1080p` 在 `grok-imagine-video` 上會被拒：
`1080p is only available on grok-imagine-video-1.5`。
**產物比請求的時長多約 0.04 秒**——要 3 秒，檔案是 3.04 秒。
每個樣本都是這樣，且不影響計費，計費按請求的時長算。
## 參考圖、首幀與音色
能喂進去的有三樣東西，其中兩樣互斥：
* **`images`** 是**首幀**。恰好一張，片子從這一幀往後動。
* **`reference_images`** 是風格與主體參考，最多三張。兩個模型都接受，
而且一旦用了，**輸出封頂 `720p`**——`reference_images` 配 `1080p` 會被拒：
`reference images are capped at 720p`。
* 兩個同時給會被拒：
`cannot be combined with images; a first frame and reference images are different modes`。
`voice_ids` 在 `grok-imagine-video-1.5` 上選預設音色，每段最多三個。合法取值：
| | | | | | |
| -------- | --------- | -------- | -------- | -------- | -------- |
| `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` | | | | |
WideRouter 上沒有自定義音色。注意音色 ID 本身**不在提交時校驗**——寫錯的名字會被
接受，然後任務失敗。音色和 `generate_audio: false` 都不改變價格。
## 計價
這幾個模型走 **`Grok-Official`** 分組。WideRouter 的標價與 xAI 官方價完全一致——
折扣體現在**分組倍率**上，`Grok-Official` 的倍率是 `0.8`。所以實際扣費是：
```
原價 × 分組倍率 = 扣費
```
影片**按產物的每秒計價**，解析度決定單價。下面是標價：
| 模型 | `480p` | `720p` | `1080p` |
| ------------------------ | ---------- | ---------- | ---------- |
| `grok-imagine-video-1.5` | \$0.08 / 秒 | \$0.14 / 秒 | \$0.25 / 秒 |
| `grok-imagine-video` | \$0.05 / 秒 | \$0.07 / 秒 | 不支援 |
有三條規則是光看每秒單價看不出來的：
* **你送進去的媒體也要收費。** 一張參考圖約 \$0.01；`edit` 與 `extend` 的源片
按它自己的長度算，每秒約 \$0.01。
* **`extend` 不對原片重複收費。** 只有新增的那一段按每秒單價計，再加源片作為輸入。
實測：把一段 3.04 秒的片子延長 3 秒花了 \$0.18——三秒輸出按 \$0.05
加上 3.04 秒輸入按 \$0.01——而結果是 6.04 秒。從頭生成六秒要 \$0.30。
* **`edit` 大約按源片長度收兩遍**，一遍算輸出一遍算輸入。
實測：編輯一段 1.04 秒的片子花了 \$0.06。
完整算一遍。`grok-imagine-video` 出三秒 `480p`：
```
\$0.05 / 秒 × 3 秒 = \$0.15 原價
\$0.15 × 0.8 = \$0.12 Grok-Official 實扣
```
完成的任務裡帶一個 `usage.cost_in_usd_ticks` 欄位，`10000000000` ticks 等於 \$1。
這個數字是**原價**，還沒乘分組倍率。乘上你所在分組的倍率，才是實際從餘額里扣掉的數。
## 時延
非同步介面上從提交到 `completed` 的端到端實測：
| 請求 | 端到端 |
| ------------------------------------ | ------- |
| `grok-imagine-video`，`480p`，1 秒 | 19 秒 |
| `grok-imagine-video-1.5`，`480p`，1 秒 | 21 秒 |
| `grok-imagine-video`，`480p`，3 秒 | 21–30 秒 |
| `grok-imagine-video`，編輯一段 1 秒的片子 | 30 秒 |
| `grok-imagine-video`，延長 3 秒 | 30 秒 |
| `grok-imagine-video-1.5`，`1080p`，3 秒 | 約 48 秒 |
| `grok-imagine-video-1.5`，`480p`，15 秒 | 約 51 秒 |
比人們常說的「影片模型通常要幾分鐘」快得多，但仍然慢到不能掛連線等——
這正是它沒有同步端點的原因。每兩三秒輪詢一次，客戶端超時按這張表最慢的那一行設，
不要按最快的設。
## 任務失敗時
影片的失敗是一個 `failed` 狀態的任務加一個 `error` 物件，不是 HTTP 錯誤——
查詢端點仍然返回 `200`。常見的 code 是 `upstream_error`，訊息由 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"
}
}
```
在生成開始之前就失敗的很快——輸入取不到是一秒以內，
上游模型自己的約束判定大約六秒。
## 下一步
在瀏覽器裡真實提交一個影片任務並輪詢到完成。
這個系列的影像那一半——三個變體與品質檔位。