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

# Grok Video 1.5 影片生成

> 使用文字, 首幀或參考圖生成影片

> [!NOTE]
>
> 中國大陸使用者請在範例中使用 `https://toapis.cn` 取代 `https://toapis.com`.

使用 `grok-video-1.5` 請求以下 3 種輸入模式. 模式必須由相容渠道開放後才能使用. 報價成功不代表生成渠道一定可用.

> [!WARNING]
>
> 圖片請使用可公開存取的 `http://` 或 `https://` URL. 本機檔案先透過[圖片上傳 API](https://docs.toapis.com/docs/zh-Hant/api-reference/uploads/images.md)上傳, 不要直接傳送 base64. 上傳後使用 JSON 傳入 URL 可適用於已支援的渠道; 部分渠道不接受 multipart 二進位檔案上傳.

## 生成模式

| 模式 | 輸入 |
| - | - |
| `text_to_video` | 僅提示詞, 不傳圖片 |
| `first_frame_image_to_video` | 恰好 1 張首幀 |
| `reference_images_to_video` | 1-7 張參考圖, 包括單張參考圖 |

新請求建議明確填寫 `video_generation_mode`. 未填寫時沿用舊單圖行為, 只傳 1 張 `reference_images` 不會自動選擇參考圖模式. 文字生成影片模式不能攜帶圖片.

## 認證

**Authorization** `string` *required*

使用 API Key 進行 Bearer Token 認證.

```text theme={null}
Authorization: Bearer YOUR_API_KEY
```

## 請求參數

**model** `string` *required* (default: grok-video-1.5)

使用公開模型名稱 `grok-video-1.5`, 不要替換為供應商模型名稱.

**prompt** `string`

描述場景和運動. 文字生成影片和參考圖模式必填. 部分舊單首幀請求可以省略, 其他首幀請求仍可能要求此欄位. 新接入建議始終提供非空提示詞.

**video\_generation\_mode** `string`

舊客戶端可以省略. 依實際輸入選值: 純文字填 `text_to_video`, 恰好 1 張首幀填 `first_frame_image_to_video`, 1-7 張參考圖填 `reference_images_to_video`. 模式必須與 `image`, `input_reference` 或 `reference_images` 的實際輸入一致, 不匹配會被拒絕. 單張參考圖必須明確指定參考圖模式, 才能與舊單首幀輸入區分.

**image** `string`

首幀 URL. 首幀模式必須填寫, 也可以改用 `input_reference`. 文字生成影片和純參考圖模式不填寫. 上游對首幀的實際處理取決於渠道.

**input\_reference** `string`

首幀 URL 的字串別名. 使用 `image` 或 `input_reference` 其中一個, 不要同時傳入不同值. 新請求使用此別名時也應明確指定模式.

**reference\_images** `array`

1-7 張參考圖 URL, 支援字串陣列或 `{"url":"https://example.com/reference.jpg"}` 物件陣列. 參考圖模式必填. 保留舊 `image_urls` 和 `images` 別名, 但不要同時傳入內容不同的多組清單.

**duration** `integer`

整數秒數, 建議明確填寫. 支援 1-15 秒.

**resolution** `string`

參考圖模式使用 `480p` 或 `720p`. 文字生成影片和首幀模式可在渠道支援時使用 `1080p`. 本頁範例均明確指定 `720p`.

**aspect\_ratio** `string`

影片畫面比例, 如 `16:9`. 常用值為 `1:1`, `16:9`, `9:16`, `3:2` 和 `2:3`, 具體取決於渠道支援範圍.

## 相容性限制

部分渠道對單首幀和單參考圖採用相同的處理方式, 模式名稱不保證嚴格的首幀控制. 開放模式不會豁免協定限制. 不支援的輸入可能在提交前被拒絕; 沒有符合條件且已開放的渠道時無法生成任務.

## 價格

影片價格以目前帳戶和 SKU 設定為準. 請查看[即時價格](https://toapis.com/pricing)以及對應參數的登入報價, 本頁不承諾固定每秒價格.

## 建立影片任務

範例均明確指定模式, 時長和解析度. 圖片 URL 需替換為實際可存取的位址.

```bash cURL theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "grok-video-1.5",
  "prompt": "A cinematic product shot with a slow camera push-in",
  "video_generation_mode": "text_to_video",
  "duration": 8,
  "resolution": "720p",
  "aspect_ratio": "16:9"
}'
```

```python Python theme={null}
import requests

response = requests.post(
    "https://toapis.com/v1/videos/generations",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "model": "grok-video-1.5",
        "prompt": "A cinematic product shot with a slow camera push-in",
        "video_generation_mode": "first_frame_image_to_video",
        "image": "https://example.com/first-frame.jpg",
        "duration": 8,
        "resolution": "720p",
        "aspect_ratio": "16:9"
    },
)
response.raise_for_status()
print(response.json()["id"])
```

### 參考圖範例

```json theme={null}
{
  "model": "grok-video-1.5",
  "prompt": "A cinematic product shot with a slow camera push-in",
  "video_generation_mode": "reference_images_to_video",
  "reference_images": [
    "https://example.com/reference-a.jpg",
    "https://example.com/reference-b.jpg"
  ],
  "duration": 8,
  "resolution": "720p",
  "aspect_ratio": "16:9"
}
```

## 回應

**id** `string`

用於輪詢的任務 ID.

**object** `string`

物件類型為 `generation.task`.

**model** `string`

本次請求的公開模型名稱.

**status** `string`

任務狀態: `queued`, `in_progress`, `completed` 或 `failed`.

```json 200 theme={null}
{
  "id": "video_abc123def456",
  "object": "generation.task",
  "model": "grok-video-1.5",
  "status": "queued",
  "progress": 0,
  "created_at": 1768380224,
  "metadata": {}
}
```

## 查詢任務狀態

使用回傳的 `id` 呼叫[影片任務狀態 API](https://docs.toapis.com/docs/zh-Hant/api-reference/tasks/video-status.md).


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